diff --git a/.ccignore b/.ccignore
new file mode 100644
index 000000000..14561791f
--- /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 000000000..3c767fc54
--- /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 000000000..afc82c2ea
--- /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 000000000..2542ee68f
--- /dev/null
+++ b/.claude/skills/code-review/SKILL.md
@@ -0,0 +1,94 @@
+---
+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.
+
+### 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 000000000..4193f6144
--- /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/.coderabbit.yaml b/.coderabbit.yaml
new file mode 100644
index 000000000..b7937d760
--- /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 000000000..ccbc829ec
--- /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 000000000..267df6812
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,73 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior in FastMCP
+labels: [bug, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for contributing to FastMCP! 🙏
+
+  - type: markdown
+    attributes:
+      value: |
+        ### Before you submit
+
+        To help us help you, please:
+
+        - 🔄 **Make sure you're testing on the latest version of FastMCP** - many issues are already fixed in newer versions
+        - 🔍 **Check if someone else has already reported this issue** or if it's been fixed on the main branch
+        - 📋 **You MUST include a copy/pasteable and properly formatted MRE** (minimal reproducible example) below 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 a 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 or proposed fix. We have LLMs too, and an incorrect analysis is harder to work with than none at all.
+        - ✂️ **Keep it short.** A one-paragraph description and a working MRE is the ideal bug report. Issues that are difficult to parse — due to length, speculation, or generated content — may be closed without response.
+
+        Thanks for helping to make FastMCP better! 🚀
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: |
+        Please explain what you're experiencing and what you would expect to happen instead.
+
+        Provide as much detail as possible to help us understand and solve your problem quickly.
+    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 000000000..7c4bef52e
--- /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 000000000..a803ec399
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/enhancement.yml
@@ -0,0 +1,35 @@
+name: 💡 Enhancement Request
+description: Suggest an idea or improvement for FastMCP
+labels: [enhancement, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for contributing to FastMCP! 🙏
+
+  - type: markdown
+    attributes:
+      value: |
+        ### Before you submit
+
+        To help us evaluate your enhancement request:
+
+        - 🔍 **Check if this has already been requested** - search existing issues first
+        - 💭 **Think about the broader impact** - how would this affect other users?
+        - 📋 **Consider implementation complexity** - is this a small change or a major feature?
+        - ✂️ **Keep it short.** Describe the problem you're trying to solve and why existing behavior falls short. Skip proposed implementations unless you have a specific, well-considered suggestion — we don't need LLM-generated API designs. Requests that are difficult to parse may be closed without response.
+
+        Thanks for helping to make FastMCP better! 🚀
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Enhancement
+      description: |
+        Please describe the enhancement:
+
+        - What problem or use case would it solve?
+        - How would it improve your workflow or experience with FastMCP?
+        - Are there any alternative solutions you've considered?
+    validations:
+      required: true
diff --git a/.github/actions/run-claude/action.yml b/.github/actions/run-claude/action.yml
new file mode 100644
index 000000000..fff6788a6
--- /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 000000000..ff429a4cc
--- /dev/null
+++ b/.github/actions/run-pytest/action.yml
@@ -0,0 +1,44 @@
+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, or client_process"
+    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"
+        else
+          MARKER="not integration and not client_process"
+          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 \
+          -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 000000000..0becaffad
--- /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/ai-labeler.yml b/.github/ai-labeler.yml
deleted file mode 100644
index 23a7dc1d3..000000000
--- a/.github/ai-labeler.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-context-files:
-  - README.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 000000000..be77ac83a
--- /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 000000000..20d3ccecf
--- /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 000000000..68212c72f
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,28 @@
+## Description
+<!-- 
+Please provide a clear and concise description of the changes made in this pull request.
+
+Using AI to generate code? Please include a note in the description with which AI tool you used.
+-->
+
+**Contributors Checklist**
+<!--
+NOTE:
+1. You must create an issue in the repository before making a Pull Request.
+2. You must not create a Pull Request for an issue that is already assigned to someone else.
+
+If you do not follow these steps, your Pull Request will be closed without review.
+-->
+
+- [ ] My change closes #(issue number)
+- [ ] I have followed the repository's development workflow
+- [ ] I have tested my changes manually and by adding relevant tests
+- [ ] I have performed all required documentation updates
+
+**Review Checklist**
+<!-- Your Pull Request will not be reviewed if tests are failing, you have not self-reviewed your changes, or you have not checked all of the following: -->
+
+- [ ] I have self-reviewed my changes
+- [ ] My Pull Request is ready for review
+
+---
diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 000000000..5ff95aace
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,47 @@
+changelog:
+  exclude:
+    labels:
+      - ignore in release notes
+
+  categories:
+    - title: New Features 🎉
+      labels:
+        - feature
+
+    - title: Enhancements 🔧
+      labels:
+        - enhancement
+      exclude:
+        labels:
+          - breaking change
+
+    - title: Fixes 🐞
+      labels:
+        - bug
+      exclude:
+        labels:
+          - contrib
+
+    - title: Breaking Changes 🛫
+      labels:
+        - breaking change
+      exclude:
+        labels:
+          - contrib
+
+    - title: Docs 📚
+      labels:
+        - documentation
+
+    - title: Examples & Contrib 💡
+      labels:
+        - example
+        - contrib
+
+    - title: Dependencies 📦
+      labels:
+        - dependencies
+
+    - 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 000000000..2e1f4b35d
--- /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 000000000..5dc08c239
--- /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 000000000..d571f6757
--- /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 000000000..4448e0012
--- /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 000000000..10fa05f16
--- /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 000000000..04b73fbf6
--- /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 000000000..48c0b6888
--- /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/ai-labeler.yml b/.github/workflows/ai-labeler.yml
deleted file mode 100644
index 41d5853fe..000000000
--- a/.github/workflows/ai-labeler.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-name: AI Labeler
-
-on:
-  issues:
-    types: [opened, reopened]
-  issue_comment:
-    types: [created]
-  pull_request:
-    types: [opened, reopened]
-
-jobs:
-  ai-labeler:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: jlowin/ai-labeler@v0.5.0
-        with:
-          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
-          controlflow-llm-model: openai/gpt-4o-mini
diff --git a/.github/workflows/auto-close-duplicates.yml b/.github/workflows/auto-close-duplicates.yml
new file mode 100644
index 000000000..d358a3a1e
--- /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@v6
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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 000000000..4338c58d8
--- /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@v6
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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 000000000..9f7724fbd
--- /dev/null
+++ b/.github/workflows/martian-test-failure.yml
@@ -0,0 +1,185 @@
+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@v6
+        with:
+          fetch-depth: 1
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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)
+
+          # 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. Your comment should include:
+
+          ## Test Failure Analysis
+
+          **Summary**: A brief 1-2 sentence summary of what failed.
+
+          **Root Cause**: A clear explanation of why the tests failed, based on your analysis of the logs and code.
+
+          **Suggested Solution**: Specific, actionable steps to fix the failure(s). Include:
+          - Which files need to be modified
+          - What changes are needed
+          - Why these changes will fix the issue
+
+          <details>
+          <summary>Detailed Analysis</summary>
+
+          Include here:
+          - Relevant log excerpts showing the failure
+          - Code snippets that are causing the issue
+          - Any related issues or PRs that might be relevant
+          </details>
+
+          <details>
+          <summary>Related Files</summary>
+
+          List files that are relevant to the failure with brief explanations of their relevance.
+          </details>
+
+          # Important Guidelines
+          - Be concise and actionable - developers want to quickly understand and fix the issue. Provide
+            additional context, references, etc in collapsible details blocks to ensure that the comment you're adding
+            is short and easy to read but additional information is a click away.
+          - Focus on facts from the logs and code, not speculation
+          - If you can't determine the root cause, say so clearly
+          - If your only suggestion is a bad suggestion (disable the test, change the timeout, etc), indicate that you've run out of ideas and
+            that they probably don't want to do that.
+          - Provide specific file names, line numbers, and code references when possible
+          - 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
+
+          # CRITICAL: ANGRY USERS
+          **IMPORTANT**: If the user is angry with you, the triage bot, don't respond. Just exit immediately without further action.
+            If at any point in the conversation the user has asked you to stop replying to the thread, just exit immediately.
+
+          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.
+
+          # 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 000000000..4c7ef711e
--- /dev/null
+++ b/.github/workflows/martian-triage-issue.yml
@@ -0,0 +1,205 @@
+# 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@v6
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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
+        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: ${{ github.event.issue.title }}
+            Issue Author: ${{ github.event.issue.user.login }}
+            </context>
+
+            <issue_body>
+            ${{ github.event.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)
+            </response_goals>
+
+            <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.
+
+            When formulating your response, you will never "bury the lede", you will always provide a clear and concise tl;dr as the first thing in your response. As your response grows in length you can organize the more detailed parts of your response collapsible sections using <details> and <summary> tags. You shouldn't put everything in collapsible sections, especially if the response is short. Use your discretion to determine when to use collapsible sections to avoid overwhelming the reader with too much detail -- think of them like an appendix that can be expanded if the reader is interested.
+
+            </response_sections>
+            <response_examples>
+            # Example output for "Recommendation" part of the response
+            PR #654 already implements the requested feature but is incomplete. The Pull Request is not in a mergeable state yet, the remaining work should be completed: 1) update the Calculator.divide method to utilize the new DivisionByZeroError or the safe_divide function, and 2) update the tests to ensure that the Calculator.divide method raises the new DivisionByZeroError when the divisor is 0.
+
+            <details>
+            <summary>Findings</summary>
+            ...details from the code analysis that are relevant to the issue and the recommendation...
+            </details>
+
+            <details>
+            <summary>Verification</summary>
+            I ran the existing tests (if execution commands are available in `<allowed_tools>`) and confirmed the current behavior:
+            ```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>Detailed Action Plan</summary>
+            ...a detailed plan that a junior developer could follow to implement the recommendation...
+            </details>
+
+            # Example Output for "Related Items" part of the response
+
+            <details>
+            <summary>Related Issues and Pull Requests</summary>
+
+            | Repository | Issue or PR | Relevance |
+            | --- | --- | --- |
+            | PrefectHQ/fastmcp | [Add matrix operations support](https://github.com/PrefectHQ/fastmcp/pull/680) | This pull request directly addresses the feature request for adding matrix operations to the calculator. |
+            | PrefectHQ/fastmcp | [Add matrix operations support](https://github.com/PrefectHQ/fastmcp/issues/681) | This issue directly addresses the feature request for adding matrix operations to the calculator. |
+            </details>
+
+            <details>
+            <summary>Related Files</summary>
+
+            | Repository | File | Relevance | Sections |
+            | --- | --- | --- | --- |
+            | modelcontextprotocol/python-sdk | [test_calculator.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/test_calculator.py) | This file contains the test cases for the Calculator class, including a test that specifically asserts a ValueError is raised for division by zero, confirming the current intended behavior. | [25-27](https://github.com/modelcontextprotocol/python-sdk/blob/main/test_calculator.py#L25-L27) |
+            | modelcontextprotocol/python-sdk | [calculator.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/calculator.py) | This file contains the implementation of the Calculator class, specifically the `divide` method which raises the ValueError when dividing by zero, matching the bug report. | [29-32](https://github.com/modelcontextprotocol/python-sdk/blob/main/calculator.py#L29-L32) |
+            </details>
+
+            <details>
+            <summary>Related Webpages</summary>
+
+            | Name | URL | Relevance |
+            | --- | --- | --- |
+            | Handling Division by Zero Best Practices | https://my-blog-about-division-by-zero.com/handling+division+by+zero+in+calculator | This webpage provides general best practices for handling division by zero in calculator applications and in Python, which is directly relevant to the issue and potential solutions. |
+            </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.
+            </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 000000000..8d297a226
--- /dev/null
+++ b/.github/workflows/marvin-comment-on-issue.yml
@@ -0,0 +1,142 @@
+# 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@v6
+
+      - 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: Run prek
+        uses: j178/prek-action@v1
+        env:
+          SKIP: no-commit-to-branch
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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
+        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: ${{ github.event.issue.title }}
+            Issue Author: ${{ github.event.issue.user.login }}
+            Comment Author: ${{ github.event.comment.user.login }}
+            </context>
+
+            <user_request>
+            ${{ github.event.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
+            You CAN: 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 (make changes locally to test, cannot push)
+            - Suggest solutions or workarounds
+            - Provide code examples
+            - Help clarify requirements
+            - Link to relevant documentation or code
+            </common_tasks>
+
+            <response_guidelines>
+            - Be concise and actionable
+            - If the request is unclear, ask clarifying questions
+            - If the request requires actions you cannot perform (like pushing changes), explain what you can and cannot do
+            - When making code changes, explain that they are local only and cannot be pushed
+            </response_guidelines>
+
+            <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 000000000..09f699522
--- /dev/null
+++ b/.github/workflows/marvin-comment-on-pr.yml
@@ -0,0 +1,284 @@
+# 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@v6
+        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: Run prek
+        uses: j178/prek-action@v1
+        env:
+          SKIP: no-commit-to-branch
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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
+        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: ${{ github.event.issue.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>
+            ${{ github.event.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>
+            This workflow allows read, write, and execute capabilities but cannot push changes.
+
+            You CAN: Read/analyze code, modify files, write code, run tests, execute commands, resolve review threads
+            You CANNOT: Commit code, push changes, create branches, checkout branches, create pull requests
+
+            **Important**: You cannot push changes to the repository - you can only make changes locally and provide feedback or 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 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 (make changes locally, cannot push)
+            - Answer questions about the changes
+            - Make additional code changes (local only)
+            - Resolve review threads after addressing feedback (if changes are made separately)
+            - 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>
+            </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: Since you cannot push changes, you can resolve threads to acknowledge feedback, but actual fixes would need to be applied separately.
+            </review_thread_tools>
+
+            <response_guidelines>
+            - Be concise and actionable
+            - If the request is unclear, ask clarifying questions
+            - If the request requires actions you cannot perform (like pushing changes), explain what you can and cannot do
+            - When making code changes, explain that they are local only and cannot be pushed
+
+            **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>
+
+            <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 000000000..a71c590c0
--- /dev/null
+++ b/.github/workflows/marvin-dedupe-issues.yml
@@ -0,0 +1,116 @@
+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@v6
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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 }}.
+
+          Follow these steps precisely:
+
+          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. Then, launch 3 parallel agents using the Task tool to search GitHub for duplicates of this issue, using diverse keywords and search approaches, using the summary from step 2
+
+          4. Next, consider the results from steps 2 and 3 and filter out false positives that are likely not actually duplicates of the original issue. Be conservative — only flag issues that describe the same underlying problem, not issues that merely share keywords or involve the same subsystem. If there are no duplicates remaining, do not proceed.
+
+          5. Finally, comment back on the issue with a list of up to three duplicate issues (or zero, if there are no likely duplicates). If there are no duplicates, DO NOT COMMENT. Just exit. 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 (eg. don't use other MCP servers, file edit, etc.)
+          - Make a todo list first
+          - Never include this issue as a duplicate of itself
+
+          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 000000000..8a3f5f47d
--- /dev/null
+++ b/.github/workflows/marvin-label-triage.yml
@@ -0,0 +1,149 @@
+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@v6
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v2
+        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 ONLY action should be to apply labels using mcp__github__update_issue. DO NOT post any comments.
+
+          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):
+          - 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
+          - good first issue: ONLY if it's clearly scoped, has obvious solution, and touches limited files
+          - invalid: Spam, completely off-topic, or nonsensical (often LLM-generated)
+
+          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 src/contrib/
+          - tests: Issues primarily about testing infrastructure, CI/CD workflows, or test coverage
+
+          IMPORTANT LABELING RULES:
+          - Be selective - only apply labels that are clearly relevant
+          - Don't apply area labels just because a file in that area is mentioned
+          - The issue must be PRIMARILY about that area to get the label
+          - When in doubt, don't apply the label
+          - Apply 2-5 labels total typically (category + maybe priority + maybe 1-2 areas)
+
+          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
+          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__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 000000000..0c34bc26f
--- /dev/null
+++ b/.github/workflows/minimize-resolved-reviews.yml
@@ -0,0 +1,43 @@
+# 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]
+
+concurrency:
+  group: minimize-reviews-${{ github.event.pull_request.number || github.event.issue.number }}
+  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.yml b/.github/workflows/publish.yml
index e51173c31..5f2fe8d53 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -5,28 +5,22 @@ on:
   workflow_dispatch:
 
 jobs:
-  publish-pypi-release:
+  pypi-publish:
+    name: Upload to PyPI
     runs-on: ubuntu-latest
-    environment: release
     permissions:
-      contents: write
-      id-token: write
+      id-token: write # For PyPI's trusted publishing
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/checkout@v6
         with:
-          python-version: "3.11"
-          cache: pip
-          cache-dependency-path: "**/pyproject.toml"
-      - name: Install dependencies
-        run: |
-          pip install setuptools wheel build
+          fetch-depth: 0
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v7
+
       - name: Build
-        run: |
-          python -m build
-      - name: Publish
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          verbose: true
+        run: uv build
+
+      - name: Publish to PyPi
+        run: uv publish -v dist/*
diff --git a/.github/workflows/run-static.yml b/.github/workflows/run-static.yml
new file mode 100644
index 000000000..7acc3aac6
--- /dev/null
+++ b/.github/workflows/run-static.yml
@@ -0,0 +1,40 @@
+name: Run static analysis
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".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@v6
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Run prek
+        uses: j178/prek-action@v1
+        env:
+          SKIP: no-commit-to-branch
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
index 86609284e..7799e7aa2 100644
--- a/.github/workflows/run-tests.yml
+++ b/.github/workflows/run-tests.yml
@@ -1,13 +1,21 @@
-name: Run tests
+name: Tests
 
 env:
-  # enable colored output
   PY_COLORS: 1
 
 on:
   push:
     branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
   pull_request:
+
   workflow_dispatch:
 
 permissions:
@@ -15,21 +23,74 @@ permissions:
 
 jobs:
   run_tests:
-    name: 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@v6
+
+      - 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@v4
+      - uses: actions/checkout@v6
+
+      - name: Setup uv (lowest-direct)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: lowest-direct
+
+      - name: Run unit tests
+        uses: ./.github/actions/run-pytest
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
+      - name: Run client process tests
+        uses: ./.github/actions/run-pytest
+        with:
+          test-type: client_process
 
-      - name: Set up Python
-        run: uv python install 3.11
+  run_integration_tests:
+    name: "Integration tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
 
-      - name: Install FastMCP
-        run: uv sync --all-extras --dev
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
 
-      - name: Run tests
-        run: uv run pytest -vv
-        if: ${{ !(github.event.pull_request.head.repo.fork) }}
+      - 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 }}
diff --git a/.github/workflows/run-upgrade-checks.yml b/.github/workflows/run-upgrade-checks.yml
new file mode 100644
index 000000000..3a8162129
--- /dev/null
+++ b/.github/workflows/run-upgrade-checks.yml
@@ -0,0 +1,133 @@
+name: Upgrade checks
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".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@v6
+
+      - name: Setup uv (upgrade)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: upgrade
+
+      - name: Run prek
+        uses: j178/prek-action@v1
+        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@v6
+
+      - 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@v6
+
+      - 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-failure"
+          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.*
diff --git a/.github/workflows/update-config-schema.yml b/.github/workflows/update-config-schema.yml
new file mode 100644
index 000000000..ed66ea209
--- /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:
+      - "src/fastmcp/utilities/mcp_server_config/**"
+      - "!src/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@v2
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        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('src/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 `src/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 000000000..6ca5eb61d
--- /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:
+      - "src/**"
+      - "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@v2
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        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@v3
+
+      - 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
index 4021cf770..7791fb4ca 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,14 +1,82 @@
 # Python-generated files
 __pycache__/
-*.py[oc]
+*.py[cod]
+*$py.class
 build/
 dist/
 wheels/
-*.egg-info
+*.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
+
+# Agents
+/PLAN.md
+/TODO.md
+/STATUS.md
+plans/
+
+# Node / admin-ui
+node_modules/
 
-src/fastmcp/_version.py
\ No newline at end of file
+# 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 000000000..dd3574432
--- /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/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    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: ^src/|^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 000000000..681311eb9
--- /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 000000000..a27089e19
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,120 @@
+# 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                                |
+| ----------------- | -------------------------------------- |
+| `src/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/`)
+
+## Development Rules
+
+### Git & CI
+
+- Prek hooks are required (run automatically on commits)
+- Never amend commits to fix prek failures
+- Apply PR labels: bugs/breaking/enhancements/features
+- 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.
+
+### 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 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
+
+- **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 `src/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 `src/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
+
+## 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 000000000..026b0a2cd
--- /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/LICENSE b/LICENSE
new file mode 100644
index 000000000..f49a4e16e
--- /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
index 7a5925e54..a5c7cd1fd 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,38 @@
-# FastMCP
+<div align="center">
 
-> **Note**: This is experimental software. The Model Context Protocol itself is only a few days old and the specification is still evolving.
+<!-- omit in toc -->
 
-A fast, pythonic way to build Model Context Protocol (MCP) servers.
+<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>
 
-The Model Context Protocol is an extremely powerful way to give LLMs access to tools and resources. However, building MCP servers can be difficult and cumbersome. FastMCP provides a simple, intuitive interface for creating MCP servers in Python.
+# FastMCP 🚀
 
-## Installation
-
-MCP servers require you to use [uv](https://github.com/astral-sh/uv) as your dependency manager.
-
-
-Install uv with brew:
-```bash
-brew install uv
-```
-*(Editor's note: I was unable to get MCP servers working unless uv was installed with brew.)*
+<strong>Move fast and make things.</strong>
 
-Install FastMCP:
-```bash
-uv pip install fastmcp
-```
+*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>
 
-## Quick Start
+---
 
-Here's a simple example that exposes your desktop directory as a resource and provides a basic addition tool:
+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 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()]
+mcp = FastMCP("Demo 🚀")
 
-@mcp.tool()
+@mcp.tool
 def add(a: int, b: int) -> int:
     """Add two numbers"""
     return a + b
@@ -50,80 +41,70 @@ if __name__ == "__main__":
     mcp.run()
 ```
 
-## Features
-
-### Resources
-
-Resources are data sources that can be accessed by the LLM. They can be files, directories, or any other data source. Resources are defined using the `@resource` decorator:
-
-```python
-@mcp.resource("file://config.json")
-def get_config() -> str:
-    """Read the config file"""
-    return Path("config.json").read_text()
-```
-
-### Tools
+## 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). When you're ready to deploy, [Prefect Horizon](https://www.prefect.io/horizon) offers free hosting for FastMCP users.
 
-Tools are functions that can be called by the LLM. They are defined using the `@tool` decorator:
-
-```python
-@mcp.tool()
-def calculate(x: int, y: int) -> int:
-    """Perform a calculation"""
-    return x + y
-```
-
-## Development
-
-### Running the Dev Inspector
+## Installation
 
-FastMCP includes a development server with the MCP Inspector for testing your server:
+We recommend installing FastMCP with [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Basic usage
-fastmcp dev your_server.py
-
-# Install package in editable mode from current directory
-fastmcp dev your_server.py --with-editable .
-
-# Install additional packages
-fastmcp dev your_server.py --with pandas --with numpy
-
-# Combine both
-fastmcp dev your_server.py --with-editable . --with pandas --with numpy
+uv pip install fastmcp
 ```
 
-The `--with` flag automatically includes `fastmcp` and any additional packages you specify. The `--with-editable` flag installs the package from the specified directory in editable mode, which is useful during development.
-
-### Installing in Claude
-
-To use your server with Claude Desktop:
+For full installation instructions, including verification and upgrading, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation).
 
-```bash
-# Basic usage
-fastmcp install your_server.py --name "My Server"
-
-# Install package in editable mode
-fastmcp install your_server.py --with-editable .
+**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)
 
-# Install additional packages
-fastmcp install your_server.py --with pandas --with numpy
-
-# Combine options
-fastmcp install your_server.py --with-editable . --with pandas --with numpy
-```
+## 📚 Documentation
 
+FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns.
 
-## Configuration
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily:
 
-FastMCP can be configured via environment variables with the prefix `FASTMCP_`:
+- [`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.
 
-- `FASTMCP_DEBUG`: Enable debug mode
-- `FASTMCP_LOG_LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
-- `FASTMCP_HOST`: HTTP server host (default: 0.0.0.0)
-- `FASTMCP_PORT`: HTTP server port (default: 8000)
+**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.
 
-## License
+## Contributing
 
-Apache 2.0
\ No newline at end of file
+We welcome contributions! See the [Contributing Guide](https://gofastmcp.com/development/contributing) for setup instructions, testing requirements, and PR guidelines.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..8e1943ad8
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+FastMCP v2.x receives security updates. Earlier versions are no longer supported.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x     | :white_check_mark: |
+| < 2.0   | :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.
diff --git a/SYNC_WITH_UPSTREAM.md b/SYNC_WITH_UPSTREAM.md
new file mode 100644
index 000000000..660465e1b
--- /dev/null
+++ b/SYNC_WITH_UPSTREAM.md
@@ -0,0 +1,58 @@
+# Keeping abreast of fastmcp and committing changes
+
+This repo (xsecuremcp2.0) tracks **upstream** [fastmcp](https://github.com/jlowin/fastmcp). Use the steps below to stay in sync and commit your work.
+
+## Remotes
+
+- **origin** – your fork: `https://github.com/PureCipher/xsecuremcp2.0.git`
+- **upstream** – fastmcp: `https://github.com/jlowin/fastmcp.git`
+
+## 1. Sync with upstream fastmcp
+
+From the repo root:
+
+```bash
+# Fetch latest from upstream and merge into current branch
+uv run scripts/sync_upstream.py
+
+# Only fetch (no merge)
+uv run scripts/sync_upstream.py --fetch-only
+
+# Rebase current branch on upstream/main instead of merge
+uv run scripts/sync_upstream.py --rebase
+```
+
+If you're in the middle of a rebase, the script will tell you. Finish the rebase first:
+
+```bash
+git rebase --continue   # after resolving conflicts and staging
+# or
+git rebase --abort      # to cancel the rebase
+```
+
+Then run `sync_upstream.py` again, or merge manually:
+
+```bash
+git fetch upstream
+git merge upstream/main --no-edit
+```
+
+## 2. Make your changes
+
+Work on your branch as usual. Run tests before committing:
+
+```bash
+uv run pytest
+```
+
+## 3. Commit and push
+
+```bash
+git add -A
+git commit -m "Your message"
+git push origin <your-branch>
+```
+
+---
+
+**Current branch:** `securemcp-core` (and `main`). If you were rebasing `securemcp-core` onto upstream, finish that rebase first, then use the sync script for future updates.
diff --git a/admin-ui/.next/dev/types/cache-life.d.ts b/admin-ui/.next/dev/types/cache-life.d.ts
new file mode 100644
index 000000000..a8c6997e7
--- /dev/null
+++ b/admin-ui/.next/dev/types/cache-life.d.ts
@@ -0,0 +1,145 @@
+// Type definitions for Next.js cacheLife configs
+
+declare module 'next/cache' {
+  export { unstable_cache } from 'next/dist/server/web/spec-extension/unstable-cache'
+  export {
+    updateTag,
+    revalidateTag,
+    revalidatePath,
+    refresh,
+  } from 'next/dist/server/web/spec-extension/revalidate'
+  export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'
+
+  
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"default"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 900 seconds (15 minutes)
+     *   expire:     never
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 15 minutes, start revalidating new values in the background.
+     * It lives for the maximum age of the server cache. If this entry has no traffic for a while, it may serve an old value the next request.
+     */
+    export function cacheLife(profile: "default"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"seconds"` profile.
+     * ```
+     *   stale:      30 seconds
+     *   revalidate: 1 seconds
+     *   expire:     60 seconds (1 minute)
+     * ```
+     * 
+     * This cache may be stale on clients for 30 seconds before checking with the server.
+     * If the server receives a new request after 1 seconds, start revalidating new values in the background.
+     * If this entry has no traffic for 1 minute it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "seconds"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"minutes"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 60 seconds (1 minute)
+     *   expire:     3600 seconds (1 hour)
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 1 minute, start revalidating new values in the background.
+     * If this entry has no traffic for 1 hour it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "minutes"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"hours"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 3600 seconds (1 hour)
+     *   expire:     86400 seconds (1 day)
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 1 hour, start revalidating new values in the background.
+     * If this entry has no traffic for 1 day it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "hours"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"days"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 86400 seconds (1 day)
+     *   expire:     604800 seconds (1 week)
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 1 day, start revalidating new values in the background.
+     * If this entry has no traffic for 1 week it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "days"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"weeks"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 604800 seconds (1 week)
+     *   expire:     2592000 seconds (1 month)
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 1 week, start revalidating new values in the background.
+     * If this entry has no traffic for 1 month it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "weeks"): void
+    
+    /**
+     * Cache this `"use cache"` for a timespan defined by the `"max"` profile.
+     * ```
+     *   stale:      300 seconds (5 minutes)
+     *   revalidate: 2592000 seconds (1 month)
+     *   expire:     31536000 seconds (365 days)
+     * ```
+     * 
+     * This cache may be stale on clients for 5 minutes before checking with the server.
+     * If the server receives a new request after 1 month, start revalidating new values in the background.
+     * If this entry has no traffic for 365 days it will expire. The next request will recompute it.
+     */
+    export function cacheLife(profile: "max"): void
+    
+    /**
+     * Cache this `"use cache"` using a custom timespan.
+     * ```
+     *   stale: ... // seconds
+     *   revalidate: ... // seconds
+     *   expire: ... // seconds
+     * ```
+     *
+     * This is similar to Cache-Control: max-age=`stale`,s-max-age=`revalidate`,stale-while-revalidate=`expire-revalidate`
+     *
+     * If a value is left out, the lowest of other cacheLife() calls or the default, is used instead.
+     */
+    export function cacheLife(profile: {
+      /**
+       * This cache may be stale on clients for ... seconds before checking with the server.
+       */
+      stale?: number,
+      /**
+       * If the server receives a new request after ... seconds, start revalidating new values in the background.
+       */
+      revalidate?: number,
+      /**
+       * If this entry has no traffic for ... seconds it will expire. The next request will recompute it.
+       */
+      expire?: number
+    }): void
+  
+
+  import { cacheTag } from 'next/dist/server/use-cache/cache-tag'
+  export { cacheTag }
+
+  export const unstable_cacheTag: typeof cacheTag
+  export const unstable_cacheLife: typeof cacheLife
+}
diff --git a/admin-ui/.next/dev/types/routes.d.ts b/admin-ui/.next/dev/types/routes.d.ts
new file mode 100644
index 000000000..85ea48a0b
--- /dev/null
+++ b/admin-ui/.next/dev/types/routes.d.ts
@@ -0,0 +1,65 @@
+// This file is generated automatically by Next.js
+// Do not edit this file manually
+
+type AppRoutes = "/" | "/audit" | "/consent" | "/contracts" | "/explain" | "/ledger" | "/monitoring" | "/policies"
+type PageRoutes = never
+type LayoutRoutes = "/"
+type RedirectRoutes = never
+type RewriteRoutes = "/api/[[...path]]"
+type Routes = AppRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes
+
+
+interface ParamMap {
+  "/": {}
+  "/api/[[...path]]": { "path"?: string[]; }
+  "/audit": {}
+  "/consent": {}
+  "/contracts": {}
+  "/explain": {}
+  "/ledger": {}
+  "/monitoring": {}
+  "/policies": {}
+}
+
+
+export type ParamsOf<Route extends Routes> = ParamMap[Route]
+
+interface LayoutSlotMap {
+  "/": never
+}
+
+
+export type { AppRoutes, PageRoutes, LayoutRoutes, RedirectRoutes, RewriteRoutes, ParamMap }
+
+declare global {
+  /**
+   * Props for Next.js App Router page components
+   * @example
+   * ```tsx
+   * export default function Page(props: PageProps<'/blog/[slug]'>) {
+   *   const { slug } = await props.params
+   *   return <div>Blog post: {slug}</div>
+   * }
+   * ```
+   */
+  interface PageProps<AppRoute extends AppRoutes> {
+    params: Promise<ParamMap[AppRoute]>
+    searchParams: Promise<Record<string, string | string[] | undefined>>
+  }
+
+  /**
+   * Props for Next.js App Router layout components
+   * @example
+   * ```tsx
+   * export default function Layout(props: LayoutProps<'/dashboard'>) {
+   *   return <div>{props.children}</div>
+   * }
+   * ```
+   */
+  type LayoutProps<LayoutRoute extends LayoutRoutes> = {
+    params: Promise<ParamMap[LayoutRoute]>
+    children: React.ReactNode
+  } & {
+    [K in LayoutSlotMap[LayoutRoute]]: React.ReactNode
+  }
+}
diff --git a/admin-ui/.next/dev/types/validator.ts b/admin-ui/.next/dev/types/validator.ts
new file mode 100644
index 000000000..1df173ba4
--- /dev/null
+++ b/admin-ui/.next/dev/types/validator.ts
@@ -0,0 +1,133 @@
+// This file is generated automatically by Next.js
+// Do not edit this file manually
+// This file validates that all pages and layouts export the correct types
+
+import type { AppRoutes, LayoutRoutes, ParamMap } from "./routes.js"
+import type { ResolvingMetadata, ResolvingViewport } from "next/types.js"
+
+type AppPageConfig<Route extends AppRoutes = AppRoutes> = {
+  default: React.ComponentType<{ params: Promise<ParamMap[Route]> } & any> | ((props: { params: Promise<ParamMap[Route]> } & any) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
+  generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
+  generateMetadata?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingMetadata
+  ) => Promise<any> | any
+  generateViewport?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingViewport
+  ) => Promise<any> | any
+  metadata?: any
+  viewport?: any
+}
+
+type LayoutConfig<Route extends LayoutRoutes = LayoutRoutes> = {
+  default: React.ComponentType<LayoutProps<Route>> | ((props: LayoutProps<Route>) => React.ReactNode | Promise<React.ReactNode> | never | void | Promise<void>)
+  generateStaticParams?: (props: { params: ParamMap[Route] }) => Promise<any[]> | any[]
+  generateMetadata?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingMetadata
+  ) => Promise<any> | any
+  generateViewport?: (
+    props: { params: Promise<ParamMap[Route]> } & any,
+    parent: ResolvingViewport
+  ) => Promise<any> | any
+  metadata?: any
+  viewport?: any
+}
+
+
+// Validate ../../../app/(dashboard)/audit/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/audit">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/audit/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/consent/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/consent">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/consent/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/contracts/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/contracts">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/contracts/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/explain/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/explain">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/explain/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/ledger/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/ledger">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/ledger/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/monitoring/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/monitoring">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/monitoring/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/(dashboard)/policies/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/policies">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/policies/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+
+
+
+
+
+
+// Validate ../../../app/(dashboard)/layout.tsx
+{
+  type __IsExpected<Specific extends LayoutConfig<"/">> = Specific
+  const handler = {} as typeof import("../../../app/(dashboard)/layout.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../../app/layout.tsx
+{
+  type __IsExpected<Specific extends LayoutConfig<"/">> = Specific
+  const handler = {} as typeof import("../../../app/layout.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
diff --git a/admin-ui/next-env.d.ts b/admin-ui/next-env.d.ts
new file mode 100644
index 000000000..c4b7818fb
--- /dev/null
+++ b/admin-ui/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/docs/.ccignore b/docs/.ccignore
new file mode 100644
index 000000000..ad117c3ee
--- /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 000000000..503fe1647
--- /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/low-level.mdx b/docs/apps/low-level.mdx
new file mode 100644
index 000000000..944e48498
--- /dev/null
+++ b/docs/apps/low-level.mdx
@@ -0,0 +1,303 @@
+---
+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
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+The [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) is an open protocol that lets tools return interactive UIs — an HTML page rendered in a sandboxed iframe inside the host client. [Prefab UI](/apps/prefab) builds on this protocol so you never have to think about it, but when you need full control — custom rendering, a specific JavaScript framework, maps, 3D, video — you can use the MCP Apps extension directly.
+
+This page covers how to write custom HTML apps and wire them up in FastMCP. You'll be working with the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) JavaScript SDK for host communication, and FastMCP's `AppConfig` for resource and CSP management.
+
+## 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.server.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.server.apps`:
+
+```python
+from fastmcp.server.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`. You don't need to set this 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
+
+<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.server.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.server.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: 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 mcp import types
+
+from fastmcp import FastMCP
+from fastmcp.server.apps import AppConfig, ResourceCSP
+from fastmcp.tools import ToolResult
+
+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=[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."""
+    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.server.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 000000000..d8dcfc3fd
--- /dev/null
+++ b/docs/apps/overview.mdx
@@ -0,0 +1,76 @@
+---
+title: Apps
+sidebarTitle: Overview
+description: Give your tools interactive UIs rendered directly in the conversation.
+icon: grid-2
+tag: NEW
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.0.0" />
+
+MCP Apps let your tools return interactive UIs — rendered in a sandboxed iframe right inside the host client's conversation. Instead of returning plain text, a tool can show a chart, a sortable table, a form, or anything you can build with HTML.
+
+FastMCP implements the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) and provides two approaches:
+
+## Prefab Apps (Recommended)
+
+<VersionBadge version="3.1.0" />
+
+<Tip>
+[Prefab](https://prefab.prefect.io) is in extremely early, active development — its API changes frequently and breaking changes can occur with any release. The FastMCP integration is equally new and under rapid development. These docs are included for users who want to work on the cutting edge; production use is not recommended. Always [pin `prefab-ui` to a specific version](/apps/prefab#getting-started) in your dependencies.
+</Tip>
+
+[Prefab UI](https://prefab.prefect.io) is a declarative UI framework for Python. You describe layouts, charts, tables, forms, and interactive behaviors using a Python DSL — and the framework compiles them to a JSON protocol that a shared renderer interprets. It started as a component library inside FastMCP and grew into its own framework with [comprehensive documentation](https://prefab.prefect.io).
+
+```python
+from prefab_ui.components import Column, Heading, BarChart, ChartSeries
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Dashboard")
+
+@mcp.tool(app=True)
+def sales_chart(year: int) -> PrefabApp:
+    """Show sales data as an interactive chart."""
+    data = get_sales_data(year)
+
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(f"{year} Sales")
+        BarChart(
+            data=data,
+            series=[ChartSeries(data_key="revenue", label="Revenue")],
+            x_axis="month",
+        )
+
+    return PrefabApp(view=view)
+```
+
+Install with `pip install "fastmcp[apps]"` and see [Prefab Apps](/apps/prefab) for the integration guide.
+
+## Custom HTML Apps
+
+The [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) is an open protocol, and you can use it directly when you need full control. You write your own HTML/CSS/JavaScript and communicate with the host via the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) SDK.
+
+This is the right choice for custom rendering (maps, 3D, video), specific JavaScript frameworks, or capabilities beyond what the component library offers.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.apps import AppConfig, ResourceCSP
+
+mcp = FastMCP("Custom App")
+
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/view.html"))
+def my_tool() -> str:
+    return '{"values": [1, 2, 3]}'
+
+@mcp.resource(
+    "ui://my-app/view.html",
+    app=AppConfig(csp=ResourceCSP(resource_domains=["https://unpkg.com"])),
+)
+def view() -> str:
+    return "<html>...</html>"
+```
+
+See [Custom HTML Apps](/apps/low-level) for the full reference.
diff --git a/docs/apps/patterns.mdx b/docs/apps/patterns.mdx
new file mode 100644
index 000000000..ffc699f89
--- /dev/null
+++ b/docs/apps/patterns.mdx
@@ -0,0 +1,483 @@
+---
+title: Patterns
+sidebarTitle: Patterns
+description: Charts, tables, forms, and other common tool UIs.
+icon: grid-2-plus
+tag: SOON
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.1.0" />
+
+<Tip>
+[Prefab](https://prefab.prefect.io) is in extremely early, active development — its API changes frequently and breaking changes can occur with any release. The FastMCP integration is equally new and under rapid development. These docs are included for users who want to work on the cutting edge; production use is not recommended. Always pin `prefab-ui` to a specific version in your dependencies.
+</Tip>
+
+The most common use of Prefab is giving your tools a visual representation — a chart instead of raw numbers, a sortable table instead of a text dump, a status dashboard instead of a list of booleans. Each pattern below is a complete, copy-pasteable tool.
+
+## Charts
+
+Prefab includes [bar, line, area, pie, radar, and radial charts](https://prefab.prefect.io/docs/components/charts). They all render client-side with tooltips, legends, and responsive sizing.
+
+### Bar Chart
+
+```python
+from prefab_ui.components import Column, Heading, BarChart, ChartSeries
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Charts")
+
+
+@mcp.tool(app=True)
+def quarterly_revenue(year: int) -> PrefabApp:
+    """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},
+    ]
+
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(f"{year} Revenue vs Costs")
+        BarChart(
+            data=data,
+            series=[
+                ChartSeries(data_key="revenue", label="Revenue"),
+                ChartSeries(data_key="costs", label="Costs"),
+            ],
+            x_axis="quarter",
+            show_legend=True,
+        )
+
+    return PrefabApp(view=view)
+```
+
+Multiple `ChartSeries` entries plot different data keys. Add `stacked=True` to stack bars, or `horizontal=True` to flip the axes.
+
+### Area Chart
+
+`LineChart` and `AreaChart` share the same API as `BarChart`, with `curve` for interpolation (`"linear"`, `"smooth"`, `"step"`) and `show_dots` for data points:
+
+```python
+from prefab_ui.components import Column, Heading, AreaChart, ChartSeries
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Charts")
+
+
+@mcp.tool(app=True)
+def usage_trend() -> PrefabApp:
+    """Show API usage over time."""
+    data = [
+        {"date": "Feb 1", "requests": 1200},
+        {"date": "Feb 2", "requests": 1350},
+        {"date": "Feb 3", "requests": 980},
+        {"date": "Feb 4", "requests": 1500},
+        {"date": "Feb 5", "requests": 1420},
+    ]
+
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("API Usage")
+        AreaChart(
+            data=data,
+            series=[ChartSeries(data_key="requests", label="Requests")],
+            x_axis="date",
+            curve="smooth",
+            height=250,
+        )
+
+    return PrefabApp(view=view)
+```
+
+### Pie and Donut Charts
+
+`PieChart` uses `data_key` (the numeric value) and `name_key` (the label) instead of series. Set `inner_radius` for a donut:
+
+```python
+from prefab_ui.components import Column, Heading, PieChart
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Charts")
+
+
+@mcp.tool(app=True)
+def ticket_breakdown() -> PrefabApp:
+    """Show open tickets by category."""
+    data = [
+        {"category": "Bug", "count": 23},
+        {"category": "Feature", "count": 15},
+        {"category": "Docs", "count": 8},
+        {"category": "Infra", "count": 12},
+    ]
+
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Open Tickets")
+        PieChart(
+            data=data,
+            data_key="count",
+            name_key="category",
+            show_legend=True,
+            inner_radius=60,
+        )
+
+    return PrefabApp(view=view)
+```
+
+## Data Tables
+
+[DataTable](https://prefab.prefect.io/docs/components/data-display/data-table) provides sortable columns, full-text search, and pagination — all running client-side in the browser.
+
+```python
+from prefab_ui.components import Column, Heading, DataTable, DataTableColumn
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Directory")
+
+
+@mcp.tool(app=True)
+def employee_directory() -> PrefabApp:
+    """Show a searchable, sortable employee directory."""
+    employees = [
+        {"name": "Alice Chen", "department": "Engineering", "role": "Staff Engineer", "location": "SF"},
+        {"name": "Bob Martinez", "department": "Design", "role": "Lead Designer", "location": "NYC"},
+        {"name": "Carol Johnson", "department": "Engineering", "role": "Senior Engineer", "location": "London"},
+        {"name": "David Kim", "department": "Product", "role": "Product Manager", "location": "SF"},
+        {"name": "Eva Müller", "department": "Engineering", "role": "Engineer", "location": "Berlin"},
+    ]
+
+    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,
+            searchable=True,
+            paginated=True,
+            page_size=15,
+        )
+
+    return PrefabApp(view=view)
+```
+
+## Forms
+
+A form collects input, but it needs somewhere to send that input. The [`CallTool`](https://prefab.prefect.io/docs/concepts/actions) action connects a form to a tool on your MCP server — so you need two tools: one that renders the form, and one that handles the submission.
+
+```python
+from prefab_ui.components import (
+    Column, Heading, Row, Muted, Badge, Input, Select,
+    Textarea, Button, Form, ForEach, Separator,
+)
+from prefab_ui.actions import ShowToast
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Contacts")
+
+contacts_db: list[dict] = [
+    {"name": "Zaphod Beeblebrox", "email": "zaphod@galaxy.gov", "category": "Partner"},
+]
+
+
+@mcp.tool(app=True)
+def contact_form() -> PrefabApp:
+    """Show a contact list with a form to add new contacts."""
+    with Column(gap=6, css_class="p-6") as view:
+        Heading("Contacts")
+
+        with ForEach("contacts"):
+            with Row(gap=2, align="center"):
+                Muted("{{ name }}")
+                Muted("{{ email }}")
+                Badge("{{ category }}")
+
+        Separator()
+
+        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_db)})
+
+
+@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."""
+    contacts_db.append({"name": name, "email": email, "category": category, "notes": notes})
+    return list(contacts_db)
+```
+
+When the user submits the form, the renderer calls `save_contact` on the server with all named input values as arguments. Because `result_key="contacts"` is set, the returned list replaces the `contacts` state — and the `ForEach` re-renders with the new data automatically.
+
+The `save_contact` tool is a regular MCP tool. The LLM can also call it directly in conversation. Your UI actions and your conversational tools are the same thing.
+
+### Pydantic Model Forms
+
+For complex forms, `Form.from_model()` generates the entire form from a Pydantic model — inputs, labels, validation, and submit wiring:
+
+```python
+from typing import Literal
+
+from pydantic import BaseModel, Field
+from prefab_ui.components import Column, Heading, Form
+from prefab_ui.actions.mcp import CallTool
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Bug Tracker")
+
+
+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")
+    steps_to_reproduce: str = Field(title="Steps to Reproduce")
+
+
+@mcp.tool(app=True)
+def report_bug() -> PrefabApp:
+    """Show a bug report form."""
+    with Column(gap=4, css_class="p-6") as view:
+        Heading("Report a Bug")
+        Form.from_model(BugReport, on_submit=CallTool("create_bug_report"))
+
+    return PrefabApp(view=view)
+
+
+@mcp.tool
+def create_bug_report(data: dict) -> str:
+    """Create a bug report from the form submission."""
+    report = BugReport(**data)
+    # save to database...
+    return f"Created bug report: {report.title}"
+```
+
+`str` fields become text inputs, `Literal` becomes a select, `bool` becomes a checkbox. The `on_submit` CallTool receives all field values under a `data` key.
+
+## Status Displays
+
+Cards, badges, progress bars, and grids combine naturally for dashboards. See the [Prefab layout](https://prefab.prefect.io/docs/concepts/composition) and [container](https://prefab.prefect.io/docs/components/containers) docs for the full set of layout and display components.
+
+```python
+from prefab_ui.components import (
+    Column, Row, Grid, Heading, Text, Muted, Badge,
+    Card, CardContent, Progress, Separator,
+)
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Monitoring")
+
+
+@mcp.tool(app=True)
+def system_status() -> PrefabApp:
+    """Show current system health."""
+    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},
+    ]
+    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
+
+[`If`, `Elif`, and `Else`](https://prefab.prefect.io/docs/concepts/composition#conditional-rendering) show or hide content based on state. Changes are instant — no server round-trip.
+
+```python
+from prefab_ui.components import Column, Heading, Switch, Separator, Alert, If
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Flags")
+
+
+@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("{{ dark_mode }}"):
+            Alert(title="Dark mode enabled", description="UI will use dark theme.")
+        with If("{{ 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
+
+[Tabs](https://prefab.prefect.io/docs/components/containers/tabs) organize content into switchable views. Switching is client-side — no server round-trip.
+
+```python
+from prefab_ui.components import (
+    Column, Heading, Text, Muted, Badge, Row,
+    DataTable, DataTableColumn, Tabs, Tab, ForEach,
+)
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Projects")
+
+
+@mcp.tool(app=True)
+def project_overview(project_id: str) -> PrefabApp:
+    """Show project details organized in tabs."""
+    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"},
+        ],
+        "activity": [
+            {"timestamp": "2 hours ago", "message": "Merged PR #342"},
+            {"timestamp": "1 day ago", "message": "Released v3.0.1"},
+        ],
+    }
+
+    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"):
+                    with Row(gap=2):
+                        Muted("{{ timestamp }}")
+                        Text("{{ message }}")
+
+    return PrefabApp(view=view, state={"activity": project["activity"]})
+```
+
+## Accordion
+
+[Accordion](https://prefab.prefect.io/docs/components/containers/accordion) collapses sections to save space. `multiple=True` lets users expand several items at once:
+
+```python
+from prefab_ui.components import (
+    Column, Heading, Row, Text, Badge, Progress,
+    Accordion, AccordionItem,
+)
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("API Monitor")
+
+
+@mcp.tool(app=True)
+def api_health() -> PrefabApp:
+    """Show health details for each API endpoint."""
+    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},
+    ]
+
+    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)
+```
+
+## Next Steps
+
+- **[Custom HTML Apps](/apps/low-level)** — When you need your own HTML, CSS, and JavaScript
+- **[Prefab UI Docs](https://prefab.prefect.io)** — Components, state, expressions, and actions
diff --git a/docs/apps/prefab.mdx b/docs/apps/prefab.mdx
new file mode 100644
index 000000000..907670d4b
--- /dev/null
+++ b/docs/apps/prefab.mdx
@@ -0,0 +1,195 @@
+---
+title: Prefab Apps
+sidebarTitle: Prefab Apps
+description: Build interactive tool UIs in pure Python — no HTML or JavaScript required.
+icon: palette
+tag: SOON
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="3.1.0" />
+
+<Tip>
+[Prefab](https://prefab.prefect.io) is in extremely early, active development — its API changes frequently and breaking changes can occur with any release. The FastMCP integration is equally new and under rapid development. These docs are included for users who want to work on the cutting edge; production use is not recommended. Always pin `prefab-ui` to a specific version in your dependencies (see below).
+</Tip>
+
+[Prefab UI](https://prefab.prefect.io) is a declarative UI framework for Python. You describe what your interface should look like — a chart, a table, a form — and return it from your tool. FastMCP takes care of everything else: registering the renderer, wiring the protocol metadata, and delivering the component tree to the host.
+
+Prefab started as a component library inside FastMCP and grew into a full framework for building interactive applications — with its own state management, reactive expression system, and action model. The [Prefab documentation](https://prefab.prefect.io) covers all of this in depth. This page focuses on the FastMCP integration: what you return from a tool, and what FastMCP does with it.
+
+```bash
+pip install "fastmcp[apps]"
+```
+
+<Tip>
+Prefab UI is in active early development and its API changes frequently. We strongly recommend pinning `prefab-ui` to a specific version in your project's dependencies. Installing `fastmcp[apps]` pulls in `prefab-ui` but won't pin it — so a routine `pip install --upgrade` could introduce breaking changes.
+
+```toml
+# pyproject.toml
+dependencies = [
+    "fastmcp[apps]",
+    "prefab-ui==0.8.0",  # pin to a known working version
+]
+```
+</Tip>
+
+Here's the simplest possible Prefab App — a tool that returns a bar chart:
+
+```python
+from prefab_ui.components import Column, Heading, BarChart, ChartSeries
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Dashboard")
+
+
+@mcp.tool(app=True)
+def revenue_chart(year: int) -> PrefabApp:
+    """Show annual revenue as an interactive bar chart."""
+    data = [
+        {"quarter": "Q1", "revenue": 42000},
+        {"quarter": "Q2", "revenue": 51000},
+        {"quarter": "Q3", "revenue": 47000},
+        {"quarter": "Q4", "revenue": 63000},
+    ]
+
+    with Column(gap=4, css_class="p-6") as view:
+        Heading(f"{year} Revenue")
+        BarChart(
+            data=data,
+            series=[ChartSeries(data_key="revenue", label="Revenue")],
+            x_axis="quarter",
+        )
+
+    return PrefabApp(view=view)
+```
+
+That's it — you declare a layout using Python's `with` statement, and return it. When the host calls this tool, the user sees an interactive bar chart instead of a JSON blob. The [Patterns](/apps/patterns) page has more examples: area charts, data tables, forms, status dashboards, and more.
+
+## What You Return
+
+### Components
+
+The simplest way to get started. If you're returning a visual representation of data and don't need Prefab's more advanced features like initial state or stylesheets, just return the components directly. FastMCP wraps them in a `PrefabApp` automatically:
+
+```python
+from prefab_ui.components import Column, Heading, Badge
+from fastmcp import FastMCP
+
+mcp = FastMCP("Status")
+
+
+@mcp.tool(app=True)
+def status_badge() -> Column:
+    """Show system status."""
+    with Column(gap=2) as view:
+        Heading("All Systems Operational")
+        Badge("Healthy", variant="success")
+    return view
+```
+
+Want a chart? Return a chart. Want a table? Return a table. FastMCP handles the wiring.
+
+### PrefabApp
+
+When you need more control — setting initial state values that components can read and react to, or configuring the rendering engine — return a `PrefabApp` explicitly:
+
+```python
+from prefab_ui.components import Column, Heading, Text, Button, If, Badge
+from prefab_ui.actions import ToggleState
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo")
+
+
+@mcp.tool(app=True)
+def toggle_demo() -> PrefabApp:
+    """Interactive toggle with state."""
+    with Column(gap=4, css_class="p-6") as view:
+        Button("Toggle", on_click=ToggleState("show"))
+        with If("{{ show }}"):
+            Badge("Visible!", variant="success")
+
+    return PrefabApp(view=view, state={"show": False})
+```
+
+The `state` dict provides the initial values. Components reference state with `{{ expression }}` templates. State mutations like `ToggleState` happen entirely in the browser — no server round-trip. The [Prefab state guide](https://prefab.prefect.io/docs/concepts/state) covers this in detail.
+
+### ToolResult
+
+Every tool result has two audiences: the renderer (which displays the UI) and the LLM (which reads the text content to understand what happened). By default, Prefab Apps send `"[Rendered Prefab UI]"` as the text content, which tells the LLM almost nothing.
+
+If you want the LLM to understand the result — so it can reference the data in conversation, summarize it, or decide what to do next — wrap your return in a `ToolResult` with a meaningful `content` string:
+
+```python
+from prefab_ui.components import Column, Heading, BarChart, ChartSeries
+from prefab_ui.app import PrefabApp
+from fastmcp import FastMCP
+from fastmcp.tools import ToolResult
+
+mcp = FastMCP("Sales")
+
+
+@mcp.tool(app=True)
+def sales_overview(year: int) -> ToolResult:
+    """Show sales data visually and 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:
+        Heading("Sales Overview")
+        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 LLM sees `"Total revenue for 2025: $203,000 across 4 quarters"` and can reason about it.
+
+## Type Inference
+
+If your tool's return type annotation is a Prefab type — `PrefabApp`, `Component`, or their `Optional` variants — FastMCP detects this and enables app rendering automatically:
+
+```python
+@mcp.tool
+def greet(name: str) -> PrefabApp:
+    return PrefabApp(view=Heading(f"Hello, {name}!"))
+```
+
+This is equivalent to `@mcp.tool(app=True)`. Explicit `app=True` is recommended for clarity, and is required when the return type doesn't reveal a Prefab type (e.g., `-> ToolResult`).
+
+## How It Works
+
+Behind the scenes, when a tool returns a Prefab component or `PrefabApp`, FastMCP:
+
+1. **Registers a shared renderer** — a `ui://prefab/renderer.html` resource containing the JavaScript rendering engine, fetched once by the host and reused across all your Prefab tools.
+2. **Wires the tool metadata** — so the host knows to load the renderer iframe when displaying the tool result.
+3. **Serializes the component tree** — your Python components become `structuredContent` on the tool result, which the renderer interprets and displays.
+
+None of this requires any configuration. The `app=True` flag (or type inference) is the only thing you need.
+
+## Mixing with Custom HTML Apps
+
+Prefab tools and [custom HTML tools](/apps/low-level) coexist in the same server. Prefab tools share a single renderer resource; custom tools point to their own. Both use the same MCP Apps protocol:
+
+```python
+from fastmcp.server.apps import AppConfig
+
+@mcp.tool(app=True)
+def team_directory() -> PrefabApp:
+    ...
+
+@mcp.tool(app=AppConfig(resource_uri="ui://my-app/map.html"))
+def map_view() -> str:
+    ...
+```
+
+## Next Steps
+
+- **[Patterns](/apps/patterns)** — Charts, tables, forms, and other common tool UIs
+- **[Custom HTML Apps](/apps/low-level)** — When you need your own HTML, CSS, and JavaScript
+- **[Prefab UI Docs](https://prefab.prefect.io)** — Components, state, expressions, and actions
diff --git a/docs/assets/brand/blue-logo.png b/docs/assets/brand/blue-logo.png
new file mode 100644
index 000000000..18c3bc6f9
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 000000000..9982cd801
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 000000000..3dc9951ee
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 000000000..d1384e30e
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 000000000..e906a020c
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 000000000..1c411823f
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 000000000..eccd888c4
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 000000000..1c0bc14d2
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 000000000..a50956cc8
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 000000000..93ccf6efb
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 000000000..4c2491eeb
--- /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 000000000..a30944eaa
--- /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 000000000..76a55779a
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 000000000..43019d18f
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 000000000..6d0f58fce
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 000000000..a3eeb6239
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 000000000..efda5c85b
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 000000000..af45659c7
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 000000000..2f93bc0ca
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 000000000..5dc7932e4
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 000000000..5c2d673d4
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 000000000..f16370447
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 000000000..02d936762
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 000000000..84950f9ec
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 000000000..71eb80777
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 000000000..81377c5be
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 000000000..41b5717b2
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 000000000..0bb8d8177
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 000000000..0d5eb0541
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 000000000..8eff8f8e2
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 000000000..b3cef5d7d
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 000000000..4c42695b5
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 000000000..a51a6656d
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 000000000..2cd904679
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 000000000..1a6ecfe4d
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 000000000..5613b66d9
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 000000000..6db828c76
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 000000000..1ff5fc071
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 000000000..81d0ad754
--- /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 000000000..81d0ad754
--- /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 000000000..5716e1f73
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 000000000..ae9e94fe9
--- /dev/null
+++ b/docs/changelog.mdx
@@ -0,0 +1,2971 @@
+---
+title: "Changelog"
+icon: "list-check"
+rss: true
+tag: NEW
+---
+
+<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.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**](/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**](/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>
\ No newline at end of file
diff --git a/docs/cli/auth.mdx b/docs/cli/auth.mdx
new file mode 100644
index 000000000..71b89e08a
--- /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 000000000..bd72b163d
--- /dev/null
+++ b/docs/cli/client.mdx
@@ -0,0 +1,140 @@
+---
+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.
diff --git a/docs/cli/generate-cli.mdx b/docs/cli/generate-cli.mdx
new file mode 100644
index 000000000..2754d199a
--- /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 000000000..657921357
--- /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 000000000..0171b7854
--- /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 000000000..2cd4e145d
--- /dev/null
+++ b/docs/cli/overview.mdx
@@ -0,0 +1,103 @@
+---
+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 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 000000000..dd976d561
--- /dev/null
+++ b/docs/cli/running.mdx
@@ -0,0 +1,141 @@
+---
+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.
+
+## 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 000000000..2e12fbc13
--- /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 000000000..c1f92d1c4
--- /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 000000000..84fbe2164
--- /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 000000000..801c7632c
--- /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.mdx b/docs/clients/client.mdx
new file mode 100644
index 000000000..fc5ddc263
--- /dev/null
+++ b/docs/clients/client.mdx
@@ -0,0 +1,237 @@
+---
+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.serverInfo.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.serverInfo.name}")
+
+    # Now ready for operations
+    tools = await client.list_tools()
+```
+
+## 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 000000000..33adbb6d6
--- /dev/null
+++ b/docs/clients/elicitation.mdx
@@ -0,0 +1,138 @@
+---
+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.requestedSchema`
+</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
+)
+```
diff --git a/docs/clients/generate-cli.mdx b/docs/clients/generate-cli.mdx
new file mode 100644
index 000000000..b0faaefb0
--- /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 000000000..eea9ff322
--- /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 000000000..5e1b447aa
--- /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, 'root'):
+        method = message.root.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 000000000..707ab8dac
--- /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 000000000..bb50d475f
--- /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 -> mcp.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 -> mcp.types.GetPromptResult
+```
diff --git a/docs/clients/resources.mdx b/docs/clients/resources.mdx
new file mode 100644
index 000000000..a3e9300da
--- /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.mimeType}")
+```
+
+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.mimeType}")
+
+            # 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 -> mcp.types.ReadResourceResult
+```
diff --git a/docs/clients/roots.mdx b/docs/clients/roots.mdx
new file mode 100644
index 000000000..0370c119a
--- /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 000000000..a2e0e9942
--- /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.systemPrompt 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 mcp.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/src/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 000000000..ce27520e4
--- /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 000000000..1541f593e
--- /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[mcp.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 -> 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()
+```
diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdx
new file mode 100644
index 000000000..7e3eb03db
--- /dev/null
+++ b/docs/clients/transports.mdx
@@ -0,0 +1,235 @@
+---
+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")
+)
+```
+
+### 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 000000000..b61f5cf6d
--- /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 000000000..9ba4c6877
--- /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 000000000..f9c6384b2
--- /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 000000000..72a64c21a
--- /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 000000000..99844f692
--- /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 000000000..20aa16809
--- /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 000000000..e961de9d1
--- /dev/null
+++ b/docs/deployment/http.mdx
@@ -0,0 +1,870 @@
+---
+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.
+
+### 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](/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).
+
+## 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 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 bearer token authentication (though OAuth is recommended for production):
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerTokenAuth
+
+# Read configuration from environment
+auth_token = os.environ.get("MCP_AUTH_TOKEN")
+if auth_token:
+    auth = BearerTokenAuth(token=auth_token)
+    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 000000000..a7d053813
--- /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) 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 000000000..c10855345
--- /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/server-configuration.mdx b/docs/deployment/server-configuration.mdx
new file mode 100644
index 000000000..f9b0e4781
--- /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 000000000..c8772765a
--- /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 000000000..346462736
--- /dev/null
+++ b/docs/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/development/tests.mdx b/docs/development/tests.mdx
new file mode 100644
index 000000000..6a9973fe8
--- /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 `src/` directory structure, creating a predictable mapping between code and tests. When you're working on `src/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.
\ No newline at end of file
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 000000000..c61f61cbe
--- /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 000000000..da9fc87db
--- /dev/null
+++ b/docs/development/v3-notes/v3-features.mdx
@@ -0,0 +1,1482 @@
+---
+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 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.server.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.server.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: `src/fastmcp/server/apps.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** (`src/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` (`src/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` (`src/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` (`src/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` (`src/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** (`src/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, ListToolsNext, 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, call_next: ListToolsNext) -> Sequence[Tool]:
+        tools = await call_next()  # Get tools from downstream
+        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` (`src/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` (`src/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` (`src/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** (`src/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 (`src/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.nextCursor:
+        result = await client.list_tools_mcp(cursor=result.nextCursor)
+```
+
+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 mcp.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/docs.json b/docs/docs.json
new file mode 100644
index 000000000..a793fb35f
--- /dev/null
+++ b/docs/docs.json
@@ -0,0 +1,1054 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "appearance": {
+    "default": "system",
+    "strict": false
+  },
+  "background": {
+    "color": {
+      "dark": "#222831",
+      "light": "#EEEEEE"
+    },
+    "decoration": "gradient"
+  },
+  "banner": {
+    "content": "Deploy FastMCP servers for free on [Prefect Horizon](https://www.prefect.io/horizon)"
+  },
+  "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\u2019ve 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": "Features",
+                    "icon": "stars",
+                    "pages": [
+                      "servers/tasks",
+                      "servers/composition",
+                      "servers/dependency-injection",
+                      "servers/elicitation",
+                      "servers/icons",
+                      "servers/lifespan",
+                      "servers/logging",
+                      "servers/middleware",
+                      "servers/pagination",
+                      "servers/progress",
+                      "servers/sampling",
+                      "servers/storage-backends",
+                      "servers/telemetry",
+                      "servers/testing",
+                      "servers/versioning"
+                    ],
+                    "tag": "UPDATED"
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Providers",
+                    "icon": "layer-group",
+                    "pages": [
+                      "servers/providers/overview",
+                      "servers/providers/local",
+                      "servers/providers/filesystem",
+                      "servers/providers/proxy",
+                      "servers/providers/skills",
+                      "servers/providers/custom"
+                    ],
+                    "tag": "NEW"
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Transforms",
+                    "icon": "wand-magic-sparkles",
+                    "pages": [
+                      "servers/transforms/transforms",
+                      "servers/transforms/namespace",
+                      "servers/transforms/tool-transformation",
+                      "servers/visibility",
+                      "servers/transforms/code-mode",
+                      "servers/transforms/tool-search",
+                      "servers/transforms/resources-as-tools",
+                      "servers/transforms/prompts-as-tools"
+                    ],
+                    "tag": "NEW"
+                  },
+                  {
+                    "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"
+                    ],
+                    "tag": "UPDATED"
+                  },
+                  "servers/authorization",
+                  {
+                    "collapsed": true,
+                    "group": "Deployment",
+                    "icon": "rocket",
+                    "pages": [
+                      "deployment/running-server",
+                      "deployment/http",
+                      "deployment/prefect-horizon",
+                      "deployment/server-configuration"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Apps",
+                "pages": [
+                  "apps/overview",
+                  "apps/prefab",
+                  "apps/patterns",
+                  "apps/low-level"
+                ]
+              },
+              {
+                "group": "Clients",
+                "pages": [
+                  "clients/client",
+                  "clients/transports",
+                  {
+                    "collapsed": true,
+                    "group": "Core Operations",
+                    "icon": "toolbox",
+                    "pages": [
+                      "clients/tools",
+                      "clients/resources",
+                      "clients/prompts"
+                    ]
+                  },
+                  {
+                    "collapsed": true,
+                    "group": "Handlers",
+                    "icon": "hand",
+                    "pages": [
+                      "clients/notifications",
+                      "clients/sampling",
+                      "clients/elicitation",
+                      "clients/tasks",
+                      "clients/progress",
+                      "clients/logging",
+                      "clients/roots"
+                    ],
+                    "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/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/mcp-json-configuration"
+                ]
+              },
+              {
+                "group": "CLI",
+                "pages": [
+                  "cli/overview",
+                  "cli/running",
+                  "cli/install-mcp",
+                  "cli/inspecting",
+                  "cli/client",
+                  "cli/generate-cli",
+                  "cli/auth"
+                ]
+              },
+              {
+                "group": "More",
+                "pages": [
+                  "more/settings",
+                  {
+                    "collapsed": true,
+                    "group": "Upgrading",
+                    "icon": "up",
+                    "pages": [
+                      "getting-started/upgrading/from-fastmcp-2",
+                      "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": "What's New",
+                    "icon": "sparkles",
+                    "pages": [
+                      "updates",
+                      "changelog"
+                    ]
+                  }
+                ]
+              }
+            ],
+            "icon": "book"
+          },
+          {
+            "anchors": [
+              {
+                "anchor": "Python SDK",
+                "icon": "python",
+                "pages": [
+                  "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",
+                  {
+                    "group": "fastmcp.cli",
+                    "pages": [
+                      "python-sdk/fastmcp-cli-__init__",
+                      "python-sdk/fastmcp-cli-auth",
+                      "python-sdk/fastmcp-cli-cimd",
+                      "python-sdk/fastmcp-cli-cli",
+                      "python-sdk/fastmcp-cli-client",
+                      "python-sdk/fastmcp-cli-discovery",
+                      "python-sdk/fastmcp-cli-generate",
+                      {
+                        "group": "install",
+                        "pages": [
+                          "python-sdk/fastmcp-cli-install-__init__",
+                          "python-sdk/fastmcp-cli-install-claude_code",
+                          "python-sdk/fastmcp-cli-install-claude_desktop",
+                          "python-sdk/fastmcp-cli-install-cursor",
+                          "python-sdk/fastmcp-cli-install-gemini_cli",
+                          "python-sdk/fastmcp-cli-install-goose",
+                          "python-sdk/fastmcp-cli-install-mcp_json",
+                          "python-sdk/fastmcp-cli-install-shared",
+                          "python-sdk/fastmcp-cli-install-stdio"
+                        ]
+                      },
+                      "python-sdk/fastmcp-cli-run",
+                      "python-sdk/fastmcp-cli-tasks"
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.client",
+                    "pages": [
+                      "python-sdk/fastmcp-client-__init__",
+                      {
+                        "group": "auth",
+                        "pages": [
+                          "python-sdk/fastmcp-client-auth-__init__",
+                          "python-sdk/fastmcp-client-auth-bearer",
+                          "python-sdk/fastmcp-client-auth-oauth"
+                        ]
+                      },
+                      "python-sdk/fastmcp-client-client",
+                      "python-sdk/fastmcp-client-elicitation",
+                      "python-sdk/fastmcp-client-logging",
+                      "python-sdk/fastmcp-client-messages",
+                      {
+                        "group": "mixins",
+                        "pages": [
+                          "python-sdk/fastmcp-client-mixins-__init__",
+                          "python-sdk/fastmcp-client-mixins-prompts",
+                          "python-sdk/fastmcp-client-mixins-resources",
+                          "python-sdk/fastmcp-client-mixins-task_management",
+                          "python-sdk/fastmcp-client-mixins-tools"
+                        ]
+                      },
+                      "python-sdk/fastmcp-client-oauth_callback",
+                      "python-sdk/fastmcp-client-progress",
+                      "python-sdk/fastmcp-client-roots",
+                      {
+                        "group": "sampling",
+                        "pages": [
+                          "python-sdk/fastmcp-client-sampling-__init__",
+                          {
+                            "group": "handlers",
+                            "pages": [
+                              "python-sdk/fastmcp-client-sampling-handlers-__init__",
+                              "python-sdk/fastmcp-client-sampling-handlers-anthropic",
+                              "python-sdk/fastmcp-client-sampling-handlers-google_genai",
+                              "python-sdk/fastmcp-client-sampling-handlers-openai"
+                            ]
+                          }
+                        ]
+                      },
+                      "python-sdk/fastmcp-client-tasks",
+                      "python-sdk/fastmcp-client-telemetry",
+                      {
+                        "group": "transports",
+                        "pages": [
+                          "python-sdk/fastmcp-client-transports-__init__",
+                          "python-sdk/fastmcp-client-transports-base",
+                          "python-sdk/fastmcp-client-transports-config",
+                          "python-sdk/fastmcp-client-transports-http",
+                          "python-sdk/fastmcp-client-transports-inference",
+                          "python-sdk/fastmcp-client-transports-memory",
+                          "python-sdk/fastmcp-client-transports-sse",
+                          "python-sdk/fastmcp-client-transports-stdio"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.experimental",
+                    "pages": [
+                      "python-sdk/fastmcp-experimental-__init__",
+                      {
+                        "group": "sampling",
+                        "pages": [
+                          "python-sdk/fastmcp-experimental-sampling-__init__",
+                          "python-sdk/fastmcp-experimental-sampling-handlers"
+                        ]
+                      },
+                      {
+                        "group": "transforms",
+                        "pages": [
+                          "python-sdk/fastmcp-experimental-transforms-__init__",
+                          "python-sdk/fastmcp-experimental-transforms-code_mode"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.prompts",
+                    "pages": [
+                      "python-sdk/fastmcp-prompts-__init__",
+                      "python-sdk/fastmcp-prompts-function_prompt",
+                      "python-sdk/fastmcp-prompts-prompt"
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.resources",
+                    "pages": [
+                      "python-sdk/fastmcp-resources-__init__",
+                      "python-sdk/fastmcp-resources-function_resource",
+                      "python-sdk/fastmcp-resources-resource",
+                      "python-sdk/fastmcp-resources-template",
+                      "python-sdk/fastmcp-resources-types"
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.server",
+                    "pages": [
+                      "python-sdk/fastmcp-server-__init__",
+                      "python-sdk/fastmcp-server-apps",
+                      {
+                        "group": "auth",
+                        "pages": [
+                          "python-sdk/fastmcp-server-auth-__init__",
+                          "python-sdk/fastmcp-server-auth-auth",
+                          "python-sdk/fastmcp-server-auth-authorization",
+                          "python-sdk/fastmcp-server-auth-cimd",
+                          "python-sdk/fastmcp-server-auth-jwt_issuer",
+                          "python-sdk/fastmcp-server-auth-middleware",
+                          {
+                            "group": "oauth_proxy",
+                            "pages": [
+                              "python-sdk/fastmcp-server-auth-oauth_proxy-__init__",
+                              "python-sdk/fastmcp-server-auth-oauth_proxy-consent",
+                              "python-sdk/fastmcp-server-auth-oauth_proxy-models",
+                              "python-sdk/fastmcp-server-auth-oauth_proxy-proxy",
+                              "python-sdk/fastmcp-server-auth-oauth_proxy-ui"
+                            ]
+                          },
+                          "python-sdk/fastmcp-server-auth-oidc_proxy",
+                          {
+                            "group": "providers",
+                            "pages": [
+                              "python-sdk/fastmcp-server-auth-providers-__init__",
+                              "python-sdk/fastmcp-server-auth-providers-auth0",
+                              "python-sdk/fastmcp-server-auth-providers-aws",
+                              "python-sdk/fastmcp-server-auth-providers-azure",
+                              "python-sdk/fastmcp-server-auth-providers-debug",
+                              "python-sdk/fastmcp-server-auth-providers-descope",
+                              "python-sdk/fastmcp-server-auth-providers-discord",
+                              "python-sdk/fastmcp-server-auth-providers-github",
+                              "python-sdk/fastmcp-server-auth-providers-google",
+                              "python-sdk/fastmcp-server-auth-providers-in_memory",
+                              "python-sdk/fastmcp-server-auth-providers-introspection",
+                              "python-sdk/fastmcp-server-auth-providers-jwt",
+                              "python-sdk/fastmcp-server-auth-providers-oci",
+                              "python-sdk/fastmcp-server-auth-providers-propelauth",
+                              "python-sdk/fastmcp-server-auth-providers-scalekit",
+                              "python-sdk/fastmcp-server-auth-providers-supabase",
+                              "python-sdk/fastmcp-server-auth-providers-workos"
+                            ]
+                          },
+                          "python-sdk/fastmcp-server-auth-redirect_validation",
+                          "python-sdk/fastmcp-server-auth-ssrf"
+                        ]
+                      },
+                      "python-sdk/fastmcp-server-context",
+                      "python-sdk/fastmcp-server-dependencies",
+                      "python-sdk/fastmcp-server-elicitation",
+                      "python-sdk/fastmcp-server-event_store",
+                      "python-sdk/fastmcp-server-http",
+                      "python-sdk/fastmcp-server-lifespan",
+                      "python-sdk/fastmcp-server-low_level",
+                      {
+                        "group": "middleware",
+                        "pages": [
+                          "python-sdk/fastmcp-server-middleware-__init__",
+                          "python-sdk/fastmcp-server-middleware-authorization",
+                          "python-sdk/fastmcp-server-middleware-caching",
+                          "python-sdk/fastmcp-server-middleware-dereference",
+                          "python-sdk/fastmcp-server-middleware-error_handling",
+                          "python-sdk/fastmcp-server-middleware-logging",
+                          "python-sdk/fastmcp-server-middleware-middleware",
+                          "python-sdk/fastmcp-server-middleware-ping",
+                          "python-sdk/fastmcp-server-middleware-rate_limiting",
+                          "python-sdk/fastmcp-server-middleware-response_limiting",
+                          "python-sdk/fastmcp-server-middleware-timing",
+                          "python-sdk/fastmcp-server-middleware-tool_injection"
+                        ]
+                      },
+                      {
+                        "group": "mixins",
+                        "pages": [
+                          "python-sdk/fastmcp-server-mixins-__init__",
+                          "python-sdk/fastmcp-server-mixins-lifespan",
+                          "python-sdk/fastmcp-server-mixins-mcp_operations",
+                          "python-sdk/fastmcp-server-mixins-transport"
+                        ]
+                      },
+                      {
+                        "group": "openapi",
+                        "pages": [
+                          "python-sdk/fastmcp-server-openapi-__init__",
+                          "python-sdk/fastmcp-server-openapi-components",
+                          "python-sdk/fastmcp-server-openapi-routing",
+                          "python-sdk/fastmcp-server-openapi-server"
+                        ]
+                      },
+                      {
+                        "group": "providers",
+                        "pages": [
+                          "python-sdk/fastmcp-server-providers-__init__",
+                          "python-sdk/fastmcp-server-providers-aggregate",
+                          "python-sdk/fastmcp-server-providers-base",
+                          "python-sdk/fastmcp-server-providers-fastmcp_provider",
+                          "python-sdk/fastmcp-server-providers-filesystem",
+                          "python-sdk/fastmcp-server-providers-filesystem_discovery",
+                          {
+                            "group": "local_provider",
+                            "pages": [
+                              "python-sdk/fastmcp-server-providers-local_provider-__init__",
+                              {
+                                "group": "decorators",
+                                "pages": [
+                                  "python-sdk/fastmcp-server-providers-local_provider-decorators-__init__",
+                                  "python-sdk/fastmcp-server-providers-local_provider-decorators-prompts",
+                                  "python-sdk/fastmcp-server-providers-local_provider-decorators-resources",
+                                  "python-sdk/fastmcp-server-providers-local_provider-decorators-tools"
+                                ]
+                              },
+                              "python-sdk/fastmcp-server-providers-local_provider-local_provider"
+                            ]
+                          },
+                          {
+                            "group": "openapi",
+                            "pages": [
+                              "python-sdk/fastmcp-server-providers-openapi-__init__",
+                              "python-sdk/fastmcp-server-providers-openapi-components",
+                              "python-sdk/fastmcp-server-providers-openapi-provider",
+                              "python-sdk/fastmcp-server-providers-openapi-routing"
+                            ]
+                          },
+                          "python-sdk/fastmcp-server-providers-proxy",
+                          {
+                            "group": "skills",
+                            "pages": [
+                              "python-sdk/fastmcp-server-providers-skills-__init__",
+                              "python-sdk/fastmcp-server-providers-skills-claude_provider",
+                              "python-sdk/fastmcp-server-providers-skills-directory_provider",
+                              "python-sdk/fastmcp-server-providers-skills-skill_provider",
+                              "python-sdk/fastmcp-server-providers-skills-vendor_providers"
+                            ]
+                          },
+                          "python-sdk/fastmcp-server-providers-wrapped_provider"
+                        ]
+                      },
+                      "python-sdk/fastmcp-server-proxy",
+                      {
+                        "group": "sampling",
+                        "pages": [
+                          "python-sdk/fastmcp-server-sampling-__init__",
+                          "python-sdk/fastmcp-server-sampling-run",
+                          "python-sdk/fastmcp-server-sampling-sampling_tool"
+                        ]
+                      },
+                      "python-sdk/fastmcp-server-server",
+                      {
+                        "group": "tasks",
+                        "pages": [
+                          "python-sdk/fastmcp-server-tasks-__init__",
+                          "python-sdk/fastmcp-server-tasks-capabilities",
+                          "python-sdk/fastmcp-server-tasks-config",
+                          "python-sdk/fastmcp-server-tasks-elicitation",
+                          "python-sdk/fastmcp-server-tasks-handlers",
+                          "python-sdk/fastmcp-server-tasks-keys",
+                          "python-sdk/fastmcp-server-tasks-notifications",
+                          "python-sdk/fastmcp-server-tasks-requests",
+                          "python-sdk/fastmcp-server-tasks-routing",
+                          "python-sdk/fastmcp-server-tasks-subscriptions"
+                        ]
+                      },
+                      "python-sdk/fastmcp-server-telemetry",
+                      {
+                        "group": "transforms",
+                        "pages": [
+                          "python-sdk/fastmcp-server-transforms-__init__",
+                          "python-sdk/fastmcp-server-transforms-catalog",
+                          "python-sdk/fastmcp-server-transforms-namespace",
+                          "python-sdk/fastmcp-server-transforms-prompts_as_tools",
+                          "python-sdk/fastmcp-server-transforms-resources_as_tools",
+                          {
+                            "group": "search",
+                            "pages": [
+                              "python-sdk/fastmcp-server-transforms-search-__init__",
+                              "python-sdk/fastmcp-server-transforms-search-base",
+                              "python-sdk/fastmcp-server-transforms-search-bm25",
+                              "python-sdk/fastmcp-server-transforms-search-regex"
+                            ]
+                          },
+                          "python-sdk/fastmcp-server-transforms-tool_transform",
+                          "python-sdk/fastmcp-server-transforms-version_filter",
+                          "python-sdk/fastmcp-server-transforms-visibility"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.tools",
+                    "pages": [
+                      "python-sdk/fastmcp-tools-__init__",
+                      "python-sdk/fastmcp-tools-function_parsing",
+                      "python-sdk/fastmcp-tools-function_tool",
+                      "python-sdk/fastmcp-tools-tool",
+                      "python-sdk/fastmcp-tools-tool_transform"
+                    ]
+                  },
+                  {
+                    "group": "fastmcp.utilities",
+                    "pages": [
+                      "python-sdk/fastmcp-utilities-__init__",
+                      "python-sdk/fastmcp-utilities-async_utils",
+                      "python-sdk/fastmcp-utilities-auth",
+                      "python-sdk/fastmcp-utilities-cli",
+                      "python-sdk/fastmcp-utilities-components",
+                      "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": [
+                              "python-sdk/fastmcp-utilities-mcp_server_config-v1-__init__",
+                              {
+                                "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-__init__",
+                                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base",
+                                  "python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem"
+                                ]
+                              }
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "group": "openapi",
+                        "pages": [
+                          "python-sdk/fastmcp-utilities-openapi-__init__",
+                          "python-sdk/fastmcp-utilities-openapi-director",
+                          "python-sdk/fastmcp-utilities-openapi-formatters",
+                          "python-sdk/fastmcp-utilities-openapi-json_schema_converter",
+                          "python-sdk/fastmcp-utilities-openapi-models",
+                          "python-sdk/fastmcp-utilities-openapi-parser",
+                          "python-sdk/fastmcp-utilities-openapi-schemas"
+                        ]
+                      },
+                      "python-sdk/fastmcp-utilities-pagination",
+                      "python-sdk/fastmcp-utilities-skills",
+                      "python-sdk/fastmcp-utilities-tests",
+                      "python-sdk/fastmcp-utilities-timeout",
+                      "python-sdk/fastmcp-utilities-types",
+                      "python-sdk/fastmcp-utilities-ui",
+                      "python-sdk/fastmcp-utilities-version_check",
+                      "python-sdk/fastmcp-utilities-versions"
+                    ]
+                  }
+                ]
+              }
+            ],
+            "dropdown": "SDK Reference",
+            "icon": "code"
+          }
+        ],
+        "version": "v3"
+      },
+      {
+        "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"
+      }
+    ]
+  },
+  "redirects": [
+    {
+      "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"
+    }
+  ],
+  "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"
+  }
+}
\ No newline at end of file
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
new file mode 100644
index 000000000..20443337b
--- /dev/null
+++ b/docs/getting-started/installation.mdx
@@ -0,0 +1,97 @@
+---
+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.
+
+## 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 000000000..3f240cec1
--- /dev/null
+++ b/docs/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](/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) 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) 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 000000000..47baa5655
--- /dev/null
+++ b/docs/getting-started/upgrading/from-fastmcp-2.mdx
@@ -0,0 +1,440 @@
+---
+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: set FASTMCP_DECORATOR_MODE=object for v2 compat (itself deprecated).
+
+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 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>
+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 mcp.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
+# 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`), set `FASTMCP_DECORATOR_MODE=object` for v2 compatibility. This escape hatch is itself deprecated and will be removed in a future release.
+
+**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 still work but emit warnings. Update when convenient.
+
+**mount() prefix → namespace**
+
+```python
+# Deprecated
+main.mount(subserver, prefix="api")
+
+# New
+main.mount(subserver, namespace="api")
+```
+
+**import_server() → mount()**
+
+```python
+# Deprecated
+main.import_server(subserver)
+
+# New
+main.mount(subserver)
+```
+
+**Module import paths for proxy and OpenAPI**
+
+The proxy and OpenAPI modules have moved under `providers` to reflect v3's provider-based architecture:
+
+```python
+# Deprecated
+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` itself is deprecated — use `FastMCP` with an `OpenAPIProvider` instead:
+
+```python
+# Deprecated
+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()**
+
+```python
+# Deprecated
+mcp.add_tool_transformation("name", config)
+
+# New
+from fastmcp.server.transforms import ToolTransform
+mcp.add_transform(ToolTransform({"name": config}))
+```
+
+**FastMCP.as_proxy() → create_proxy()**
+
+```python
+# Deprecated
+proxy = FastMCP.as_proxy("http://example.com/mcp")
+
+# New
+from fastmcp.server import create_proxy
+proxy = create_proxy("http://example.com/mcp")
+```
+
+## v2.14.0
+
+### OpenAPI Parser Promotion
+
+The experimental OpenAPI parser is now standard. Update imports:
+
+```python
+# Before
+from fastmcp.experimental.server.openapi import FastMCPOpenAPI
+
+# After
+from fastmcp.server.openapi import FastMCPOpenAPI
+```
+
+### 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-low-level-sdk.mdx b/docs/getting-started/upgrading/from-low-level-sdk.mdx
new file mode 100644
index 000000000..ce4ddea75
--- /dev/null
+++ b/docs/getting-started/upgrading/from-low-level-sdk.mdx
@@ -0,0 +1,592 @@
+---
+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.
+
+<Note>
+This guide covers upgrading from **v1** of the `mcp` package. We'll provide a separate guide when v2 ships.
+</Note>
+
+<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 3.0. 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 000000000..494d06bdc
--- /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 3.0. 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):
+Direct imports from the `mcp` package (e.g., `import mcp.types`, `from mcp.server.stdio import stdio_server`) still work because FastMCP includes `mcp` as a dependency. However, prefer FastMCP's own APIs where equivalents exist:
+- mcp.types.TextContent for tool returns → just return plain Python values (str, int, dict, etc.)
+- mcp.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
+
+If your server imports directly from the `mcp` package — like `import mcp.types` or `from mcp.server.stdio import stdio_server` — those still work. FastMCP includes `mcp` as a dependency, so nothing breaks.
+
+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 anything without a FastMCP equivalent (e.g., specific protocol types you use directly), the `mcp.*` import is fine to keep.
+
+### 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 000000000..28932284f
--- /dev/null
+++ b/docs/getting-started/welcome.mdx
@@ -0,0 +1,124 @@
+---
+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). When you're ready to deploy, [Prefect Horizon](https://www.prefect.io/horizon) offers free hosting for FastMCP users.
+
+FastMCP is made with 💙 by [Prefect](https://www.prefect.io/).
+
+<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="SearchFastMcp",
+            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 000000000..b8156ac95
--- /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.
+
+```python
+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 000000000..65f9d3873
--- /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 000000000..e99f78351
--- /dev/null
+++ b/docs/integrations/authkit.mdx
@@ -0,0 +1,101 @@
+---
+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, where AuthKit handles user login and your FastMCP server validates the tokens.
+
+<Warning>
+AuthKit 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. If you need resource-specific audience validation, consider using [WorkOSProvider](/integrations/workos) (OAuth proxy pattern) instead.
+</Warning>
+
+## 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
+```
+
+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://localhost: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 000000000..b7df29222
--- /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 000000000..4376a38ce
--- /dev/null
+++ b/docs/integrations/azure.mdx
@@ -0,0 +1,460 @@
+---
+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>
diff --git a/docs/integrations/chatgpt.mdx b/docs/integrations/chatgpt.mdx
new file mode 100644
index 000000000..92ddb7404
--- /dev/null
+++ b/docs/integrations/chatgpt.mdx
@@ -0,0 +1,156 @@
+---
+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={"readOnlyHint": True}` to skip confirmation prompts for read-only tools:
+
+```python
+@mcp.tool(annotations={"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 000000000..8098ff51e
--- /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 000000000..4478bcc37
--- /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 000000000..5681d70d7
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 000000000..da0744ee0
--- /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 000000000..dba9b3509
--- /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 000000000..5d6c643b7
--- /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 000000000..2fd2ca4a5
--- /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 000000000..abdc1d0e7
--- /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.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 000000000..10613fb1b
--- /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 000000000..159e662a5
--- /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) 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 000000000..72e65d3ce
--- /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['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 000000000..17d49d12f
--- /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 000000000..fc2ff8e39
--- /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/images/authkit/enable_dcr.png b/docs/integrations/images/authkit/enable_dcr.png
new file mode 100644
index 000000000..e5942f60e
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 000000000..690f8d391
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 000000000..08812ba9b
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 000000000..3954dab07
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 000000000..f00782154
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 000000000..a5592abca
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 000000000..bd4b5cf33
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 000000000..d100b1eab
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 000000000..c65e34181
Binary files /dev/null and b/docs/integrations/images/permit/role_assignement.png differ
diff --git a/docs/integrations/mcp-json-configuration.mdx b/docs/integrations/mcp-json-configuration.mdx
new file mode 100644
index 000000000..b44b15e76
--- /dev/null
+++ b/docs/integrations/mcp-json-configuration.mdx
@@ -0,0 +1,422 @@
+---
+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"
+```
+
+## 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 000000000..02fa36dae
--- /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 000000000..6f88193f5
--- /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:
+
+```python
+pythonAPIStatusError: 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 000000000..88dc19b14
--- /dev/null
+++ b/docs/integrations/openapi.mdx
@@ -0,0 +1,455 @@
+---
+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.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.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.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.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.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.openapi import RouteMap, MCPType, 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.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.openapi import (
+    HTTPRoute,
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+
+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 000000000..066f5b1ea
--- /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 000000000..7f21d2010
--- /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/scalekit.mdx b/docs/integrations/scalekit.mdx
new file mode 100644
index 000000000..191b81ca2
--- /dev/null
+++ b/docs/integrations/scalekit.mdx
@@ -0,0 +1,155 @@
+---
+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.context import request_ctx
+import jwt
+
+@mcp.tool
+def inspect_token() -> dict:
+    """Inspect the current JWT token claims."""
+    context = request_ctx.get()
+
+    # Extract token from Authorization header
+    if hasattr(context, 'request') and hasattr(context.request, 'headers'):
+        auth_header = context.request.headers.get('authorization', '')
+        if auth_header.startswith('Bearer '):
+            token = auth_header[7:]
+            # Decode without verification (already verified by provider)
+            claims = jwt.decode(token, options={"verify_signature": False})
+            return claims
+
+    return {"error": "No token found"}
+```
diff --git a/docs/integrations/supabase.mdx b/docs/integrations/supabase.mdx
new file mode 100644
index 000000000..9ffda444d
--- /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 000000000..4f13a5512
--- /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/settings.mdx b/docs/more/settings.mdx
new file mode 100644
index 000000000..d2b4d0443
--- /dev/null
+++ b/docs/more/settings.mdx
@@ -0,0 +1,93 @@
+---
+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. Case-insensitive. |
+| `FASTMCP_LOG_ENABLED` | `bool` | `true` | Enable or disable FastMCP logging entirely. |
+| `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. |
+
+## 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_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_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. |
+
+## 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_DECORATOR_MODE` | `Literal["function", "object"]` | `function` | Controls what `@tool`, `@resource`, and `@prompt` decorators return. `function` returns the original function (default); `object` returns component objects (deprecated, will be removed). |
+| `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 000000000..fe32bdd75
--- /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 000000000..d2f812f52
--- /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/src/fastmcp/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python
+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 `src/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 000000000..7bd8600c5
--- /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/public/schemas/fastmcp.json/latest.json b/docs/public/schemas/fastmcp.json/latest.json
new file mode 100644
index 000000000..aa1f59ce4
--- /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 000000000..aa1f59ce4
--- /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/fastmcp-cli-__init__.mdx b/docs/python-sdk/fastmcp-cli-__init__.mdx
new file mode 100644
index 000000000..d2873740a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.cli`
+
+
+FastMCP CLI package.
diff --git a/docs/python-sdk/fastmcp-cli-auth.mdx b/docs/python-sdk/fastmcp-cli-auth.mdx
new file mode 100644
index 000000000..586a53505
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-auth.mdx
@@ -0,0 +1,9 @@
+---
+title: auth
+sidebarTitle: auth
+---
+
+# `fastmcp.cli.auth`
+
+
+Authentication-related CLI commands.
diff --git a/docs/python-sdk/fastmcp-cli-cimd.mdx b/docs/python-sdk/fastmcp-cli-cimd.mdx
new file mode 100644
index 000000000..2b4b73457
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-cimd.mdx
@@ -0,0 +1,43 @@
+---
+title: cimd
+sidebarTitle: cimd
+---
+
+# `fastmcp.cli.cimd`
+
+
+CIMD (Client ID Metadata Document) CLI commands.
+
+## Functions
+
+### `create_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cimd.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_command() -> 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.
+
+After creating the document, host it at an HTTPS URL with a non-root path,
+for example: https://myapp.example.com/oauth/client.json
+
+
+### `validate_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cimd.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_command(url: Annotated[str, cyclopts.Parameter(help='URL of the CIMD document to validate')]) -> 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
+
diff --git a/docs/python-sdk/fastmcp-cli-cli.mdx b/docs/python-sdk/fastmcp-cli-cli.mdx
new file mode 100644
index 000000000..60804a298
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-cli.mdx
@@ -0,0 +1,130 @@
+---
+title: cli
+sidebarTitle: cli
+---
+
+# `fastmcp.cli.cli`
+
+
+FastMCP CLI tools using Cyclopts.
+
+## Functions
+
+### `with_argv` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+version()
+```
+
+
+Display version information and platform details.
+
+
+### `inspector` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inspector(server_spec: str | None = None) -> 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
+
+
+### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(server_spec: str | None = None, *server_args: str) -> 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
+
+
+### `inspect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+inspect(server_spec: str | None = None) -> 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
+
+
+### `prepare` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L954" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 &lt;config&gt; --project &lt;output-dir&gt;
+
+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
+
diff --git a/docs/python-sdk/fastmcp-cli-client.mdx b/docs/python-sdk/fastmcp-cli-client.mdx
new file mode 100644
index 000000000..726663bfb
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-client.mdx
@@ -0,0 +1,135 @@
+---
+title: client
+sidebarTitle: client
+---
+
+# `fastmcp.cli.client`
+
+
+Client-side CLI commands for querying and invoking MCP servers.
+
+## Functions
+
+### `resolve_server_spec` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resolve_server_spec(server_spec: str | 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)``.
+
+
+### `coerce_value` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+coerce_value(raw: str, schema: dict[str, Any]) -> Any
+```
+
+
+Coerce a string CLI value according to a JSON-Schema type hint.
+
+
+### `parse_tool_arguments` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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``.
+
+
+### `format_tool_signature` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_tool_signature(tool: mcp.types.Tool) -> str
+```
+
+
+Build ``name(param: type, ...) -> return_type`` from a tool's JSON schemas.
+
+
+### `list_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L625" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_command(server_spec: Annotated[str | None, cyclopts.Parameter(help='Server URL, Python file, MCPConfig JSON, or .js file')] = 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
+
+
+### `call_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L774" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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) -> 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"]}'
+```
+
+
+### `discover_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/client.py#L875" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+discover_command() -> 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
+
diff --git a/docs/python-sdk/fastmcp-cli-discovery.mdx b/docs/python-sdk/fastmcp-cli-discovery.mdx
new file mode 100644
index 000000000..5892df9af
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-discovery.mdx
@@ -0,0 +1,71 @@
+---
+title: discovery
+sidebarTitle: discovery
+---
+
+# `fastmcp.cli.discovery`
+
+
+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.
+
+
+## Functions
+
+### `discover_servers` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/discovery.py#L314" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `resolve_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/discovery.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+## Classes
+
+### `DiscoveredServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/discovery.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A single MCP server found in an editor or project config.
+
+
+**Methods:**
+
+#### `qualified_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/discovery.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+qualified_name(self) -> str
+```
+
+Fully qualified ``source:name`` identifier.
+
+
+#### `transport_summary` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/discovery.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+transport_summary(self) -> str
+```
+
+Human-readable one-liner describing the transport.
+
diff --git a/docs/python-sdk/fastmcp-cli-generate.mdx b/docs/python-sdk/fastmcp-cli-generate.mdx
new file mode 100644
index 000000000..ebedaa186
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-generate.mdx
@@ -0,0 +1,66 @@
+---
+title: generate
+sidebarTitle: generate
+---
+
+# `fastmcp.cli.generate`
+
+
+Generate a standalone CLI script and agent skill from an MCP server.
+
+## Functions
+
+### `serialize_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/generate.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `generate_cli_script` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/generate.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `generate_skill_content` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/generate.py#L621" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `generate_cli_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/generate.py#L672" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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') -> 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
+
diff --git a/docs/python-sdk/fastmcp-cli-install-__init__.mdx b/docs/python-sdk/fastmcp-cli-install-__init__.mdx
new file mode 100644
index 000000000..3909565f2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.cli.install`
+
+
+Install subcommands for FastMCP CLI using Cyclopts.
diff --git a/docs/python-sdk/fastmcp-cli-install-claude_code.mdx b/docs/python-sdk/fastmcp-cli-install-claude_code.mdx
new file mode 100644
index 000000000..0a3393077
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-claude_code.mdx
@@ -0,0 +1,71 @@
+---
+title: claude_code
+sidebarTitle: claude_code
+---
+
+# `fastmcp.cli.install.claude_code`
+
+
+Claude Code integration for FastMCP install using Cyclopts.
+
+## Functions
+
+### `find_claude_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_code.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `check_claude_code_available` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_code.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+check_claude_code_available() -> bool
+```
+
+
+Check if Claude Code CLI is available.
+
+
+### `install_claude_code` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_code.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_claude_code(file: Path, server_object: str | None, name: str) -> 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
+
+
+### `claude_code_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_code.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+claude_code_command(server_spec: str) -> None
+```
+
+
+Install an MCP server in Claude Code.
+
+**Args:**
+- `server_spec`: Python file to install, optionally with \:object suffix
+
diff --git a/docs/python-sdk/fastmcp-cli-install-claude_desktop.mdx b/docs/python-sdk/fastmcp-cli-install-claude_desktop.mdx
new file mode 100644
index 000000000..23f7a1b27
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-claude_desktop.mdx
@@ -0,0 +1,58 @@
+---
+title: claude_desktop
+sidebarTitle: claude_desktop
+---
+
+# `fastmcp.cli.install.claude_desktop`
+
+
+Claude Desktop integration for FastMCP install using Cyclopts.
+
+## Functions
+
+### `get_claude_config_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_desktop.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_claude_config_path() -> Path | None
+```
+
+
+Get the Claude config directory based on platform.
+
+
+### `install_claude_desktop` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_desktop.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_claude_desktop(file: Path, server_object: str | None, name: str) -> 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
+
+**Returns:**
+- True if installation was successful, False otherwise
+
+
+### `claude_desktop_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/claude_desktop.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+claude_desktop_command(server_spec: str) -> None
+```
+
+
+Install an MCP server in Claude Desktop.
+
+**Args:**
+- `server_spec`: Python file to install, optionally with \:object suffix
+
diff --git a/docs/python-sdk/fastmcp-cli-install-cursor.mdx b/docs/python-sdk/fastmcp-cli-install-cursor.mdx
new file mode 100644
index 000000000..a61bca0ff
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-cursor.mdx
@@ -0,0 +1,107 @@
+---
+title: cursor
+sidebarTitle: cursor
+---
+
+# `fastmcp.cli.install.cursor`
+
+
+Cursor integration for FastMCP install using Cyclopts.
+
+## Functions
+
+### `generate_cursor_deeplink` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `open_deeplink` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `install_cursor_workspace` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_cursor_workspace(file: Path, server_object: str | None, name: str, workspace_path: Path) -> 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
+
+
+### `install_cursor` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_cursor(file: Path, server_object: str | None, name: str) -> 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
+
+
+### `cursor_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/cursor.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+cursor_command(server_spec: str) -> None
+```
+
+
+Install an MCP server in Cursor.
+
+**Args:**
+- `server_spec`: Python file to install, optionally with \:object suffix
+
diff --git a/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx
new file mode 100644
index 000000000..9cb51f0f4
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx
@@ -0,0 +1,68 @@
+---
+title: gemini_cli
+sidebarTitle: gemini_cli
+---
+
+# `fastmcp.cli.install.gemini_cli`
+
+
+Gemini CLI integration for FastMCP install using Cyclopts.
+
+## Functions
+
+### `find_gemini_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/gemini_cli.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+find_gemini_command() -> str | None
+```
+
+
+Find the Gemini CLI command.
+
+
+### `check_gemini_cli_available` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/gemini_cli.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+check_gemini_cli_available() -> bool
+```
+
+
+Check if Gemini CLI is available.
+
+
+### `install_gemini_cli` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/gemini_cli.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_gemini_cli(file: Path, server_object: str | None, name: str) -> 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
+
+
+### `gemini_cli_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/gemini_cli.py#L150" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+gemini_cli_command(server_spec: str) -> None
+```
+
+
+Install an MCP server in Gemini CLI.
+
+**Args:**
+- `server_spec`: Python file to install, optionally with \:object suffix
+
diff --git a/docs/python-sdk/fastmcp-cli-install-goose.mdx b/docs/python-sdk/fastmcp-cli-install-goose.mdx
new file mode 100644
index 000000000..cd2a8cc9a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-goose.mdx
@@ -0,0 +1,67 @@
+---
+title: goose
+sidebarTitle: goose
+---
+
+# `fastmcp.cli.install.goose`
+
+
+Goose integration for FastMCP install using Cyclopts.
+
+## Functions
+
+### `generate_goose_deeplink` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/goose.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_goose_deeplink(name: str, command: str, args: list[str]) -> 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.
+
+
+### `install_goose` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/goose.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_goose(file: Path, server_object: str | None, name: str) -> 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.
+
+
+### `goose_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/goose.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+goose_command(server_spec: str) -> 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
+
diff --git a/docs/python-sdk/fastmcp-cli-install-mcp_json.mdx b/docs/python-sdk/fastmcp-cli-install-mcp_json.mdx
new file mode 100644
index 000000000..a9eca1e51
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-mcp_json.mdx
@@ -0,0 +1,49 @@
+---
+title: mcp_json
+sidebarTitle: mcp_json
+---
+
+# `fastmcp.cli.install.mcp_json`
+
+
+MCP configuration JSON generation for FastMCP install using Cyclopts.
+
+## Functions
+
+### `install_mcp_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/mcp_json.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_mcp_json(file: Path, server_object: str | None, name: str) -> 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
+
+
+### `mcp_json_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/mcp_json.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+mcp_json_command(server_spec: str) -> None
+```
+
+
+Generate MCP configuration JSON for manual installation.
+
+**Args:**
+- `server_spec`: Python file to install, optionally with \:object suffix
+
diff --git a/docs/python-sdk/fastmcp-cli-install-shared.mdx b/docs/python-sdk/fastmcp-cli-install-shared.mdx
new file mode 100644
index 000000000..a1fe2119c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-shared.mdx
@@ -0,0 +1,50 @@
+---
+title: shared
+sidebarTitle: shared
+---
+
+# `fastmcp.cli.install.shared`
+
+
+Shared utilities for install commands.
+
+## Functions
+
+### `parse_env_var` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/shared.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_env_var(env_var: str) -> tuple[str, str]
+```
+
+
+Parse environment variable string in format KEY=VALUE.
+
+
+### `process_common_args` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/shared.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `open_deeplink` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/shared.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+open_deeplink(url: 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.
+
diff --git a/docs/python-sdk/fastmcp-cli-install-stdio.mdx b/docs/python-sdk/fastmcp-cli-install-stdio.mdx
new file mode 100644
index 000000000..62bdc8fde
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-install-stdio.mdx
@@ -0,0 +1,50 @@
+---
+title: stdio
+sidebarTitle: stdio
+---
+
+# `fastmcp.cli.install.stdio`
+
+
+Stdio command generation for FastMCP install using Cyclopts.
+
+## Functions
+
+### `install_stdio` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/stdio.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+install_stdio(file: Path, server_object: str | 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
+
+
+### `stdio_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/install/stdio.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+stdio_command(server_spec: str) -> 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
+
diff --git a/docs/python-sdk/fastmcp-cli-run.mdx b/docs/python-sdk/fastmcp-cli-run.mdx
new file mode 100644
index 000000000..0b341c459
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-run.mdx
@@ -0,0 +1,136 @@
+---
+title: run
+sidebarTitle: run
+---
+
+# `fastmcp.cli.run`
+
+
+FastMCP run command implementation with enhanced type hints.
+
+## Functions
+
+### `is_url` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_url(path: str) -> bool
+```
+
+
+Check if a string is a URL.
+
+
+### `create_client_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `create_mcp_config_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_mcp_config_server(mcp_config_path: Path) -> FastMCP[None]
+```
+
+
+Create a FastMCP server from a MCPConfig.
+
+
+### `load_mcp_server_config` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `run_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `run_module_command` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_module_command(module_name: str) -> 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.
+
+
+### `run_v1_server_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L299" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run_v1_server_async(server: FastMCP1x, 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
+
+
+### `run_with_reload` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/run.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-cli-tasks.mdx b/docs/python-sdk/fastmcp-cli-tasks.mdx
new file mode 100644
index 000000000..99f5dac1f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-cli-tasks.mdx
@@ -0,0 +1,41 @@
+---
+title: tasks
+sidebarTitle: tasks
+---
+
+# `fastmcp.cli.tasks`
+
+
+FastMCP tasks CLI for Docket task management.
+
+## Functions
+
+### `check_distributed_backend` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/tasks.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `worker` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/tasks.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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_*).
+
diff --git a/docs/python-sdk/fastmcp-client-__init__.mdx b/docs/python-sdk/fastmcp-client-__init__.mdx
new file mode 100644
index 000000000..bc145d4b7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-client-auth-__init__.mdx b/docs/python-sdk/fastmcp-client-auth-__init__.mdx
new file mode 100644
index 000000000..28242780d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-auth-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.auth`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-client-auth-bearer.mdx b/docs/python-sdk/fastmcp-client-auth-bearer.mdx
new file mode 100644
index 000000000..a6a53a3a6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-auth-bearer.mdx
@@ -0,0 +1,18 @@
+---
+title: bearer
+sidebarTitle: bearer
+---
+
+# `fastmcp.client.auth.bearer`
+
+## Classes
+
+### `BearerAuth` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/bearer.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `auth_flow` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/bearer.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+auth_flow(self, request)
+```
diff --git a/docs/python-sdk/fastmcp-client-auth-oauth.mdx b/docs/python-sdk/fastmcp-client-auth-oauth.mdx
new file mode 100644
index 000000000..455ea1337
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-auth-oauth.mdx
@@ -0,0 +1,104 @@
+---
+title: oauth
+sidebarTitle: oauth
+---
+
+# `fastmcp.client.auth.oauth`
+
+## Functions
+
+### `check_if_auth_required` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+## Classes
+
+### `ClientNotFoundError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Raised when OAuth client credentials are not found on the server.
+
+
+### `TokenStorageAdapter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `clear` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+clear(self) -> None
+```
+
+#### `get_tokens` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tokens(self) -> OAuthToken | None
+```
+
+#### `set_tokens` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_tokens(self, tokens: OAuthToken) -> None
+```
+
+#### `get_client_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_client_info(self) -> OAuthClientInformationFull | None
+```
+
+#### `set_client_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_client_info(self, client_info: OAuthClientInformationFull) -> None
+```
+
+### `OAuth` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `redirect_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+redirect_handler(self, authorization_url: str) -> None
+```
+
+Open browser for authorization, with pre-flight check for invalid client.
+
+
+#### `callback_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+callback_handler(self) -> tuple[str, str | None]
+```
+
+Handle OAuth callback and return (auth_code, state).
+
+
+#### `async_auth_flow` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/auth/oauth.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx
new file mode 100644
index 000000000..6c3ac689a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-client.mdx
@@ -0,0 +1,286 @@
+---
+title: client
+sidebarTitle: client
+---
+
+# `fastmcp.client.client`
+
+## Classes
+
+### `ClientSessionState` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+### `CallToolResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Parsed result from a tool call.
+
+
+### `Client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+**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"})
+```
+
+
+**Methods:**
+
+#### `session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+session(self) -> ClientSession
+```
+
+Get the current active session. Raises RuntimeError if not connected.
+
+
+#### `initialize_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+initialize_result(self) -> mcp.types.InitializeResult | None
+```
+
+Get the result of the initialization request.
+
+
+#### `set_roots` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L354" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_roots(self, roots: RootsList | RootsHandler) -> None
+```
+
+Set the roots for the client. This does not automatically call `send_roots_list_changed`.
+
+
+#### `set_sampling_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_sampling_callback(self, sampling_callback: SamplingHandler, sampling_capabilities: mcp.types.SamplingCapability | None = None) -> None
+```
+
+Set the sampling callback for the client.
+
+
+#### `set_elicitation_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None
+```
+
+Set the elicitation callback for the client.
+
+
+#### `is_connected` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_connected(self) -> bool
+```
+
+Check if the client is currently connected.
+
+
+#### `new` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `initialize` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L430" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `timeout`: Optional timeout for the initialization request (seconds or timedelta).
+If None, uses the client's init_timeout setting.
+
+**Returns:**
+- The server's initialization response containing server info,
+capabilities, protocol version, and optional instructions.
+
+**Raises:**
+- `RuntimeError`: If the client is not connected or initialization times out.
+
+
+#### `close` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L731" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close(self)
+```
+
+#### `ping` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L737" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ping(self) -> bool
+```
+
+Send a ping request.
+
+
+#### `cancel` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L742" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+cancel(self, request_id: str | int, reason: str | None = None) -> None
+```
+
+Send a cancellation notification for an in-progress request.
+
+
+#### `progress` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L759" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+progress(self, progress_token: str | int, progress: float, total: float | None = None, message: str | None = None) -> None
+```
+
+Send a progress notification.
+
+
+#### `set_logging_level` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L771" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_logging_level(self, level: mcp.types.LoggingLevel) -> None
+```
+
+Send a logging/setLevel request.
+
+
+#### `send_roots_list_changed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L775" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+send_roots_list_changed(self) -> None
+```
+
+Send a roots/list_changed notification.
+
+
+#### `complete_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L781" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`: The reference to complete.
+- `argument`: Arguments to pass to the completion request.
+- `context_arguments`: 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
+
+
+#### `complete` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L812" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`: The reference to complete.
+- `argument`: Arguments to pass to the completion request.
+- `context_arguments`: 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
+
+
+#### `generate_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/client.py#L839" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_name(cls, name: str | None = None) -> str
+```
diff --git a/docs/python-sdk/fastmcp-client-elicitation.mdx b/docs/python-sdk/fastmcp-client-elicitation.mdx
new file mode 100644
index 000000000..c9db14702
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-elicitation.mdx
@@ -0,0 +1,18 @@
+---
+title: elicitation
+sidebarTitle: elicitation
+---
+
+# `fastmcp.client.elicitation`
+
+## Functions
+
+### `create_elicitation_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/elicitation.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_elicitation_callback(elicitation_handler: ElicitationHandler) -> ElicitationFnT
+```
+
+## Classes
+
+### `ElicitResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/elicitation.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
diff --git a/docs/python-sdk/fastmcp-client-logging.mdx b/docs/python-sdk/fastmcp-client-logging.mdx
new file mode 100644
index 000000000..b9453a0be
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-logging.mdx
@@ -0,0 +1,24 @@
+---
+title: logging
+sidebarTitle: logging
+---
+
+# `fastmcp.client.logging`
+
+## Functions
+
+### `default_log_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/logging.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_log_handler(message: LogMessage) -> None
+```
+
+
+Default handler that properly routes server log messages to appropriate log levels.
+
+
+### `create_log_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/logging.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_log_callback(handler: LogHandler | None = None) -> LoggingFnT
+```
diff --git a/docs/python-sdk/fastmcp-client-messages.mdx b/docs/python-sdk/fastmcp-client-messages.mdx
new file mode 100644
index 000000000..fde8f0cde
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-messages.mdx
@@ -0,0 +1,107 @@
+---
+title: messages
+sidebarTitle: messages
+---
+
+# `fastmcp.client.messages`
+
+## Classes
+
+### `MessageHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `dispatch` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+dispatch(self, message: Message) -> None
+```
+
+#### `on_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_message(self, message: Message) -> None
+```
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, message: RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]) -> None
+```
+
+#### `on_ping` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_ping(self, message: mcp.types.PingRequest) -> None
+```
+
+#### `on_list_roots` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_roots(self, message: mcp.types.ListRootsRequest) -> None
+```
+
+#### `on_create_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_create_message(self, message: mcp.types.CreateMessageRequest) -> None
+```
+
+#### `on_notification` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_notification(self, message: mcp.types.ServerNotification) -> None
+```
+
+#### `on_exception` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_exception(self, message: Exception) -> None
+```
+
+#### `on_progress` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_progress(self, message: mcp.types.ProgressNotification) -> None
+```
+
+#### `on_logging_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_logging_message(self, message: mcp.types.LoggingMessageNotification) -> None
+```
+
+#### `on_tool_list_changed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_tool_list_changed(self, message: mcp.types.ToolListChangedNotification) -> None
+```
+
+#### `on_resource_list_changed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_resource_list_changed(self, message: mcp.types.ResourceListChangedNotification) -> None
+```
+
+#### `on_prompt_list_changed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_prompt_list_changed(self, message: mcp.types.PromptListChangedNotification) -> None
+```
+
+#### `on_resource_updated` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_resource_updated(self, message: mcp.types.ResourceUpdatedNotification) -> None
+```
+
+#### `on_cancelled` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/messages.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_cancelled(self, message: mcp.types.CancelledNotification) -> None
+```
diff --git a/docs/python-sdk/fastmcp-client-mixins-__init__.mdx b/docs/python-sdk/fastmcp-client-mixins-__init__.mdx
new file mode 100644
index 000000000..bc0e32a4c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-mixins-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.mixins`
+
+
+Client mixins for FastMCP.
diff --git a/docs/python-sdk/fastmcp-client-mixins-prompts.mdx b/docs/python-sdk/fastmcp-client-mixins-prompts.mdx
new file mode 100644
index 000000000..3931c03db
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-mixins-prompts.mdx
@@ -0,0 +1,119 @@
+---
+title: prompts
+sidebarTitle: prompts
+---
+
+# `fastmcp.client.mixins.prompts`
+
+
+Prompt-related methods for FastMCP Client.
+
+## Classes
+
+### `ClientPromptsMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing prompt-related methods for Client.
+
+
+**Methods:**
+
+#### `list_prompts_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts_mcp(self: Client) -> 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.
+
+**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
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self: Client) -> 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.
+
+**Returns:**
+- list\[mcp.types.Prompt]: A list of all Prompt objects.
+
+**Raises:**
+- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
+
+#### `get_prompt_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`: The name of the prompt to retrieve.
+- `arguments`: Arguments to pass to the prompt. Defaults to None.
+- `meta`: 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
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
+```
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> PromptTask
+```
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/prompts.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self: Client, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult | PromptTask
+```
+
+Retrieve a rendered prompt message list from the server.
+
+**Args:**
+- `name`: The name of the prompt to retrieve.
+- `arguments`: Arguments to pass to the prompt. Defaults to None.
+- `version`: Specific prompt version to get. If None, gets highest version.
+- `meta`: Optional request-level metadata.
+- `task`: If True, execute as background task (SEP-1686). Defaults to False.
+- `task_id`: Optional client-provided task ID (auto-generated if not provided).
+- `ttl`: 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
+
diff --git a/docs/python-sdk/fastmcp-client-mixins-resources.mdx b/docs/python-sdk/fastmcp-client-mixins-resources.mdx
new file mode 100644
index 000000000..655101ac3
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-mixins-resources.mdx
@@ -0,0 +1,158 @@
+---
+title: resources
+sidebarTitle: resources
+---
+
+# `fastmcp.client.mixins.resources`
+
+
+Resource-related methods for FastMCP Client.
+
+## Classes
+
+### `ClientResourcesMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing resource-related methods for Client.
+
+
+**Methods:**
+
+#### `list_resources_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources_mcp(self: Client) -> 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.
+
+**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
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self: Client) -> 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.
+
+**Returns:**
+- list\[mcp.types.Resource]: A list of all Resource objects.
+
+**Raises:**
+- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
+
+#### `list_resource_templates_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates_mcp(self: Client) -> 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.
+
+**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
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self: Client) -> 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.
+
+**Returns:**
+- list\[mcp.types.ResourceTemplate]: A list of all ResourceTemplate objects.
+
+**Raises:**
+- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
+
+#### `read_resource_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`: The URI of the resource to read. Can be a string or an AnyUrl object.
+- `meta`: 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
+
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self: Client, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
+```
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self: Client, uri: AnyUrl | str) -> ResourceTask
+```
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/resources.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self: Client, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask
+```
+
+Read the contents of a resource or resolved template.
+
+**Args:**
+- `uri`: The URI of the resource to read. Can be a string or an AnyUrl object.
+- `version`: Specific version to read. If None, reads highest version.
+- `meta`: Optional request-level metadata.
+- `task`: If True, execute as background task (SEP-1686). Defaults to False.
+- `task_id`: Optional client-provided task ID (auto-generated if not provided).
+- `ttl`: 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
+
diff --git a/docs/python-sdk/fastmcp-client-mixins-task_management.mdx b/docs/python-sdk/fastmcp-client-mixins-task_management.mdx
new file mode 100644
index 000000000..90d6d18b8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-mixins-task_management.mdx
@@ -0,0 +1,110 @@
+---
+title: task_management
+sidebarTitle: task_management
+---
+
+# `fastmcp.client.mixins.task_management`
+
+
+Task management methods for FastMCP Client.
+
+## Classes
+
+### `ClientTaskManagementMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/task_management.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing task management methods for Client.
+
+
+**Methods:**
+
+#### `get_task_status` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/task_management.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- Status information including taskId, status, pollInterval, etc.
+
+**Raises:**
+- `RuntimeError`: If client not connected
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
+
+#### `get_task_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/task_management.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- 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
+
+
+#### `list_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/task_management.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- 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
+
+
+#### `cancel_task` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/task_management.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- The task status showing cancelled state
+
+**Raises:**
+- `RuntimeError`: If task doesn't exist
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
diff --git a/docs/python-sdk/fastmcp-client-mixins-tools.mdx b/docs/python-sdk/fastmcp-client-mixins-tools.mdx
new file mode 100644
index 000000000..f048ed070
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-mixins-tools.mdx
@@ -0,0 +1,141 @@
+---
+title: tools
+sidebarTitle: tools
+---
+
+# `fastmcp.client.mixins.tools`
+
+
+Tool-related methods for FastMCP Client.
+
+## Classes
+
+### `ClientToolsMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing tool-related methods for Client.
+
+
+**Methods:**
+
+#### `list_tools_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools_mcp(self: Client) -> 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.
+
+**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
+
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self: Client) -> 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.
+
+**Returns:**
+- list\[mcp.types.Tool]: A list of all Tool objects.
+
+**Raises:**
+- `RuntimeError`: If called while the client is not connected.
+- `McpError`: If the request results in a TimeoutError | JSONRPCError
+
+
+#### `call_tool_mcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`: The name of the tool to call.
+- `arguments`: Arguments to pass to the tool.
+- `timeout`: The timeout for the tool call. Defaults to None.
+- `progress_handler`: The progress handler to use for the tool call. Defaults to None.
+- `meta`: 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
+
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult
+```
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> ToolTask
+```
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/mixins/tools.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> 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`: The name of the tool to call.
+- `arguments`: Arguments to pass to the tool. Defaults to None.
+- `version`: Specific tool version to call. If None, calls highest version.
+- `timeout`: The timeout for the tool call. Defaults to None.
+- `progress_handler`: The progress handler to use for the tool call. Defaults to None.
+- `raise_on_error`: Whether to raise an exception if the tool call results in an error. Defaults to True.
+- `meta`: 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`: If True, execute as background task (SEP-1686). Defaults to False.
+- `task_id`: Optional client-provided task ID (auto-generated if not provided).
+- `ttl`: 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.
+
diff --git a/docs/python-sdk/fastmcp-client-oauth_callback.mdx b/docs/python-sdk/fastmcp-client-oauth_callback.mdx
new file mode 100644
index 000000000..c3e3e84fb
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-oauth_callback.mdx
@@ -0,0 +1,70 @@
+---
+title: oauth_callback
+sidebarTitle: oauth_callback
+---
+
+# `fastmcp.client.oauth_callback`
+
+
+
+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.
+
+
+## Functions
+
+### `create_callback_html` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `create_oauth_callback_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_oauth_callback_server(port: int, 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)
+
+
+## Classes
+
+### `CallbackResponse` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `from_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_dict(cls, data: dict[str, str]) -> CallbackResponse
+```
+
+#### `to_dict` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_dict(self) -> dict[str, str]
+```
+
+### `OAuthCallbackResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/oauth_callback.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Container for OAuth callback results, used with anyio.Event for async coordination.
+
diff --git a/docs/python-sdk/fastmcp-client-progress.mdx b/docs/python-sdk/fastmcp-client-progress.mdx
new file mode 100644
index 000000000..884dab165
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-progress.mdx
@@ -0,0 +1,25 @@
+---
+title: progress
+sidebarTitle: progress
+---
+
+# `fastmcp.client.progress`
+
+## Functions
+
+### `default_progress_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/progress.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-client-roots.mdx b/docs/python-sdk/fastmcp-client-roots.mdx
new file mode 100644
index 000000000..8b429856a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-roots.mdx
@@ -0,0 +1,20 @@
+---
+title: roots
+sidebarTitle: roots
+---
+
+# `fastmcp.client.roots`
+
+## Functions
+
+### `convert_roots_list` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/roots.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_roots_list(roots: RootsList) -> list[mcp.types.Root]
+```
+
+### `create_roots_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/roots.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_roots_callback(handler: RootsList | RootsHandler) -> ListRootsFnT
+```
diff --git a/docs/python-sdk/fastmcp-client-sampling-__init__.mdx b/docs/python-sdk/fastmcp-client-sampling-__init__.mdx
new file mode 100644
index 000000000..609853b1f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-__init__.mdx
@@ -0,0 +1,14 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.sampling`
+
+## Functions
+
+### `create_sampling_callback` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/sampling/__init__.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_sampling_callback(sampling_handler: SamplingHandler) -> SamplingFnT
+```
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx
new file mode 100644
index 000000000..43329b5e6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.sampling.handlers`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx
new file mode 100644
index 000000000..976367c28
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-anthropic.mdx
@@ -0,0 +1,17 @@
+---
+title: anthropic
+sidebarTitle: anthropic
+---
+
+# `fastmcp.client.sampling.handlers.anthropic`
+
+
+Anthropic sampling handler for FastMCP.
+
+## Classes
+
+### `AnthropicSamplingHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/sampling/handlers/anthropic.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sampling handler that uses the Anthropic API.
+
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-google_genai.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-google_genai.mdx
new file mode 100644
index 000000000..9681c3a4a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-google_genai.mdx
@@ -0,0 +1,17 @@
+---
+title: google_genai
+sidebarTitle: google_genai
+---
+
+# `fastmcp.client.sampling.handlers.google_genai`
+
+
+Google GenAI sampling handler with tool support for FastMCP 3.0.
+
+## Classes
+
+### `GoogleGenaiSamplingHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/sampling/handlers/google_genai.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sampling handler that uses the Google GenAI API with tool support.
+
diff --git a/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx b/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx
new file mode 100644
index 000000000..b291bbaa5
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-sampling-handlers-openai.mdx
@@ -0,0 +1,17 @@
+---
+title: openai
+sidebarTitle: openai
+---
+
+# `fastmcp.client.sampling.handlers.openai`
+
+
+OpenAI sampling handler for FastMCP.
+
+## Classes
+
+### `OpenAISamplingHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/sampling/handlers/openai.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sampling handler that uses the OpenAI API.
+
diff --git a/docs/python-sdk/fastmcp-client-tasks.mdx b/docs/python-sdk/fastmcp-client-tasks.mdx
new file mode 100644
index 000000000..547d9bc92
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-tasks.mdx
@@ -0,0 +1,219 @@
+---
+title: tasks
+sidebarTitle: tasks
+---
+
+# `fastmcp.client.tasks`
+
+
+SEP-1686 client Task classes.
+
+## Classes
+
+### `TaskNotificationHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+MessageHandler that routes task status notifications to Task objects.
+
+
+**Methods:**
+
+#### `dispatch` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+dispatch(self, message: Message) -> None
+```
+
+Dispatch messages, including task status notifications.
+
+
+### `Task` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `task_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+task_id(self) -> str
+```
+
+Get the task ID.
+
+
+#### `returned_immediately` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `on_status_change` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `status` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+status(self) -> GetTaskResult
+```
+
+Get current task status.
+
+If server executed immediately, returns synthetic completed status.
+Otherwise queries the server for current status.
+
+
+#### `result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+result(self) -> TaskResultT
+```
+
+Wait for and return the task result.
+
+Must be implemented by subclasses to return the appropriate result type.
+
+
+#### `wait` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wait(self) -> 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 ('submitted', 'working', 'completed', 'failed').
+   If None, waits for any terminal state (completed/failed)
+- `timeout`: Maximum time to wait in seconds
+
+**Returns:**
+- Final task status
+
+**Raises:**
+- `TimeoutError`: If desired state not reached within timeout
+
+
+#### `cancel` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `ToolTask` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- The parsed tool result (same as call_tool returns)
+
+
+### `PromptTask` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- The prompt result with messages and description
+
+
+### `ResourceTask` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/tasks.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-client-telemetry.mdx b/docs/python-sdk/fastmcp-client-telemetry.mdx
new file mode 100644
index 000000000..9a1f8d260
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-telemetry.mdx
@@ -0,0 +1,23 @@
+---
+title: telemetry
+sidebarTitle: telemetry
+---
+
+# `fastmcp.client.telemetry`
+
+
+Client-side telemetry helpers.
+
+## Functions
+
+### `client_span` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/telemetry.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+client_span(name: str, method: str, component_key: str, session_id: str | None = None, resource_uri: 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.
+
diff --git a/docs/python-sdk/fastmcp-client-transports-__init__.mdx b/docs/python-sdk/fastmcp-client-transports-__init__.mdx
new file mode 100644
index 000000000..1f9b02d38
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.client.transports`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-client-transports-base.mdx b/docs/python-sdk/fastmcp-client-transports-base.mdx
new file mode 100644
index 000000000..12c1848d2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-base.mdx
@@ -0,0 +1,62 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.client.transports.base`
+
+## Classes
+
+### `SessionKwargs` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/base.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Keyword arguments for the MCP ClientSession constructor.
+
+
+### `ClientTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/base.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/base.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `close` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/base.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close(self)
+```
+
+Close the transport.
+
+
+#### `get_session_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/base.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_session_id(self) -> str | None
+```
+
+Get the session ID for this transport, if available.
+
diff --git a/docs/python-sdk/fastmcp-client-transports-config.mdx b/docs/python-sdk/fastmcp-client-transports-config.mdx
new file mode 100644
index 000000000..7ad10e0df
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-config.mdx
@@ -0,0 +1,72 @@
+---
+title: config
+sidebarTitle: config
+---
+
+# `fastmcp.client.transports.config`
+
+## Classes
+
+### `MCPConfigTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/config.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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")
+```
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/config.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
+```
+
+#### `close` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/config.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close(self)
+```
diff --git a/docs/python-sdk/fastmcp-client-transports-http.mdx b/docs/python-sdk/fastmcp-client-transports-http.mdx
new file mode 100644
index 000000000..a3375240e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-http.mdx
@@ -0,0 +1,37 @@
+---
+title: http
+sidebarTitle: http
+---
+
+# `fastmcp.client.transports.http`
+
+
+Streamable HTTP transport for FastMCP Client.
+
+## Classes
+
+### `StreamableHttpTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/http.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport implementation that connects to an MCP server via Streamable HTTP Requests.
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/http.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
+```
+
+#### `get_session_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/http.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_session_id(self) -> str | None
+```
+
+#### `close` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/http.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close(self)
+```
diff --git a/docs/python-sdk/fastmcp-client-transports-inference.mdx b/docs/python-sdk/fastmcp-client-transports-inference.mdx
new file mode 100644
index 000000000..730f56845
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-inference.mdx
@@ -0,0 +1,56 @@
+---
+title: inference
+sidebarTitle: inference
+---
+
+# `fastmcp.client.transports.inference`
+
+## Functions
+
+### `infer_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/inference.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+infer_transport(transport: ClientTransport | FastMCP | FastMCP1Server | 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 FastMCP1Server: 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)
+```
+
diff --git a/docs/python-sdk/fastmcp-client-transports-memory.mdx b/docs/python-sdk/fastmcp-client-transports-memory.mdx
new file mode 100644
index 000000000..b5887b8ca
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-memory.mdx
@@ -0,0 +1,27 @@
+---
+title: memory
+sidebarTitle: memory
+---
+
+# `fastmcp.client.transports.memory`
+
+## Classes
+
+### `FastMCPTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/memory.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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 2.x servers and FastMCP 1.0
+servers from the low-level MCP SDK. This is particularly useful for unit
+tests or scenarios where client and server run in the same runtime.
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/memory.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
+```
diff --git a/docs/python-sdk/fastmcp-client-transports-sse.mdx b/docs/python-sdk/fastmcp-client-transports-sse.mdx
new file mode 100644
index 000000000..59c145401
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-sse.mdx
@@ -0,0 +1,25 @@
+---
+title: sse
+sidebarTitle: sse
+---
+
+# `fastmcp.client.transports.sse`
+
+
+Server-Sent Events (SSE) transport for FastMCP Client.
+
+## Classes
+
+### `SSETransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/sse.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport implementation that connects to an MCP server via Server-Sent Events.
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/sse.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
+```
diff --git a/docs/python-sdk/fastmcp-client-transports-stdio.mdx b/docs/python-sdk/fastmcp-client-transports-stdio.mdx
new file mode 100644
index 000000000..eb7d98eb2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-client-transports-stdio.mdx
@@ -0,0 +1,79 @@
+---
+title: stdio
+sidebarTitle: stdio
+---
+
+# `fastmcp.client.transports.stdio`
+
+## Classes
+
+### `StdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `connect_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession]
+```
+
+#### `connect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+connect(self, **session_kwargs: Unpack[SessionKwargs]) -> ClientSession | None
+```
+
+#### `disconnect` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disconnect(self)
+```
+
+#### `close` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close(self)
+```
+
+### `PythonStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running Python scripts.
+
+
+### `FastMCPStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running FastMCP servers using the FastMCP CLI.
+
+
+### `NodeStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running Node.js scripts.
+
+
+### `UvStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L340" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running commands via the uv tool.
+
+
+### `UvxStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running commands via the uvx tool.
+
+
+### `NpxStdioTransport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/client/transports/stdio.py#L484" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transport for running commands via the npx tool.
+
diff --git a/docs/python-sdk/fastmcp-decorators.mdx b/docs/python-sdk/fastmcp-decorators.mdx
new file mode 100644
index 000000000..c2cc11dbb
--- /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/src/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/src/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/src/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 000000000..f27566ef3
--- /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 000000000..d8f5a6871
--- /dev/null
+++ b/docs/python-sdk/fastmcp-exceptions.mdx
@@ -0,0 +1,71 @@
+---
+title: exceptions
+sidebarTitle: exceptions
+---
+
+# `fastmcp.exceptions`
+
+
+Custom exceptions for FastMCP.
+
+## Classes
+
+### `FastMCPError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/exceptions.py#L6" 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/src/fastmcp/exceptions.py#L10" 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/src/fastmcp/exceptions.py#L14" 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/src/fastmcp/exceptions.py#L18" 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/src/fastmcp/exceptions.py#L22" 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/src/fastmcp/exceptions.py#L26" 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/src/fastmcp/exceptions.py#L30" 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/src/fastmcp/exceptions.py#L34" 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/src/fastmcp/exceptions.py#L38" 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/src/fastmcp/exceptions.py#L42" 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-__init__.mdx b/docs/python-sdk/fastmcp-experimental-__init__.mdx
new file mode 100644
index 000000000..04ef31f33
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.experimental`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-experimental-sampling-__init__.mdx b/docs/python-sdk/fastmcp-experimental-sampling-__init__.mdx
new file mode 100644
index 000000000..f37691267
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-sampling-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.experimental.sampling`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-experimental-sampling-handlers.mdx b/docs/python-sdk/fastmcp-experimental-sampling-handlers.mdx
new file mode 100644
index 000000000..9220684bb
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-sampling-handlers.mdx
@@ -0,0 +1,8 @@
+---
+title: handlers
+sidebarTitle: handlers
+---
+
+# `fastmcp.experimental.sampling.handlers`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-experimental-transforms-__init__.mdx b/docs/python-sdk/fastmcp-experimental-transforms-__init__.mdx
new file mode 100644
index 000000000..a33a00679
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-transforms-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.experimental.transforms`
+
+*This module is empty or contains only private/internal implementations.*
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 000000000..0553029eb
--- /dev/null
+++ b/docs/python-sdk/fastmcp-experimental-transforms-code_mode.mdx
@@ -0,0 +1,136 @@
+---
+title: code_mode
+sidebarTitle: code_mode
+---
+
+# `fastmcp.experimental.transforms.code_mode`
+
+## Classes
+
+### `SandboxProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/experimental/transforms/code_mode.py#L73" 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/src/fastmcp/experimental/transforms/code_mode.py#L82" 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/src/fastmcp/experimental/transforms/code_mode.py#L91" 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.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/experimental/transforms/code_mode.py#L109" 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/src/fastmcp/experimental/transforms/code_mode.py#L180" 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/src/fastmcp/experimental/transforms/code_mode.py#L262" 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/src/fastmcp/experimental/transforms/code_mode.py#L323" 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/src/fastmcp/experimental/transforms/code_mode.py#L390" 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/src/fastmcp/experimental/transforms/code_mode.py#L439" 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/src/fastmcp/experimental/transforms/code_mode.py#L489" 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/src/fastmcp/experimental/transforms/code_mode.py#L492" 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 000000000..f7d8f6e26
--- /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/src/fastmcp/mcp_config.py#L56" 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/src/fastmcp/mcp_config.py#L345" 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/src/fastmcp/mcp_config.py#L155" 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/src/fastmcp/mcp_config.py#L188" 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/src/fastmcp/mcp_config.py#L200" 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/src/fastmcp/mcp_config.py#L204" 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/src/fastmcp/mcp_config.py#L240" 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/src/fastmcp/mcp_config.py#L265" 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/src/fastmcp/mcp_config.py#L276" 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/src/fastmcp/mcp_config.py#L290" 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/src/fastmcp/mcp_config.py#L303" 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/src/fastmcp/mcp_config.py#L308" 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/src/fastmcp/mcp_config.py#L312" 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/src/fastmcp/mcp_config.py#L316" 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/src/fastmcp/mcp_config.py#L322" 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/src/fastmcp/mcp_config.py#L330" 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/src/fastmcp/mcp_config.py#L340" 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-prompts-__init__.mdx b/docs/python-sdk/fastmcp-prompts-__init__.mdx
new file mode 100644
index 000000000..8ef80b59e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-prompts-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.prompts`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-prompts-function_prompt.mdx b/docs/python-sdk/fastmcp-prompts-function_prompt.mdx
new file mode 100644
index 000000000..a3222afc0
--- /dev/null
+++ b/docs/python-sdk/fastmcp-prompts-function_prompt.mdx
@@ -0,0 +1,106 @@
+---
+title: function_prompt
+sidebarTitle: function_prompt
+---
+
+# `fastmcp.prompts.function_prompt`
+
+
+Standalone @prompt decorator for FastMCP.
+
+## Functions
+
+### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L398" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(name_or_fn: str | Callable[..., Any] | 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().
+
+
+## Classes
+
+### `DecoratedPrompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L49" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for functions decorated with @prompt.
+
+
+### `PromptMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata attached to functions by the @prompt decorator.
+
+
+### `FunctionPrompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A prompt that is a function.
+
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> 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
+
+
+#### `render` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render(self, arguments: dict[str, Any] | None = None) -> PromptResult
+```
+
+Render the prompt with arguments.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this prompt with docket for background execution.
+
+FunctionPrompt registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/function_prompt.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any] | 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()
+
diff --git a/docs/python-sdk/fastmcp-prompts-prompt.mdx b/docs/python-sdk/fastmcp-prompts-prompt.mdx
new file mode 100644
index 000000000..2fe759342
--- /dev/null
+++ b/docs/python-sdk/fastmcp-prompts-prompt.mdx
@@ -0,0 +1,145 @@
+---
+title: prompt
+sidebarTitle: prompt
+---
+
+# `fastmcp.prompts.prompt`
+
+
+Base classes for FastMCP prompts.
+
+## Classes
+
+### `Message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Wrapper for prompt message with auto-serialization.
+
+Accepts any content - strings pass through, other types
+(dict, list, BaseModel) are JSON-serialized to text.
+
+
+**Methods:**
+
+#### `to_mcp_prompt_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_prompt_message(self) -> PromptMessage
+```
+
+Convert to MCP PromptMessage.
+
+
+### `PromptArgument` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+An argument that can be passed to a prompt.
+
+
+### `PromptResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L108" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Canonical result type for prompt rendering.
+
+Provides explicit control over prompt responses: multiple messages,
+roles, and metadata at both the message and result level.
+
+
+**Methods:**
+
+#### `to_mcp_prompt_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_prompt_result(self) -> GetPromptResult
+```
+
+Convert to MCP GetPromptResult.
+
+
+### `Prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A prompt template that can be rendered with parameters.
+
+
+**Methods:**
+
+#### `to_mcp_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_prompt(self, **overrides: Any) -> SDKPrompt
+```
+
+Convert the prompt to an MCP prompt.
+
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> 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
+
+
+#### `render` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `convert_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+convert_result(self, raw_value: Any) -> PromptResult
+```
+
+Convert a raw return value to PromptResult.
+
+**Raises:**
+- `TypeError`: for unsupported types
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this prompt with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any] | 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()
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/prompts/prompt.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
diff --git a/docs/python-sdk/fastmcp-resources-__init__.mdx b/docs/python-sdk/fastmcp-resources-__init__.mdx
new file mode 100644
index 000000000..cc5fd2786
--- /dev/null
+++ b/docs/python-sdk/fastmcp-resources-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.resources`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-resources-function_resource.mdx b/docs/python-sdk/fastmcp-resources-function_resource.mdx
new file mode 100644
index 000000000..3a7d346e1
--- /dev/null
+++ b/docs/python-sdk/fastmcp-resources-function_resource.mdx
@@ -0,0 +1,93 @@
+---
+title: function_resource
+sidebarTitle: function_resource
+---
+
+# `fastmcp.resources.function_resource`
+
+
+Standalone @resource decorator for FastMCP.
+
+## Functions
+
+### `resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resource(uri: str) -> 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().
+
+
+## Classes
+
+### `DecoratedResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for functions decorated with @resource.
+
+
+### `ResourceMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata attached to functions by the @resource decorator.
+
+
+### `FunctionResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl | 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.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> str | bytes | ResourceResult
+```
+
+Read the resource by calling the wrapped function.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/function_resource.py#L225" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this resource with docket for background execution.
+
+FunctionResource registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
diff --git a/docs/python-sdk/fastmcp-resources-resource.mdx b/docs/python-sdk/fastmcp-resources-resource.mdx
new file mode 100644
index 000000000..029b48700
--- /dev/null
+++ b/docs/python-sdk/fastmcp-resources-resource.mdx
@@ -0,0 +1,180 @@
+---
+title: resource
+sidebarTitle: resource
+---
+
+# `fastmcp.resources.resource`
+
+
+Base classes and interfaces for FastMCP resources.
+
+## Classes
+
+### `ResourceContent` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `to_mcp_resource_contents` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `ResourceResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `to_mcp_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `Resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L210" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for all resources.
+
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl) -> FunctionResource
+```
+
+#### `set_default_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_default_mime_type(cls, mime_type: str | None) -> str
+```
+
+Set default MIME type if not provided.
+
+
+#### `set_default_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_default_name(self) -> Self
+```
+
+Set default name from URI if not provided.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `convert_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L303" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `to_mcp_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_resource(self, **overrides: Any) -> SDKResource
+```
+
+Convert the resource to an SDKResource.
+
+
+#### `key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L397" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+key(self) -> str
+```
+
+The globally unique lookup key for this resource.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this resource with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L408" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, **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()
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/resource.py#L429" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
diff --git a/docs/python-sdk/fastmcp-resources-template.mdx b/docs/python-sdk/fastmcp-resources-template.mdx
new file mode 100644
index 000000000..89e51c22f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-resources-template.mdx
@@ -0,0 +1,244 @@
+---
+title: template
+sidebarTitle: template
+---
+
+# `fastmcp.resources.template`
+
+
+Resource template functionality.
+
+## Functions
+
+### `extract_query_params` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+extract_query_params(uri_template: str) -> set[str]
+```
+
+
+Extract query parameter names from RFC 6570 `{?param1,param2}` syntax.
+
+
+### `build_regex` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+build_regex(template: str) -> re.Pattern
+```
+
+
+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)
+
+
+### `match_uri_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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}`
+
+
+## Classes
+
+### `ResourceTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A template for dynamically creating resources.
+
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+```
+
+#### `set_default_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_default_mime_type(cls, mime_type: str | None) -> str
+```
+
+Set default MIME type if not provided.
+
+
+#### `matches` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L169" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+matches(self, uri: str) -> dict[str, Any] | None
+```
+
+Check if URI matches template and extract parameters.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult
+```
+
+Read the resource content.
+
+
+#### `convert_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `to_mcp_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_template(self, **overrides: Any) -> SDKResourceTemplate
+```
+
+Convert the resource template to an SDKResourceTemplate.
+
+
+#### `from_mcp_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_template(cls, mcp_template: SDKResourceTemplate) -> ResourceTemplate
+```
+
+Creates a FastMCP ResourceTemplate from a raw MCP ResourceTemplate object.
+
+
+#### `key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+key(self) -> str
+```
+
+The globally unique lookup key for this template.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L292" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this template with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **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()
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `FunctionResourceTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A template for dynamically creating resources.
+
+
+**Methods:**
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_resource(self, uri: str, params: dict[str, Any]) -> Resource
+```
+
+Create a resource from the template with the given parameters.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L393" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult
+```
+
+Read the resource content.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this template with docket for background execution.
+
+FunctionResourceTemplate registers the underlying function, which has the
+user's Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **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()
+
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/template.py#L460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-resources-types.mdx b/docs/python-sdk/fastmcp-resources-types.mdx
new file mode 100644
index 000000000..d19b24eb2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-resources-types.mdx
@@ -0,0 +1,134 @@
+---
+title: types
+sidebarTitle: types
+---
+
+# `fastmcp.resources.types`
+
+
+Concrete resource implementations.
+
+## Classes
+
+### `TextResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource that reads from a string.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the text content.
+
+
+### `BinaryResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource that reads from bytes.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the binary content.
+
+
+### `FileResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource that reads from a file.
+
+Set is_binary=True to read file as binary data instead of text.
+
+
+**Methods:**
+
+#### `validate_absolute_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_absolute_path(cls, path: Path) -> Path
+```
+
+Ensure path is absolute.
+
+
+#### `set_binary_from_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool
+```
+
+Set is_binary based on mime_type if not explicitly set.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the file content.
+
+
+### `HttpResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource that reads from an HTTP endpoint.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the HTTP content.
+
+
+### `DirectoryResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource that lists files in a directory.
+
+
+**Methods:**
+
+#### `validate_absolute_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_absolute_path(cls, path: Path) -> Path
+```
+
+Ensure path is absolute.
+
+
+#### `list_files` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_files(self) -> list[Path]
+```
+
+List files in the directory.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/resources/types.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the directory listing.
+
diff --git a/docs/python-sdk/fastmcp-server-__init__.mdx b/docs/python-sdk/fastmcp-server-__init__.mdx
new file mode 100644
index 000000000..157a018ce
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-server-apps.mdx b/docs/python-sdk/fastmcp-server-apps.mdx
new file mode 100644
index 000000000..00e53eafe
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-apps.mdx
@@ -0,0 +1,86 @@
+---
+title: apps
+sidebarTitle: apps
+---
+
+# `fastmcp.server.apps`
+
+
+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/src/fastmcp/server/apps.py#L115" 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"]``.
+
+
+### `resolve_ui_mime_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/apps.py#L122" 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. This ensures UI resources are correctly
+identified regardless of how they're registered (via FastMCP.resource,
+the standalone @resource decorator, or resource templates).
+
+**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)
+
+
+## Classes
+
+### `ResourceCSP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/apps.py#L18" 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/src/fastmcp/server/apps.py#L50" 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/src/fastmcp/server/apps.py#L77" 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).
+
diff --git a/docs/python-sdk/fastmcp-server-auth-__init__.mdx b/docs/python-sdk/fastmcp-server-auth-__init__.mdx
new file mode 100644
index 000000000..c86f07005
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.auth`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-server-auth-auth.mdx b/docs/python-sdk/fastmcp-server-auth-auth.mdx
new file mode 100644
index 000000000..2186df875
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-auth.mdx
@@ -0,0 +1,382 @@
+---
+title: auth
+sidebarTitle: auth
+---
+
+# `fastmcp.server.auth.auth`
+
+## Classes
+
+### `AccessToken` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+AccessToken that includes all JWT claims.
+
+
+### `TokenHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `handle` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+handle(self, request: Any)
+```
+
+Wrap SDK handle() and transform auth error responses.
+
+
+### `PrivateKeyJWTClientAuthenticator` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `authenticate_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `AuthProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L236" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `set_mcp_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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")
+
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+#### `get_well_known_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+#### `get_middleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `TokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `scopes_supported` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify a bearer token and return access info if valid.
+
+
+### `RemoteAuthProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L389" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify token using the configured token verifier.
+
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L440" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_routes(self, mcp_path: str | None = None) -> list[Route]
+```
+
+Get routes for this provider.
+
+Creates protected resource metadata routes (RFC 9728).
+
+
+### `MultiAuth` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L472" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L537" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `set_mcp_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L558" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_mcp_path(self, mcp_path: str | None) -> None
+```
+
+Propagate MCP path to the server and all verifiers.
+
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L566" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_routes(self, mcp_path: str | None = None) -> list[Route]
+```
+
+Delegate route creation to the server.
+
+
+#### `get_well_known_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L572" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `OAuthProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L583" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+OAuth Authorization Server provider.
+
+This class provides full OAuth server functionality including client registration,
+authorization flows, token issuance, and token verification.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L646" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `get_well_known_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/auth.py#L740" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-authorization.mdx b/docs/python-sdk/fastmcp-server-auth-authorization.mdx
new file mode 100644
index 000000000..7465c43dc
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-authorization.mdx
@@ -0,0 +1,129 @@
+---
+title: authorization
+sidebarTitle: authorization
+---
+
+# `fastmcp.server.auth.authorization`
+
+
+Authorization checks for FastMCP components.
+
+This module provides callable-based authorization for tools, resources, and prompts.
+Auth checks are functions that receive an AuthContext and return True to allow access
+or False to deny.
+
+Auth checks can also raise exceptions:
+- AuthorizationError: Propagates with the custom message for explicit denial
+- Other exceptions: Masked for security (logged, treated as auth failure)
+
+Example:
+    ```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(): ...
+    ```
+
+
+## Functions
+
+### `require_scopes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/authorization.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+require_scopes(*scopes: str) -> AuthCheck
+```
+
+
+Require specific OAuth scopes.
+
+Returns an auth check that requires ALL specified scopes to be present
+in the token (AND logic).
+
+**Args:**
+- `*scopes`: One or more scope strings that must all be present.
+
+
+### `restrict_tag` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/authorization.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+restrict_tag(tag: str) -> AuthCheck
+```
+
+
+Restrict components with a specific tag to require certain scopes.
+
+If the component has the specified tag, the token must have ALL the
+required scopes. If the component doesn't have the tag, access is allowed.
+
+**Args:**
+- `tag`: The tag that triggers the scope requirement.
+- `scopes`: List of scopes required when the tag is present.
+
+
+### `run_auth_checks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/authorization.py#L134" 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.
+
+All checks must pass for authorization to succeed. Checks can be
+synchronous or asynchronous functions.
+
+Auth checks can:
+- Return True to allow access
+- Return False to deny access
+- Raise AuthorizationError to deny with a custom message (propagates)
+- Raise other exceptions (masked for security, treated as denial)
+
+**Args:**
+- `checks`: A single check function or list of check functions.
+Each check can be sync (returns bool) or async (returns Awaitable[bool]).
+- `ctx`: The auth context to pass to each check.
+
+**Returns:**
+- True if all checks pass, False if any check fails.
+
+**Raises:**
+- `AuthorizationError`: If an auth check explicitly raises it.
+
+
+## Classes
+
+### `AuthContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/authorization.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Context passed to auth check callables.
+
+This object is passed to each auth check function and provides
+access to the current authentication token and the component being accessed.
+
+**Attributes:**
+- `token`: The current access token, or None if unauthenticated.
+- `component`: The component (tool, resource, or prompt) being accessed.
+- `tool`: Backwards-compatible alias for component when it's a Tool.
+
+
+**Methods:**
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/authorization.py#L64" 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.
+
+Returns the component if it's a Tool, None otherwise.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-cimd.mdx b/docs/python-sdk/fastmcp-server-auth-cimd.mdx
new file mode 100644
index 000000000..dda5d28c6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-cimd.mdx
@@ -0,0 +1,242 @@
+---
+title: cimd
+sidebarTitle: cimd
+---
+
+# `fastmcp.server.auth.cimd`
+
+
+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
+
+
+## Classes
+
+### `CIMDDocument` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `validate_auth_method` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_auth_method(cls, v: str) -> str
+```
+
+Ensure no shared-secret auth methods are used.
+
+
+#### `validate_redirect_uris` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_redirect_uris(cls, v: list[str]) -> list[str]
+```
+
+Ensure redirect_uris is non-empty and each entry is a valid URI.
+
+
+### `CIMDValidationError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Raised when CIMD document validation fails.
+
+
+### `CIMDFetchError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Raised when CIMD document fetching fails.
+
+
+### `CIMDFetcher` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `is_cimd_client_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `fetch` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `validate_redirect_uri` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_redirect_uri(self, doc: CIMDDocument, redirect_uri: str) -> bool
+```
+
+Validate that a redirect_uri is allowed by the CIMD document.
+
+**Args:**
+- `doc`: The CIMD document
+- `redirect_uri`: The redirect URI to validate
+
+**Returns:**
+- True if valid, False otherwise
+
+
+### `CIMDAssertionValidator` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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)
+
+
+**Methods:**
+
+#### `validate_assertion` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L495" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `CIMDClientManager` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L677" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `is_cimd_client_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L711" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+#### `get_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L722" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `validate_private_key_jwt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/cimd.py#L771" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_private_key_jwt(self, assertion: str, client, 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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-jwt_issuer.mdx b/docs/python-sdk/fastmcp-server-auth-jwt_issuer.mdx
new file mode 100644
index 000000000..b30f3090b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-jwt_issuer.mdx
@@ -0,0 +1,106 @@
+---
+title: jwt_issuer
+sidebarTitle: jwt_issuer
+---
+
+# `fastmcp.server.auth.jwt_issuer`
+
+
+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.
+
+
+## Functions
+
+### `derive_jwt_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+derive_jwt_key() -> bytes
+```
+
+
+Derive JWT signing key from a high-entropy or low-entropy key material and server salt.
+
+
+## Classes
+
+### `JWTIssuer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `issue_access_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `issue_refresh_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> dict[str, Any]
+```
+
+Verify and decode a FastMCP token.
+
+Validates JWT signature, expiration, issuer, and audience.
+
+**Args:**
+- `token`: JWT token to verify
+
+**Returns:**
+- Decoded token payload
+
+**Raises:**
+- `JoseError`: If token is invalid, expired, or has wrong claims
+
diff --git a/docs/python-sdk/fastmcp-server-auth-middleware.mdx b/docs/python-sdk/fastmcp-server-auth-middleware.mdx
new file mode 100644
index 000000000..29217a9fe
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-middleware.mdx
@@ -0,0 +1,26 @@
+---
+title: middleware
+sidebarTitle: middleware
+---
+
+# `fastmcp.server.auth.middleware`
+
+
+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.
+
+
+## Classes
+
+### `RequireAuthMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/middleware.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy-__init__.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-__init__.mdx
new file mode 100644
index 000000000..7c4665aa8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-__init__.mdx
@@ -0,0 +1,16 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.auth.oauth_proxy`
+
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy-consent.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-consent.mdx
new file mode 100644
index 000000000..67c514ee7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-consent.mdx
@@ -0,0 +1,28 @@
+---
+title: consent
+sidebarTitle: consent
+---
+
+# `fastmcp.server.auth.oauth_proxy.consent`
+
+
+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.
+
+
+## Classes
+
+### `ConsentMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/consent.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy-models.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-models.mdx
new file mode 100644
index 000000000..a096e9e45
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-models.mdx
@@ -0,0 +1,105 @@
+---
+title: models
+sidebarTitle: models
+---
+
+# `fastmcp.server.auth.oauth_proxy.models`
+
+
+OAuth Proxy Models and Constants.
+
+This module contains all Pydantic models and constants used by the OAuth proxy.
+
+
+## Classes
+
+### `OAuthTransaction` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `ClientCode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `UpstreamTokenSet` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `JTIMapping` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `RefreshTokenMetadata` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `ProxyDCRClient` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `validate_redirect_uri` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/models.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 first, falling back to
+base validation (registered redirect_uris) if patterns don't match.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy-proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-proxy.mdx
new file mode 100644
index 000000000..dd1400086
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-proxy.mdx
@@ -0,0 +1,323 @@
+---
+title: proxy
+sidebarTitle: proxy
+---
+
+# `fastmcp.server.auth.oauth_proxy.proxy`
+
+
+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.
+
+
+## Classes
+
+### `OAuthProxy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `set_mcp_path` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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")
+
+
+#### `jwt_issuer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L601" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `register_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L645" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `authorize` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L698" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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), skip the consent screen
+and redirect directly to the upstream IdP.
+
+
+#### `load_authorization_code` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L817" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `exchange_authorization_code` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L865" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `load_refresh_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L1111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `exchange_refresh_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L1140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+#### `load_access_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L1384" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_access_token(self, token: str) -> AccessToken | None
+```
+
+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. Return upstream validation result
+
+The FastMCP JWT is a reference token - all authorization data comes
+from validating the upstream token via the TokenVerifier.
+
+
+#### `revoke_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L1460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/proxy.py#L1493" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy-ui.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-ui.mdx
new file mode 100644
index 000000000..fdbd2eb50
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy-ui.mdx
@@ -0,0 +1,50 @@
+---
+title: ui
+sidebarTitle: ui
+---
+
+# `fastmcp.server.auth.oauth_proxy.ui`
+
+
+OAuth Proxy UI Generation Functions.
+
+This module contains HTML generation functions for consent and error pages.
+
+
+## Functions
+
+### `create_consent_html` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/ui.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `create_error_html` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oauth_proxy/ui.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx
new file mode 100644
index 000000000..183380ed9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx
@@ -0,0 +1,82 @@
+---
+title: oidc_proxy
+sidebarTitle: oidc_proxy
+---
+
+# `fastmcp.server.auth.oidc_proxy`
+
+
+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
+
+
+## Classes
+
+### `OIDCConfiguration` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oidc_proxy.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+OIDC Configuration.
+
+
+**Methods:**
+
+#### `get_oidc_configuration` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oidc_proxy.py#L143" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_oidc_configuration(cls, config_url: AnyHttpUrl) -> 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
+
+
+### `OIDCProxy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oidc_proxy.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `get_oidc_configuration` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oidc_proxy.py#L432" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `get_token_verifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/oidc_proxy.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_token_verifier(self) -> 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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-__init__.mdx b/docs/python-sdk/fastmcp-server-auth-providers-__init__.mdx
new file mode 100644
index 000000000..9de7cce8a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.auth.providers`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx
new file mode 100644
index 000000000..140ddd193
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx
@@ -0,0 +1,41 @@
+---
+title: auth0
+sidebarTitle: auth0
+---
+
+# `fastmcp.server.auth.providers.auth0`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `Auth0Provider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/auth0.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx
new file mode 100644
index 000000000..5803d4f62
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx
@@ -0,0 +1,82 @@
+---
+title: aws
+sidebarTitle: aws
+---
+
+# `fastmcp.server.auth.providers.aws`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `AWSCognitoTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Token verifier that filters claims to Cognito-specific subset.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify token and filter claims to Cognito-specific subset.
+
+
+### `AWSCognitoProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `get_token_verifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/aws.py#L174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_token_verifier(self) -> TokenVerifier
+```
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx
new file mode 100644
index 000000000..4d3140c4a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx
@@ -0,0 +1,182 @@
+---
+title: azure
+sidebarTitle: azure
+---
+
+# `fastmcp.server.auth.providers.azure`
+
+
+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.
+
+
+## Functions
+
+### `EntraOBOToken` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L683" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+## Classes
+
+### `AzureProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `authorize` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `get_obo_credential` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L478" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- `ImportError`: If azure-identity is not installed (requires fastmcp[azure]).
+
+
+#### `close_obo_credentials` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L519" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+close_obo_credentials(self) -> None
+```
+
+Close all cached OBO credentials.
+
+
+### `AzureJWTVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L530" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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",
+    )
+
+
+**Methods:**
+
+#### `scopes_supported` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/azure.py#L610" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-debug.mdx b/docs/python-sdk/fastmcp-server-auth-providers-debug.mdx
new file mode 100644
index 000000000..8ed3e6b87
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-debug.mdx
@@ -0,0 +1,70 @@
+---
+title: debug
+sidebarTitle: debug
+---
+
+# `fastmcp.server.auth.providers.debug`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `DebugTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/debug.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/debug.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx
new file mode 100644
index 000000000..3436aa5c3
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx
@@ -0,0 +1,60 @@
+---
+title: descope
+sidebarTitle: descope
+---
+
+# `fastmcp.server.auth.providers.descope`
+
+
+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.
+
+
+## Classes
+
+### `DescopeProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/descope.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/descope.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-discord.mdx b/docs/python-sdk/fastmcp-server-auth-providers-discord.mdx
new file mode 100644
index 000000000..61b024b63
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-discord.mdx
@@ -0,0 +1,66 @@
+---
+title: discord
+sidebarTitle: discord
+---
+
+# `fastmcp.server.auth.providers.discord`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `DiscordTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/discord.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/discord.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify Discord OAuth token by calling Discord's tokeninfo API.
+
+
+### `DiscordProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/discord.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx
new file mode 100644
index 000000000..66a808136
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx
@@ -0,0 +1,66 @@
+---
+title: github
+sidebarTitle: github
+---
+
+# `fastmcp.server.auth.providers.github`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `GitHubTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/github.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/github.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify GitHub OAuth token by calling GitHub API.
+
+
+### `GitHubProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/github.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx
new file mode 100644
index 000000000..880488438
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx
@@ -0,0 +1,66 @@
+---
+title: google
+sidebarTitle: google
+---
+
+# `fastmcp.server.auth.providers.google`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `GoogleTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Token verifier for Google OAuth tokens.
+
+Google OAuth tokens are opaque (not JWTs), so we verify them
+by calling Google's tokeninfo API to check if they're valid and get user info.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify Google OAuth token by calling Google's tokeninfo API.
+
+
+### `GoogleProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/google.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx b/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx
new file mode 100644
index 000000000..c4ee4cc14
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx
@@ -0,0 +1,96 @@
+---
+title: in_memory
+sidebarTitle: in_memory
+---
+
+# `fastmcp.server.auth.providers.in_memory`
+
+## Classes
+
+### `InMemoryOAuthProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+An in-memory OAuth provider for testing purposes.
+It simulates the OAuth 2.1 flow locally without external calls.
+
+
+**Methods:**
+
+#### `get_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_client(self, client_id: str) -> OAuthClientInformationFull | None
+```
+
+#### `register_client` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_client(self, client_info: OAuthClientInformationFull) -> None
+```
+
+#### `authorize` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str
+```
+
+Simulates user authorization and generates an authorization code.
+Returns a redirect URI with the code and state.
+
+
+#### `load_authorization_code` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_authorization_code(self, client: OAuthClientInformationFull, authorization_code: str) -> AuthorizationCode | None
+```
+
+#### `exchange_authorization_code` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+exchange_authorization_code(self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode) -> OAuthToken
+```
+
+#### `load_refresh_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L215" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshToken | None
+```
+
+#### `exchange_refresh_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L230" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+exchange_refresh_token(self, client: OAuthClientInformationFull, refresh_token: RefreshToken, scopes: list[str]) -> OAuthToken
+```
+
+#### `load_access_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L287" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_access_token(self, token: str) -> AccessToken | None
+```
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `revoke_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/in_memory.py#L355" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+revoke_token(self, token: AccessToken | RefreshToken) -> None
+```
+
+Revokes an access or refresh token and its counterpart.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx b/docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx
new file mode 100644
index 000000000..811737e34
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx
@@ -0,0 +1,82 @@
+---
+title: introspection
+sidebarTitle: introspection
+---
+
+# `fastmcp.server.auth.providers.introspection`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `IntrospectionTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/introspection.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/introspection.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx b/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx
new file mode 100644
index 000000000..6ba9054c2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx
@@ -0,0 +1,146 @@
+---
+title: jwt
+sidebarTitle: jwt
+---
+
+# `fastmcp.server.auth.providers.jwt`
+
+
+TokenVerifier implementations for FastMCP.
+
+## Classes
+
+### `JWKData` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+JSON Web Key data structure.
+
+
+### `JWKSData` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+JSON Web Key Set data structure.
+
+
+### `RSAKeyPair` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+RSA key pair for JWT testing.
+
+
+**Methods:**
+
+#### `generate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate(cls) -> RSAKeyPair
+```
+
+Generate an RSA key pair for testing.
+
+**Returns:**
+- Generated key pair
+
+
+#### `create_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `JWTVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `load_access_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+load_access_token(self, token: str) -> AccessToken | None
+```
+
+Validate a JWT bearer token and return an AccessToken when the token is valid.
+
+**Args:**
+- `token`: 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.
+
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `StaticTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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!
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/jwt.py#L540" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify token against static token dictionary.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-oci.mdx b/docs/python-sdk/fastmcp-server-auth-providers-oci.mdx
new file mode 100644
index 000000000..b88c7c49e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-oci.mdx
@@ -0,0 +1,97 @@
+---
+title: oci
+sidebarTitle: oci
+---
+
+# `fastmcp.server.auth.providers.oci`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `OCIProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/oci.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-propelauth.mdx b/docs/python-sdk/fastmcp-server-auth-providers-propelauth.mdx
new file mode 100644
index 000000000..3b31b00d8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-propelauth.mdx
@@ -0,0 +1,69 @@
+---
+title: propelauth
+sidebarTitle: propelauth
+---
+
+# `fastmcp.server.auth.providers.propelauth`
+
+
+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)
+    ```
+
+
+## Classes
+
+### `PropelAuthTokenIntrospectionOverrides` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/propelauth.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `PropelAuthProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/propelauth.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+For detailed setup instructions, see:
+https://docs.propelauth.com/mcp-authentication/overview
+
+
+**Methods:**
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/propelauth.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/propelauth.py#L174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify token and check the ``aud`` claim against the configured resource.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx
new file mode 100644
index 000000000..1aa125c6c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx
@@ -0,0 +1,61 @@
+---
+title: scalekit
+sidebarTitle: scalekit
+---
+
+# `fastmcp.server.auth.providers.scalekit`
+
+
+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.
+
+
+## Classes
+
+### `ScalekitProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/scalekit.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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/
+
+
+**Methods:**
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/scalekit.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx b/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx
new file mode 100644
index 000000000..c44deecae
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx
@@ -0,0 +1,67 @@
+---
+title: supabase
+sidebarTitle: supabase
+---
+
+# `fastmcp.server.auth.providers.supabase`
+
+
+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.
+
+
+## Classes
+
+### `SupabaseProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/supabase.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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 (HS256, 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
+
+
+**Methods:**
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/supabase.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx
new file mode 100644
index 000000000..cb263d9ec
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx
@@ -0,0 +1,102 @@
+---
+title: workos
+sidebarTitle: workos
+---
+
+# `fastmcp.server.auth.providers.workos`
+
+
+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.
+
+
+## Classes
+
+### `WorkOSTokenVerifier` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `verify_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> AccessToken | None
+```
+
+Verify WorkOS OAuth token by calling userinfo endpoint.
+
+
+### `WorkOSProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+### `AuthKitProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L232" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `get_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/workos.py#L319" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-auth-redirect_validation.mdx b/docs/python-sdk/fastmcp-server-auth-redirect_validation.mdx
new file mode 100644
index 000000000..65155a160
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-redirect_validation.mdx
@@ -0,0 +1,63 @@
+---
+title: redirect_validation
+sidebarTitle: redirect_validation
+---
+
+# `fastmcp.server.auth.redirect_validation`
+
+
+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.
+
+
+## Functions
+
+### `matches_allowed_pattern` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/redirect_validation.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `validate_redirect_uri` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/redirect_validation.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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, all URIs are allowed (for DCR compatibility).
+             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
+
diff --git a/docs/python-sdk/fastmcp-server-auth-ssrf.mdx b/docs/python-sdk/fastmcp-server-auth-ssrf.mdx
new file mode 100644
index 000000000..c54ac5000
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-auth-ssrf.mdx
@@ -0,0 +1,172 @@
+---
+title: ssrf
+sidebarTitle: ssrf
+---
+
+# `fastmcp.server.auth.ssrf`
+
+
+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
+
+
+## Functions
+
+### `format_ip_for_url` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `is_ip_allowed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+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
+
+
+### `resolve_hostname` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `validate_url` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `ssrf_safe_fetch` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ssrf_safe_fetch(url: str) -> 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
+
+
+### `ssrf_safe_fetch_response` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L239" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+ssrf_safe_fetch_response(url: str) -> 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.
+
+
+## Classes
+
+### `SSRFError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Raised when an SSRF protection check fails.
+
+
+### `SSRFFetchError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Raised when SSRF-safe fetch fails.
+
+
+### `ValidatedURL` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A URL that has been validated for SSRF with resolved IPs.
+
+
+### `SSRFFetchResponse` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/ssrf.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Response payload from an SSRF-safe fetch.
+
diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx
new file mode 100644
index 000000000..58a916faf
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-context.mdx
@@ -0,0 +1,745 @@
+---
+title: context
+sidebarTitle: context
+---
+
+# `fastmcp.server.context`
+
+## Functions
+
+### `set_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_transport(transport: TransportType) -> Token[TransportType | None]
+```
+
+
+Set the current transport type. Returns token for reset.
+
+
+### `reset_transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+reset_transport(token: Token[TransportType | None]) -> None
+```
+
+
+Reset transport to previous value.
+
+
+### `set_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_context(context: Context) -> Generator[Context, None, None]
+```
+
+## Classes
+
+### `LogData` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `Context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `is_background_task` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `task_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `origin_request_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `fastmcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+fastmcp(self) -> FastMCP
+```
+
+Get the FastMCP instance.
+
+
+#### `request_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L321" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+request_context(self) -> RequestContext[ServerSession, Any, Request] | None
+```
+
+Access to the underlying request context.
+
+Returns None when the MCP session has not been established yet.
+Returns the full RequestContext 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)
+```
+
+
+#### `lifespan_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan_context(self) -> dict[str, Any]
+```
+
+Access the server's lifespan context.
+
+Returns the context dict yielded by the server's lifespan function.
+Returns an empty dict if no lifespan was configured or if the MCP
+session is not yet established.
+
+In background tasks (Docket workers), where request_context is not
+available, falls back to reading from the FastMCP server's lifespan
+result directly.
+
+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"
+```
+
+
+#### `report_progress` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L474" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> list[SDKResource]
+```
+
+List all available resources from the server.
+
+**Returns:**
+- List of Resource objects available on the server
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> list[SDKPrompt]
+```
+
+List all available prompts from the server.
+
+**Returns:**
+- List of Prompt objects available on the server
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L506" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self, uri: str | AnyUrl) -> ResourceResult
+```
+
+Read a resource by URI.
+
+**Args:**
+- `uri`: Resource URI to read
+
+**Returns:**
+- ResourceResult with contents
+
+
+#### `log` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L541" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `transport` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L571" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `client_supports_extension` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L579" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+Returns ``False`` when no session is available (e.g., outside a
+request context) or when the client did not advertise the extension.
+
+Example::
+
+    from fastmcp.server.apps 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"
+
+
+#### `client_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L607" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+client_id(self) -> str | None
+```
+
+Get the client ID if available.
+
+
+#### `request_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L616" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+request_id(self) -> str
+```
+
+Get the unique ID for this request.
+
+Raises RuntimeError if MCP request context is not available.
+
+
+#### `session_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L629" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L686" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `debug` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L712" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`.
+
+
+#### `info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L728" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`.
+
+
+#### `warning` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L744" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`.
+
+
+#### `error` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L760" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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`.
+
+
+#### `list_roots` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L776" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_roots(self) -> list[Root]
+```
+
+List the roots available to the server, as indicated by the client.
+
+
+#### `send_notification` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L781" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+send_notification(self, notification: mcp.types.ServerNotificationType) -> None
+```
+
+Send a notification to the client immediately.
+
+**Args:**
+- `notification`: An MCP notification instance (e.g., ToolListChangedNotification())
+
+
+#### `close_sse_stream` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L791" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `sample_step` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L830" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample_step(self, messages: str | Sequence[str | SamplingMessage]) -> 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)
+
+
+#### `sample` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L909" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]
+```
+
+Overload: With result_type, returns SamplingResult[ResultT].
+
+
+#### `sample` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L925" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[str]
+```
+
+Overload: Without result_type, returns SamplingResult[str].
+
+
+#### `sample` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L940" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample(self, messages: str | Sequence[str | SamplingMessage]) -> 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
+
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1015" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1027" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1037" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1047" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: dict[str, dict[str, str]]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1057" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: list[list[str]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1069" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+elicit(self, message: str, response_type: list[dict[str, dict[str, str]]]) -> AcceptedElicitation[list[str]] | DeclinedElicitation | CancelledElicitation
+```
+
+#### `elicit` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1081" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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) -> 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.
+
+If the response_type is None, the generated schema will be that of an
+empty object in order to comply with the MCP protocol requirements.
+Clients must send an empty object ("{}")in response.
+
+**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.
+
+
+#### `set_state` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_state(self, key: str, value: Any) -> 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.
+
+
+#### `get_state` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `delete_state` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1251" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+delete_state(self, key: str) -> None
+```
+
+Delete a value from the state store.
+
+Removes from both request-scoped and session-scoped stores.
+
+
+#### `enable_components` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable_components(self) -> 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.
+
+
+#### `disable_components` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable_components(self) -> 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.
+
+
+#### `reset_visibility` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/context.py#L1348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-dependencies.mdx b/docs/python-sdk/fastmcp-server-dependencies.mdx
new file mode 100644
index 000000000..60439e182
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-dependencies.mdx
@@ -0,0 +1,616 @@
+---
+title: dependencies
+sidebarTitle: dependencies
+---
+
+# `fastmcp.server.dependencies`
+
+
+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].
+
+
+## Functions
+
+### `get_task_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 session_id, or None if not in a task.
+
+
+### `register_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_task_session(session_id: str, session: ServerSession) -> None
+```
+
+
+Register a session for Context access in background tasks.
+
+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.
+
+**Args:**
+- `session_id`: The session identifier
+- `session`: The ServerSession instance
+
+
+### `get_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_task_session(session_id: str) -> ServerSession | None
+```
+
+
+Get a registered session by ID if still alive.
+
+**Args:**
+- `session_id`: The session identifier
+
+**Returns:**
+- The ServerSession if found and alive, None otherwise
+
+
+### `is_docket_available` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_docket_available() -> bool
+```
+
+
+Check if pydocket is installed.
+
+
+### `require_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `transform_context_annotations` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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__)
+
+
+### `get_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_context() -> Context
+```
+
+
+Get the current FastMCP Context instance directly.
+
+
+### `get_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_server() -> FastMCP
+```
+
+
+Get the current FastMCP server instance directly.
+
+**Returns:**
+- The active FastMCP server
+
+**Raises:**
+- `RuntimeError`: If no server in context
+
+
+### `get_http_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_http_request() -> Request
+```
+
+
+Get the current HTTP request.
+
+Tries MCP SDK's request_ctx first, then falls back to FastMCP's HTTP context.
+
+
+### `get_http_headers` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `get_access_token` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `without_injected_parameters` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L541" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+without_injected_parameters(fn: Callable[..., Any]) -> 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
+
+**Returns:**
+- Async wrapper function without injected parameters
+
+
+### `resolve_dependencies` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L690" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `CurrentContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L893" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `OptionalCurrentContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L918" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+OptionalCurrentContext() -> Context | None
+```
+
+
+Get the current FastMCP Context, or None when no context is active.
+
+
+### `CurrentDocket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L941" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `CurrentWorker` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L986" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `CurrentFastMCP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1028" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `CurrentRequest` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1063" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `CurrentHeaders` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1099" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `CurrentAccessToken` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1318" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `TokenClaim` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+## Classes
+
+### `TaskContextInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `ProgressLike` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for progress tracking interface.
+
+Defines the common interface between InMemoryProgress (server context)
+and Docket's Progress (worker context).
+
+
+**Methods:**
+
+#### `current` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+current(self) -> int | None
+```
+
+Current progress value.
+
+
+#### `total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+total(self) -> int
+```
+
+Total/target progress value.
+
+
+#### `message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+message(self) -> str | None
+```
+
+Current progress message.
+
+
+#### `set_total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_total(self, total: int) -> None
+```
+
+Set the total/target value for progress tracking.
+
+
+#### `increment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+increment(self, amount: int = 1) -> None
+```
+
+Atomically increment the current progress value.
+
+
+#### `set_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_message(self, message: str | None) -> None
+```
+
+Update the progress status message.
+
+
+### `InMemoryProgress` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `current` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1182" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+current(self) -> int | None
+```
+
+#### `total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1186" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+total(self) -> int
+```
+
+#### `message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+message(self) -> str | None
+```
+
+#### `set_total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_total(self, total: int) -> None
+```
+
+Set the total/target value for progress tracking.
+
+
+#### `increment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+increment(self, amount: int = 1) -> None
+```
+
+Atomically increment the current progress value.
+
+
+#### `set_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_message(self, message: str | None) -> None
+```
+
+Update the progress status message.
+
+
+### `Progress` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+FastMCP Progress dependency that works in both server and worker contexts.
+
+Handles three execution modes:
+- In Docket worker: Uses the execution's progress (observable via Redis)
+- In FastMCP server with Docket: Falls back to in-memory progress
+- In FastMCP server without Docket: Uses in-memory progress
+
+This allows tools to use Progress() regardless of whether they're called
+immediately or as background tasks, and regardless of whether pydocket
+is installed.
+
+
+**Methods:**
+
+#### `current` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+current(self) -> int | None
+```
+
+Current progress value.
+
+
+#### `total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+total(self) -> int
+```
+
+Total/target progress value.
+
+
+#### `message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+message(self) -> str | None
+```
+
+Current progress message.
+
+
+#### `set_total` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1267" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_total(self, total: int) -> None
+```
+
+Set the total/target value for progress tracking.
+
+
+#### `increment` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+increment(self, amount: int = 1) -> None
+```
+
+Atomically increment the current progress value.
+
+
+#### `set_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/dependencies.py#L1277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_message(self, message: str | None) -> None
+```
+
+Update the progress status message.
+
diff --git a/docs/python-sdk/fastmcp-server-elicitation.mdx b/docs/python-sdk/fastmcp-server-elicitation.mdx
new file mode 100644
index 000000000..85f140c6e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-elicitation.mdx
@@ -0,0 +1,145 @@
+---
+title: elicitation
+sidebarTitle: elicitation
+---
+
+# `fastmcp.server.elicitation`
+
+## Functions
+
+### `parse_elicit_response_type` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_elicit_response_type(response_type: Any) -> 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
+
+
+### `handle_elicit_accept` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `get_elicitation_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `validate_elicitation_json_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L343" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+## Classes
+
+### `ElicitationJsonSchema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `generate_inner` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_inner(self, schema: core_schema.CoreSchema) -> JsonSchemaValue
+```
+
+Override to prevent ref generation for enums and handle list schemas.
+
+
+#### `list_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_schema(self, schema: core_schema.ListSchema) -> JsonSchemaValue
+```
+
+Generate schema for list types, detecting enum items for multi-select.
+
+
+#### `enum_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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().
+
+
+### `AcceptedElicitation` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Result when user accepts the elicitation.
+
+
+### `ScalarElicitationType` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `ElicitConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/elicitation.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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)
+
diff --git a/docs/python-sdk/fastmcp-server-event_store.mdx b/docs/python-sdk/fastmcp-server-event_store.mdx
new file mode 100644
index 000000000..004e94405
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-event_store.mdx
@@ -0,0 +1,78 @@
+---
+title: event_store
+sidebarTitle: event_store
+---
+
+# `fastmcp.server.event_store`
+
+
+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.
+
+
+## Classes
+
+### `EventEntry` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/event_store.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Stored event entry.
+
+
+### `StreamEventList` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/event_store.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+List of event IDs for a stream.
+
+
+### `EventStore` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/event_store.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+**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.
+
+
+**Methods:**
+
+#### `store_event` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/event_store.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `replay_events_after` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/event_store.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-http.mdx b/docs/python-sdk/fastmcp-server-http.mdx
new file mode 100644
index 000000000..9b2fe758d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-http.mdx
@@ -0,0 +1,106 @@
+---
+title: http
+sidebarTitle: http
+---
+
+# `fastmcp.server.http`
+
+## Functions
+
+### `set_http_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+set_http_request(request: Request) -> Generator[Request, None, None]
+```
+
+### `create_base_app` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `create_sse_app` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `create_streamable_http_app` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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) -> 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
+
+**Returns:**
+- A Starlette application with StreamableHTTP support
+
+
+## Classes
+
+### `StreamableHTTPASGIApp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+ASGI application wrapper for Streamable HTTP server transport.
+
+
+### `StarletteWithLifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> Lifespan[Starlette]
+```
+
+### `RequestContextMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/http.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Middleware that stores each request in a ContextVar and sets transport type.
+
diff --git a/docs/python-sdk/fastmcp-server-lifespan.mdx b/docs/python-sdk/fastmcp-server-lifespan.mdx
new file mode 100644
index 000000000..08a67ddd9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-lifespan.mdx
@@ -0,0 +1,101 @@
+---
+title: lifespan
+sidebarTitle: lifespan
+---
+
+# `fastmcp.server.lifespan`
+
+
+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
+    ```
+
+
+## Functions
+
+### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/lifespan.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `fn`: An async generator function that takes a FastMCP server and yields
+a dict for the lifespan context.
+
+**Returns:**
+- A composable Lifespan wrapper.
+
+
+## Classes
+
+### `Lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/lifespan.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `ContextManagerLifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/lifespan.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Lifespan wrapper for already-wrapped context manager functions.
+
+Use this for functions already decorated with @asynccontextmanager.
+
+
+### `ComposedLifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/lifespan.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Two lifespans composed together.
+
+Enters the left lifespan first, then the right. Exits in reverse order.
+Results are shallow-merged into a single dict.
+
diff --git a/docs/python-sdk/fastmcp-server-low_level.mdx b/docs/python-sdk/fastmcp-server-low_level.mdx
new file mode 100644
index 000000000..78acc7225
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-low_level.mdx
@@ -0,0 +1,108 @@
+---
+title: low_level
+sidebarTitle: low_level
+---
+
+# `fastmcp.server.low_level`
+
+## Classes
+
+### `MiddlewareServerSession` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+ServerSession that routes initialization requests through FastMCP middleware.
+
+
+**Methods:**
+
+#### `fastmcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+fastmcp(self) -> FastMCP
+```
+
+Get the FastMCP instance.
+
+
+#### `client_supports_extension` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+client_supports_extension(self, extension_id: str) -> bool
+```
+
+Check if the connected client supports a given MCP extension.
+
+Inspects the ``extensions`` extra field on ``ClientCapabilities``
+sent by the client during initialization.
+
+
+### `LowLevelServer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `fastmcp` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+fastmcp(self) -> FastMCP
+```
+
+Get the FastMCP instance.
+
+
+#### `create_initialization_options` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_initialization_options(self, notification_options: NotificationOptions | None = None, experimental_capabilities: dict[str, dict[str, Any]] | None = None, **kwargs: Any) -> InitializationOptions
+```
+
+#### `get_capabilities` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_capabilities(self, notification_options: NotificationOptions, experimental_capabilities: dict[str, dict[str, Any]]) -> mcp.types.ServerCapabilities
+```
+
+Override to set capabilities.tasks as a first-class field per SEP-1686.
+
+This ensures task capabilities appear in capabilities.tasks instead of
+capabilities.experimental.tasks, which is required by the MCP spec and
+enables proper task detection by clients like VS Code Copilot 1.107+.
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, read_stream: MemoryObjectReceiveStream[SessionMessage | Exception], write_stream: MemoryObjectSendStream[SessionMessage], initialization_options: InitializationOptions, raise_exceptions: bool = False, stateless: bool = False)
+```
+
+Overrides the run method to use the MiddlewareServerSession.
+
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self) -> Callable[[Callable[[AnyUrl], Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult]]], Callable[[AnyUrl], Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult]]]
+```
+
+Decorator for registering a read_resource handler with CreateTaskResult support.
+
+The MCP SDK's read_resource decorator does not support returning CreateTaskResult
+for background task execution. This decorator wraps the result in ServerResult.
+
+This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+for resources.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/low_level.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self) -> Callable[[Callable[[str, dict[str, Any] | None], Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult]]], Callable[[str, dict[str, Any] | None], Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult]]]
+```
+
+Decorator for registering a get_prompt handler with CreateTaskResult support.
+
+The MCP SDK's get_prompt decorator does not support returning CreateTaskResult
+for background task execution. This decorator wraps the result in ServerResult.
+
+This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+for prompts.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-__init__.mdx b/docs/python-sdk/fastmcp-server-middleware-__init__.mdx
new file mode 100644
index 000000000..8583b1df9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.middleware`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-server-middleware-authorization.mdx b/docs/python-sdk/fastmcp-server-middleware-authorization.mdx
new file mode 100644
index 000000000..5bf859a09
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-authorization.mdx
@@ -0,0 +1,116 @@
+---
+title: authorization
+sidebarTitle: authorization
+---
+
+# `fastmcp.server.middleware.authorization`
+
+
+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"]))
+    ])
+    ```
+
+
+## Classes
+
+### `AuthMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
+
+**Methods:**
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult
+```
+
+Check auth before tool execution.
+
+
+#### `on_list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult]) -> ResourceResult
+```
+
+Check auth before resource read.
+
+
+#### `on_list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L255" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/authorization.py#L282" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, PromptResult]) -> PromptResult
+```
+
+Check auth before prompt render.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-caching.mdx b/docs/python-sdk/fastmcp-server-middleware-caching.mdx
new file mode 100644
index 000000000..66b86999d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-caching.mdx
@@ -0,0 +1,221 @@
+---
+title: caching
+sidebarTitle: caching
+---
+
+# `fastmcp.server.middleware.caching`
+
+
+A middleware for response caching.
+
+## Classes
+
+### `CachableResourceContent` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A wrapper for ResourceContent that can be cached.
+
+
+### `CachableResourceResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A wrapper for ResourceResult that can be cached.
+
+
+**Methods:**
+
+#### `get_size` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_size(self) -> int
+```
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, value: ResourceResult) -> Self
+```
+
+#### `unwrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+unwrap(self) -> ResourceResult
+```
+
+### `CachableToolResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, value: ToolResult) -> Self
+```
+
+#### `unwrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+unwrap(self) -> ToolResult
+```
+
+### `CachableMessage` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A wrapper for Message that can be cached.
+
+
+### `CachablePromptResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A wrapper for PromptResult that can be cached.
+
+
+**Methods:**
+
+#### `get_size` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_size(self) -> int
+```
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, value: PromptResult) -> Self
+```
+
+#### `unwrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+unwrap(self) -> PromptResult
+```
+
+### `SharedMethodSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Shared config for a cache method.
+
+
+### `ListToolsSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Tool-related caching.
+
+
+### `ListResourcesSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Resource-related caching.
+
+
+### `ListPromptsSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Prompt-related caching.
+
+
+### `CallToolSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Tool-related caching.
+
+
+### `ReadResourceSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L164" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Resource-related caching.
+
+
+### `GetPromptSettings` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L168" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration options for Prompt-related caching.
+
+
+### `ResponseCachingStatistics` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `ResponseCachingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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 method name and arguments.
+
+
+**Methods:**
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L324" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L433" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `on_get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `statistics` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/caching.py#L499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+statistics(self) -> ResponseCachingStatistics
+```
+
+Get the statistics for the cache.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-dereference.mdx b/docs/python-sdk/fastmcp-server-middleware-dereference.mdx
new file mode 100644
index 000000000..57c5edf88
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-dereference.mdx
@@ -0,0 +1,35 @@
+---
+title: dereference
+sidebarTitle: dereference
+---
+
+# `fastmcp.server.middleware.dereference`
+
+
+Middleware that dereferences $ref in JSON schemas before sending to clients.
+
+## Classes
+
+### `DereferenceRefsMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/dereference.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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)``.
+
+
+**Methods:**
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/dereference.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]]) -> Sequence[Tool]
+```
+
+#### `on_list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/dereference.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]) -> Sequence[ResourceTemplate]
+```
diff --git a/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx b/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx
new file mode 100644
index 000000000..3089f4d2c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx
@@ -0,0 +1,60 @@
+---
+title: error_handling
+sidebarTitle: error_handling
+---
+
+# `fastmcp.server.middleware.error_handling`
+
+
+Error handling middleware for consistent error responses and tracking.
+
+## Classes
+
+### `ErrorHandlingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/error_handling.py#L18" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/error_handling.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Handle errors for all messages.
+
+
+#### `get_error_stats` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/error_handling.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_error_stats(self) -> dict[str, int]
+```
+
+Get error statistics for monitoring.
+
+
+### `RetryMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/error_handling.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/error_handling.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Implement retry logic for requests.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-logging.mdx b/docs/python-sdk/fastmcp-server-middleware-logging.mdx
new file mode 100644
index 000000000..10f6933a1
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-logging.mdx
@@ -0,0 +1,58 @@
+---
+title: logging
+sidebarTitle: logging
+---
+
+# `fastmcp.server.middleware.logging`
+
+
+Comprehensive logging middleware for FastMCP servers.
+
+## Functions
+
+### `default_serializer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/logging.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_serializer(data: Any) -> str
+```
+
+
+The default serializer for Payloads in the logging middleware.
+
+
+## Classes
+
+### `BaseLoggingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/logging.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for logging middleware.
+
+
+**Methods:**
+
+#### `on_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/logging.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any
+```
+
+Log messages for configured methods.
+
+
+### `LoggingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/logging.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `StructuredLoggingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/logging.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx
new file mode 100644
index 000000000..04a87f554
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx
@@ -0,0 +1,112 @@
+---
+title: middleware
+sidebarTitle: middleware
+---
+
+# `fastmcp.server.middleware.middleware`
+
+## Functions
+
+### `make_middleware_wrapper` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+## Classes
+
+### `CallNext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `MiddlewareContext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Unified context for all middleware operations.
+
+
+**Methods:**
+
+#### `copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+copy(self, **kwargs: Any) -> MiddlewareContext[T]
+```
+
+### `Middleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Base class for FastMCP middleware with dispatching hooks.
+
+
+**Methods:**
+
+#### `on_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L128" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any
+```
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L135" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, context: MiddlewareContext[mt.Request[Any, Any]], call_next: CallNext[mt.Request[Any, Any], Any]) -> Any
+```
+
+#### `on_notification` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_notification(self, context: MiddlewareContext[mt.Notification[Any, Any]], call_next: CallNext[mt.Notification[Any, Any], Any]) -> Any
+```
+
+#### `on_initialize` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L149" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_initialize(self, context: MiddlewareContext[mt.InitializeRequest], call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None]) -> mt.InitializeResult | None
+```
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult
+```
+
+#### `on_read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult]) -> ResourceResult
+```
+
+#### `on_get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, PromptResult]) -> PromptResult
+```
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]]) -> Sequence[Tool]
+```
+
+#### `on_list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L184" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]]) -> Sequence[Resource]
+```
+
+#### `on_list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]) -> Sequence[ResourceTemplate]
+```
+
+#### `on_list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/middleware.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]]) -> Sequence[Prompt]
+```
diff --git a/docs/python-sdk/fastmcp-server-middleware-ping.mdx b/docs/python-sdk/fastmcp-server-middleware-ping.mdx
new file mode 100644
index 000000000..7ff39d339
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-ping.mdx
@@ -0,0 +1,32 @@
+---
+title: ping
+sidebarTitle: ping
+---
+
+# `fastmcp.server.middleware.ping`
+
+
+Ping middleware for keeping client connections alive.
+
+## Classes
+
+### `PingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/ping.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_message` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/ping.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_message(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Start ping task on first message from a session.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx b/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx
new file mode 100644
index 000000000..0ac2c263f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx
@@ -0,0 +1,97 @@
+---
+title: rate_limiting
+sidebarTitle: rate_limiting
+---
+
+# `fastmcp.server.middleware.rate_limiting`
+
+
+Rate limiting middleware for protecting FastMCP servers from abuse.
+
+## Classes
+
+### `RateLimitError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Error raised when rate limit is exceeded.
+
+
+### `TokenBucketRateLimiter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Token bucket implementation for rate limiting.
+
+
+**Methods:**
+
+#### `consume` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `SlidingWindowRateLimiter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L61" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Sliding window rate limiter implementation.
+
+
+**Methods:**
+
+#### `is_allowed` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_allowed(self) -> bool
+```
+
+Check if a request is allowed.
+
+
+### `RateLimitingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Apply rate limiting to requests.
+
+
+### `SlidingWindowRateLimitingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/rate_limiting.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Apply sliding window rate limiting to requests.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-response_limiting.mdx b/docs/python-sdk/fastmcp-server-middleware-response_limiting.mdx
new file mode 100644
index 000000000..0f344100b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-response_limiting.mdx
@@ -0,0 +1,32 @@
+---
+title: response_limiting
+sidebarTitle: response_limiting
+---
+
+# `fastmcp.server.middleware.response_limiting`
+
+
+Response limiting middleware for controlling tool response sizes.
+
+## Classes
+
+### `ResponseLimitingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/response_limiting.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/response_limiting.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult
+```
+
+Intercept tool calls and limit response size.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-timing.mdx b/docs/python-sdk/fastmcp-server-middleware-timing.mdx
new file mode 100644
index 000000000..533ff5de8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-timing.mdx
@@ -0,0 +1,105 @@
+---
+title: timing
+sidebarTitle: timing
+---
+
+# `fastmcp.server.middleware.timing`
+
+
+Timing middleware for measuring and logging request performance.
+
+## Classes
+
+### `TimingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L10" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_request` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time request execution and log the results.
+
+
+### `DetailedTimingMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_call_tool(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time tool execution.
+
+
+#### `on_read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_read_resource(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time resource reading.
+
+
+#### `on_get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_get_prompt(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time prompt retrieval.
+
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_tools(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time tool listing.
+
+
+#### `on_list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_resources(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time resource listing.
+
+
+#### `on_list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_resource_templates(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time resource template listing.
+
+
+#### `on_list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/timing.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_prompts(self, context: MiddlewareContext, call_next: CallNext) -> Any
+```
+
+Time prompt listing.
+
diff --git a/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx b/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx
new file mode 100644
index 000000000..6c9c01346
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-middleware-tool_injection.mdx
@@ -0,0 +1,91 @@
+---
+title: tool_injection
+sidebarTitle: tool_injection
+---
+
+# `fastmcp.server.middleware.tool_injection`
+
+
+A middleware for injecting tools into the MCP server context.
+
+## Functions
+
+### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(context: Context) -> list[Prompt]
+```
+
+
+List prompts available on the server.
+
+
+### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(context: Context, name: Annotated[str, 'The name of the prompt to render.'], arguments: Annotated[dict[str, Any] | None, 'The arguments to pass to the prompt.'] = None) -> mcp.types.GetPromptResult
+```
+
+
+Render a prompt available on the server.
+
+
+### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(context: Context) -> list[mcp.types.Resource]
+```
+
+
+List resources available on the server.
+
+
+### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(context: Context, uri: Annotated[AnyUrl | str, 'The URI of the resource to read.']) -> ResourceResult
+```
+
+
+Read a resource available on the server.
+
+
+## Classes
+
+### `ToolInjectionMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L21" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A middleware for injecting tools into the context.
+
+
+**Methods:**
+
+#### `on_list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_list_tools(self, context: MiddlewareContext[mcp.types.ListToolsRequest], call_next: CallNext[mcp.types.ListToolsRequest, Sequence[Tool]]) -> Sequence[Tool]
+```
+
+Inject tools into the response.
+
+
+#### `on_call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+on_call_tool(self, context: MiddlewareContext[mcp.types.CallToolRequestParams], call_next: CallNext[mcp.types.CallToolRequestParams, ToolResult]) -> ToolResult
+```
+
+Intercept tool calls to injected tools.
+
+
+### `PromptToolMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A middleware for injecting prompts as tools into the context.
+
+
+### `ResourceToolMiddleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/middleware/tool_injection.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A middleware for injecting resources as tools into the context.
+
diff --git a/docs/python-sdk/fastmcp-server-mixins-__init__.mdx b/docs/python-sdk/fastmcp-server-mixins-__init__.mdx
new file mode 100644
index 000000000..d35f9fc06
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-mixins-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.mixins`
+
+
+Server mixins for FastMCP.
diff --git a/docs/python-sdk/fastmcp-server-mixins-lifespan.mdx b/docs/python-sdk/fastmcp-server-mixins-lifespan.mdx
new file mode 100644
index 000000000..9d0eec22e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-mixins-lifespan.mdx
@@ -0,0 +1,30 @@
+---
+title: lifespan
+sidebarTitle: lifespan
+---
+
+# `fastmcp.server.mixins.lifespan`
+
+
+Lifespan and Docket task infrastructure for FastMCP Server.
+
+## Classes
+
+### `LifespanMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/lifespan.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing lifespan and Docket task infrastructure for FastMCP.
+
+
+**Methods:**
+
+#### `docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/lifespan.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+docket(self: FastMCP) -> Docket | None
+```
+
+Get the Docket instance if Docket support is enabled.
+
+Returns None if Docket is not enabled or server hasn't been started yet.
+
diff --git a/docs/python-sdk/fastmcp-server-mixins-mcp_operations.mdx b/docs/python-sdk/fastmcp-server-mixins-mcp_operations.mdx
new file mode 100644
index 000000000..0b6bef529
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-mixins-mcp_operations.mdx
@@ -0,0 +1,23 @@
+---
+title: mcp_operations
+sidebarTitle: mcp_operations
+---
+
+# `fastmcp.server.mixins.mcp_operations`
+
+
+MCP protocol handler setup and wire-format handlers for FastMCP Server.
+
+## Classes
+
+### `MCPOperationsMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/mcp_operations.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing MCP protocol handler setup and wire-format handlers.
+
+Note: Methods registered with SDK decorators (e.g., _list_tools_mcp, _call_tool_mcp)
+cannot use `self: FastMCP` type hints because the SDK's `get_type_hints()` fails
+to resolve FastMCP at runtime (it's only available under TYPE_CHECKING). When
+type hints fail to resolve, the SDK falls back to calling handlers with no arguments.
+These methods use untyped `self` to avoid this issue.
+
diff --git a/docs/python-sdk/fastmcp-server-mixins-transport.mdx b/docs/python-sdk/fastmcp-server-mixins-transport.mdx
new file mode 100644
index 000000000..c5cc4e2fd
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-mixins-transport.mdx
@@ -0,0 +1,131 @@
+---
+title: transport
+sidebarTitle: transport
+---
+
+# `fastmcp.server.mixins.transport`
+
+
+Transport-related methods for FastMCP Server.
+
+## Classes
+
+### `TransportMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin providing transport-related methods for FastMCP.
+
+Includes HTTP/stdio/SSE transport handling and custom HTTP routes.
+
+
+**Methods:**
+
+#### `run_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `custom_route` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+#### `run_stdio_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L158" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+#### `run_http_async` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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) -> 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
+
+
+#### `http_app` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/mixins/transport.py#L279" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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) -> 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.
+
+**Returns:**
+- A Starlette application configured with the specified transport
+
diff --git a/docs/python-sdk/fastmcp-server-openapi-__init__.mdx b/docs/python-sdk/fastmcp-server-openapi-__init__.mdx
new file mode 100644
index 000000000..af9cd5517
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-openapi-__init__.mdx
@@ -0,0 +1,27 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.openapi`
+
+
+OpenAPI server implementation for FastMCP.
+
+.. deprecated::
+    This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+
+The recommended approach is to use OpenAPIProvider with FastMCP:
+
+    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("My API Server")
+    mcp.add_provider(provider)
+
+FastMCPOpenAPI is still available but deprecated.
+
diff --git a/docs/python-sdk/fastmcp-server-openapi-components.mdx b/docs/python-sdk/fastmcp-server-openapi-components.mdx
new file mode 100644
index 000000000..320cc7092
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-openapi-components.mdx
@@ -0,0 +1,12 @@
+---
+title: components
+sidebarTitle: components
+---
+
+# `fastmcp.server.openapi.components`
+
+
+OpenAPI component implementations - backwards compatibility stub.
+
+This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+
diff --git a/docs/python-sdk/fastmcp-server-openapi-routing.mdx b/docs/python-sdk/fastmcp-server-openapi-routing.mdx
new file mode 100644
index 000000000..650a4a497
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-openapi-routing.mdx
@@ -0,0 +1,13 @@
+---
+title: routing
+sidebarTitle: routing
+---
+
+# `fastmcp.server.openapi.routing`
+
+
+Route mapping logic for OpenAPI operations.
+
+.. deprecated::
+    This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+
diff --git a/docs/python-sdk/fastmcp-server-openapi-server.mdx b/docs/python-sdk/fastmcp-server-openapi-server.mdx
new file mode 100644
index 000000000..4f751e090
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-openapi-server.mdx
@@ -0,0 +1,43 @@
+---
+title: server
+sidebarTitle: server
+---
+
+# `fastmcp.server.openapi.server`
+
+
+FastMCPOpenAPI - backwards compatibility wrapper.
+
+This class is deprecated. Use FastMCP with OpenAPIProvider instead:
+
+    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("My API Server", providers=[provider])
+
+
+## Classes
+
+### `FastMCPOpenAPI` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/openapi/server.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+FastMCP server implementation that creates components from an OpenAPI schema.
+
+.. deprecated::
+    Use FastMCP with OpenAPIProvider instead. This class will be
+    removed in a future version.
+
+Example (deprecated):
+    ```python
+    from fastmcp.server.openapi import FastMCPOpenAPI
+    import httpx
+
+    server = FastMCPOpenAPI(
+        openapi_spec=spec,
+        client=httpx.AsyncClient(),
+    )
+    ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
new file mode 100644
index 000000000..b7addb653
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-__init__.mdx
@@ -0,0 +1,34 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers`
+
+
+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)])
+    ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-aggregate.mdx b/docs/python-sdk/fastmcp-server-providers-aggregate.mdx
new file mode 100644
index 000000000..e0a8103da
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-aggregate.mdx
@@ -0,0 +1,83 @@
+---
+title: aggregate
+sidebarTitle: aggregate
+---
+
+# `fastmcp.server.providers.aggregate`
+
+
+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()
+    ```
+
+
+## Classes
+
+### `AggregateProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/aggregate.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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 (graceful degradation).
+
+
+**Methods:**
+
+#### `add_provider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/aggregate.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_provider(self, provider: Provider) -> 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"
+
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/aggregate.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Get all task-eligible components from all providers.
+
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/aggregate.py#L256" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+Combine lifespans of all providers.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-base.mdx b/docs/python-sdk/fastmcp-server-providers-base.mdx
new file mode 100644
index 000000000..09d02595b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-base.mdx
@@ -0,0 +1,306 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.server.providers.base`
+
+
+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)])
+    ```
+
+
+## Classes
+
+### `Provider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `transforms` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+transforms(self) -> list[Transform]
+```
+
+All transforms applied to components from this provider.
+
+
+#### `add_transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `wrap_transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> Sequence[Resource]
+```
+
+List resources with all transforms applied.
+
+Components may be marked as disabled but are NOT filtered here.
+
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> Sequence[ResourceTemplate]
+```
+
+List resource templates with all transforms applied.
+
+Components may be marked as disabled but are NOT filtered here.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L250" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> Sequence[Prompt]
+```
+
+List prompts with all transforms applied.
+
+Components may be marked as disabled but are NOT filtered here.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L260" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L418" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L463" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `enable` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L492" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable(self) -> 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.
+
+
+#### `disable` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/base.py#L541" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable(self) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
new file mode 100644
index 000000000..84d60da3d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-fastmcp_provider.mdx
@@ -0,0 +1,238 @@
+---
+title: fastmcp_provider
+sidebarTitle: fastmcp_provider
+---
+
+# `fastmcp.server.providers.fastmcp_provider`
+
+
+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.
+
+
+## Classes
+
+### `FastMCPProviderTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, tool: Tool) -> FastMCPProviderTool
+```
+
+Wrap a Tool to delegate execution to the server's middleware.
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `FastMCPProviderResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, resource: Resource) -> FastMCPProviderResource
+```
+
+Wrap a Resource to delegate reading to the server's middleware.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `FastMCPProviderPrompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, prompt: Prompt) -> FastMCPProviderPrompt
+```
+
+Wrap a Prompt to delegate rendering to the server's middleware.
+
+
+#### `render` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L316" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `FastMCPProviderResourceTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L342" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `wrap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+wrap(cls, server: Any, template: ResourceTemplate) -> FastMCPProviderResourceTemplate
+```
+
+Wrap a ResourceTemplate to create FastMCPProviderResources.
+
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L435" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L456" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+No-op: the child's actual template is registered via get_tasks().
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L459" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, params: dict[str, Any], **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.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L478" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `FastMCPProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L490" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L655" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/fastmcp_provider.py#L696" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+Start the mounted server's user lifespan.
+
+This starts only the wrapped server's user-defined lifespan, NOT its
+full _lifespan_manager() (which includes Docket). The parent server's
+Docket handles all background tasks.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-filesystem.mdx b/docs/python-sdk/fastmcp-server-providers-filesystem.mdx
new file mode 100644
index 000000000..d5b589e1e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-filesystem.mdx
@@ -0,0 +1,54 @@
+---
+title: filesystem
+sidebarTitle: filesystem
+---
+
+# `fastmcp.server.providers.filesystem`
+
+
+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")])
+    ```
+
+
+## Classes
+
+### `FileSystemProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
diff --git a/docs/python-sdk/fastmcp-server-providers-filesystem_discovery.mdx b/docs/python-sdk/fastmcp-server-providers-filesystem_discovery.mdx
new file mode 100644
index 000000000..060398177
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-filesystem_discovery.mdx
@@ -0,0 +1,104 @@
+---
+title: filesystem_discovery
+sidebarTitle: filesystem_discovery
+---
+
+# `fastmcp.server.providers.filesystem_discovery`
+
+
+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
+
+
+## Functions
+
+### `discover_files` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `import_module_from_file` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+import_module_from_file(file_path: Path) -> 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.
+
+**Args:**
+- `file_path`: Path to the Python file.
+
+**Returns:**
+- The imported module.
+
+**Raises:**
+- `ImportError`: If the module cannot be imported.
+
+
+### `extract_components` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L175" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+### `discover_and_import` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+## Classes
+
+### `DiscoveryResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Result of filesystem discovery.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx
new file mode 100644
index 000000000..5fe082a63
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx
@@ -0,0 +1,13 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers.local_provider`
+
+
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx
new file mode 100644
index 000000000..d6009a6de
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx
@@ -0,0 +1,13 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers.local_provider.decorators`
+
+
+Decorator mixins for LocalProvider.
+
+This module provides mixin classes that add decorator functionality
+to LocalProvider for tools, resources, templates, and prompts.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx
new file mode 100644
index 000000000..e7d7d68f9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx
@@ -0,0 +1,81 @@
+---
+title: prompts
+sidebarTitle: prompts
+---
+
+# `fastmcp.server.providers.local_provider.decorators.prompts`
+
+
+Prompt decorator mixin for LocalProvider.
+
+This module provides the PromptDecoratorMixin class that adds prompt
+registration functionality to LocalProvider.
+
+
+## Classes
+
+### `PromptDecoratorMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/prompts.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin class providing prompt decorator functionality for LocalProvider.
+
+This mixin contains all methods related to:
+- Prompt registration via add_prompt()
+- Prompt decorator (@provider.prompt)
+
+
+**Methods:**
+
+#### `add_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/prompts.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/prompts.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self: LocalProvider, name_or_fn: F) -> F
+```
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/prompts.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self: LocalProvider, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/prompts.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self: LocalProvider, name_or_fn: str | AnyFunction | 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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx
new file mode 100644
index 000000000..70c67d91c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx
@@ -0,0 +1,77 @@
+---
+title: resources
+sidebarTitle: resources
+---
+
+# `fastmcp.server.providers.local_provider.decorators.resources`
+
+
+Resource decorator mixin for LocalProvider.
+
+This module provides the ResourceDecoratorMixin class that adds resource
+and template registration functionality to LocalProvider.
+
+
+## Classes
+
+### `ResourceDecoratorMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/resources.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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)
+
+
+**Methods:**
+
+#### `add_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/resources.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `add_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/resources.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_template(self: LocalProvider, template: ResourceTemplate) -> ResourceTemplate
+```
+
+Add a resource template to this provider's storage.
+
+
+#### `resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/resources.py#L107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resource(self: LocalProvider, uri: str) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx
new file mode 100644
index 000000000..efeae3661
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx
@@ -0,0 +1,84 @@
+---
+title: tools
+sidebarTitle: tools
+---
+
+# `fastmcp.server.providers.local_provider.decorators.tools`
+
+
+Tool decorator mixin for LocalProvider.
+
+This module provides the ToolDecoratorMixin class that adds tool
+registration functionality to LocalProvider.
+
+
+## Classes
+
+### `ToolDecoratorMixin` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/tools.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mixin class providing tool decorator functionality for LocalProvider.
+
+This mixin contains all methods related to:
+- Tool registration via add_tool()
+- Tool decorator (@provider.tool)
+
+
+**Methods:**
+
+#### `add_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/tools.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/tools.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self: LocalProvider, name_or_fn: F) -> F
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/tools.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self: LocalProvider, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/decorators/tools.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self: LocalProvider, name_or_fn: str | AnyFunction | None = None) -> 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
+- `exclude_args`: Optional list of argument names to exclude from the tool schema
+- `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
+- `serializer`: Deprecated. Return ToolResult from your tools for full control over serialization.
+
+**Returns:**
+- The registered FunctionTool or a decorator function.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx
new file mode 100644
index 000000000..f3bc03205
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx
@@ -0,0 +1,125 @@
+---
+title: local_provider
+sidebarTitle: local_provider
+---
+
+# `fastmcp.server.providers.local_provider.local_provider`
+
+
+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])
+```
+
+
+## Classes
+
+### `LocalProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `remove_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `remove_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `remove_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L285" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `remove_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/local_provider/local_provider.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx
new file mode 100644
index 000000000..bd79a038b
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-__init__.mdx
@@ -0,0 +1,23 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers.openapi`
+
+
+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])
+    ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx
new file mode 100644
index 000000000..94f0b7b6a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-components.mdx
@@ -0,0 +1,62 @@
+---
+title: components
+sidebarTitle: components
+---
+
+# `fastmcp.server.providers.openapi.components`
+
+
+OpenAPI component classes: Tool, Resource, and ResourceTemplate.
+
+## Classes
+
+### `OpenAPITool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Tool implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any]) -> ToolResult
+```
+
+Execute the HTTP request using RequestDirector.
+
+
+### `OpenAPIResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L265" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Fetch the resource data by making an HTTP request.
+
+
+### `OpenAPIResourceTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Resource template implementation for OpenAPI endpoints.
+
+
+**Methods:**
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/components.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_resource(self, uri: str, params: dict[str, Any], context: Context | None = None) -> Resource
+```
+
+Create a resource with the given parameters.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
new file mode 100644
index 000000000..5d74c19ae
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-provider.mdx
@@ -0,0 +1,40 @@
+---
+title: provider
+sidebarTitle: provider
+---
+
+# `fastmcp.server.providers.openapi.provider`
+
+
+OpenAPIProvider for creating MCP components from OpenAPI specifications.
+
+## Classes
+
+### `OpenAPIProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L181" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+lifespan(self) -> AsyncIterator[None]
+```
+
+Manage the lifecycle of the auto-created httpx client.
+
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/provider.py#L431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tasks(self) -> Sequence[FastMCPComponent]
+```
+
+Return empty list - OpenAPI components don't support tasks.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx b/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx
new file mode 100644
index 000000000..c35ca5886
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-openapi-routing.mdx
@@ -0,0 +1,23 @@
+---
+title: routing
+sidebarTitle: routing
+---
+
+# `fastmcp.server.providers.openapi.routing`
+
+
+Route mapping logic for OpenAPI operations.
+
+## Classes
+
+### `MCPType` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/routing.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Type of FastMCP component to create from a route.
+
+
+### `RouteMap` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/openapi/routing.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Mapping configuration for HTTP routes to FastMCP component types.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-proxy.mdx b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
new file mode 100644
index 000000000..4c64d8566
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-proxy.mdx
@@ -0,0 +1,317 @@
+---
+title: proxy
+sidebarTitle: proxy
+---
+
+# `fastmcp.server.providers.proxy`
+
+
+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.
+
+
+## Functions
+
+### `default_proxy_roots_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L723" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_roots_handler(context: RequestContext[ClientSession, LifespanContextT]) -> RootsList
+```
+
+
+Forward list roots request from remote server to proxy's connected clients.
+
+
+### `default_proxy_sampling_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L731" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_sampling_handler(messages: list[mcp.types.SamplingMessage], params: mcp.types.CreateMessageRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> mcp.types.CreateMessageResult
+```
+
+
+Forward sampling request from remote server to proxy's connected clients.
+
+
+### `default_proxy_elicitation_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L754" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_elicitation_handler(message: str, response_type: type, params: mcp.types.ElicitRequestParams, context: RequestContext[ClientSession, LifespanContextT]) -> ElicitResult
+```
+
+
+Forward elicitation request from remote server to proxy's connected clients.
+
+
+### `default_proxy_log_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L776" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_log_handler(message: LogMessage) -> None
+```
+
+
+Forward log notification from remote server to proxy's connected clients.
+
+
+### `default_proxy_progress_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L784" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_proxy_progress_handler(progress: float, total: float | None, message: str | None) -> None
+```
+
+
+Forward progress notification from remote server to proxy's connected clients.
+
+
+## Classes
+
+### `ProxyTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Tool that represents and executes a tool on a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyTool
+```
+
+Override to preserve _backend_name when name changes.
+
+
+#### `from_mcp_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any], context: Context | None = None) -> ToolResult
+```
+
+Executes the tool by making a call through the client.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `ProxyResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L173" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Resource that represents and reads a resource from a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyResource
+```
+
+Override to preserve _backend_uri when uri changes.
+
+
+#### `from_mcp_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L208" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> ResourceResult
+```
+
+Read the resource content from the remote server.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L273" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `ProxyTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A ResourceTemplate that represents and creates resources from a remote server template.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L297" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyTemplate
+```
+
+Override to preserve _backend_uri_template when uri_template changes.
+
+
+#### `from_mcp_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_mcp_template(cls, client_factory: ClientFactoryT, mcp_template: mcp.types.ResourceTemplate) -> ProxyTemplate
+```
+
+Factory method to create a ProxyTemplate from a raw MCP template schema.
+
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L326" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L388" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `ProxyPrompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A Prompt that represents and renders a prompt from a remote server.
+
+
+**Methods:**
+
+#### `model_copy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L412" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+model_copy(self, **kwargs: Any) -> ProxyPrompt
+```
+
+Override to preserve _backend_name when name changes.
+
+
+#### `from_mcp_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L422" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `render` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L446" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render(self, arguments: dict[str, Any]) -> PromptResult
+```
+
+Render the prompt by making a call through the client.
+
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L468" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
+
+### `ProxyProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L480" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L605" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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".
+
+
+### `FastMCPProxy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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(...)).
+
+
+### `ProxyClient` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L848" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `StatefulProxyClient` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L881" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+Because session reuse means the receive-loop task inherits a stale
+``request_ctx`` ContextVar snapshot, the default proxy handlers are
+replaced with versions that restore the ContextVar before forwarding.
+``ProxyTool.run`` stashes the current ``RequestContext`` in
+``_proxy_rc_ref`` before each backend call, and the handlers consult
+it to detect (and correct) staleness.
+
+
+**Methods:**
+
+#### `clear` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L932" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+clear(self)
+```
+
+Clear all cached clients and force disconnect them.
+
+
+#### `new_stateful` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/proxy.py#L938" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-skills-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-skills-__init__.mdx
new file mode 100644
index 000000000..c3f296111
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-skills-__init__.mdx
@@ -0,0 +1,32 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.providers.skills`
+
+
+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/
+    ```
+
diff --git a/docs/python-sdk/fastmcp-server-providers-skills-claude_provider.mdx b/docs/python-sdk/fastmcp-server-providers-skills-claude_provider.mdx
new file mode 100644
index 000000000..30ed2c7c7
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-skills-claude_provider.mdx
@@ -0,0 +1,25 @@
+---
+title: claude_provider
+sidebarTitle: claude_provider
+---
+
+# `fastmcp.server.providers.skills.claude_provider`
+
+
+Claude-specific skills provider for Claude Code skills.
+
+## Classes
+
+### `ClaudeSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/claude_provider.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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().
+
diff --git a/docs/python-sdk/fastmcp-server-providers-skills-directory_provider.mdx b/docs/python-sdk/fastmcp-server-providers-skills-directory_provider.mdx
new file mode 100644
index 000000000..bf68a00e3
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-skills-directory_provider.mdx
@@ -0,0 +1,31 @@
+---
+title: directory_provider
+sidebarTitle: directory_provider
+---
+
+# `fastmcp.server.providers.skills.directory_provider`
+
+
+Directory scanning provider for discovering multiple skills.
+
+## Classes
+
+### `SkillsDirectoryProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/directory_provider.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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().
+
diff --git a/docs/python-sdk/fastmcp-server-providers-skills-skill_provider.mdx b/docs/python-sdk/fastmcp-server-providers-skills-skill_provider.mdx
new file mode 100644
index 000000000..c1ab56d9d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-skills-skill_provider.mdx
@@ -0,0 +1,121 @@
+---
+title: skill_provider
+sidebarTitle: skill_provider
+---
+
+# `fastmcp.server.providers.skills.skill_provider`
+
+
+Basic skill provider for handling a single skill folder.
+
+## Classes
+
+### `SkillResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource representing a skill's main file or manifest.
+
+
+**Methods:**
+
+#### `get_meta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_meta(self) -> dict[str, Any]
+```
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> str | bytes | ResourceResult
+```
+
+Read the resource content.
+
+
+### `SkillFileTemplate` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A template for accessing files within a skill.
+
+
+**Methods:**
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult
+```
+
+Read a file from the skill directory.
+
+
+#### `create_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L115" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `SkillFileResource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A resource representing a specific file within a skill.
+
+
+**Methods:**
+
+#### `get_meta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_meta(self) -> dict[str, Any]
+```
+
+#### `read` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read(self) -> str | bytes | ResourceResult
+```
+
+Read the file content.
+
+
+### `SkillProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `skill_info` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/skill_provider.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+skill_info(self) -> SkillInfo
+```
+
+Get the loaded skill info.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-skills-vendor_providers.mdx b/docs/python-sdk/fastmcp-server-providers-skills-vendor_providers.mdx
new file mode 100644
index 000000000..a5a724953
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-skills-vendor_providers.mdx
@@ -0,0 +1,56 @@
+---
+title: vendor_providers
+sidebarTitle: vendor_providers
+---
+
+# `fastmcp.server.providers.skills.vendor_providers`
+
+
+Vendor-specific skills providers for various AI coding platforms.
+
+## Classes
+
+### `CursorSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Cursor skills from ~/.cursor/skills/.
+
+
+### `VSCodeSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+VS Code skills from ~/.copilot/skills/.
+
+
+### `CodexSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Codex skills from /etc/codex/skills/ and ~/.codex/skills/.
+
+Scans both system-level and user-level directories. System skills take
+precedence if duplicates exist.
+
+
+### `GeminiSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Gemini skills from ~/.gemini/skills/.
+
+
+### `GooseSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Goose skills from ~/.config/agents/skills/.
+
+
+### `CopilotSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+GitHub Copilot skills from ~/.copilot/skills/.
+
+
+### `OpenCodeSkillsProvider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/skills/vendor_providers.py#L127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+OpenCode skills from ~/.config/opencode/skills/.
+
diff --git a/docs/python-sdk/fastmcp-server-providers-wrapped_provider.mdx b/docs/python-sdk/fastmcp-server-providers-wrapped_provider.mdx
new file mode 100644
index 000000000..22fc90b40
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-providers-wrapped_provider.mdx
@@ -0,0 +1,13 @@
+---
+title: wrapped_provider
+sidebarTitle: wrapped_provider
+---
+
+# `fastmcp.server.providers.wrapped_provider`
+
+
+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()`.
+
diff --git a/docs/python-sdk/fastmcp-server-proxy.mdx b/docs/python-sdk/fastmcp-server-proxy.mdx
new file mode 100644
index 000000000..a9200635c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-proxy.mdx
@@ -0,0 +1,14 @@
+---
+title: proxy
+sidebarTitle: proxy
+---
+
+# `fastmcp.server.proxy`
+
+
+Backwards compatibility - import from fastmcp.server.providers.proxy instead.
+
+This module re-exports all proxy-related classes from their new location
+at fastmcp.server.providers.proxy. Direct imports from this module are
+deprecated and will be removed in a future version.
+
diff --git a/docs/python-sdk/fastmcp-server-sampling-__init__.mdx b/docs/python-sdk/fastmcp-server-sampling-__init__.mdx
new file mode 100644
index 000000000..0b0533971
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.sampling`
+
+
+Sampling module for FastMCP servers.
diff --git a/docs/python-sdk/fastmcp-server-sampling-run.mdx b/docs/python-sdk/fastmcp-server-sampling-run.mdx
new file mode 100644
index 000000000..c09ad42d5
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-run.mdx
@@ -0,0 +1,203 @@
+---
+title: run
+sidebarTitle: run
+---
+
+# `fastmcp.server.sampling.run`
+
+
+Sampling types and helper functions for FastMCP servers.
+
+## Functions
+
+### `determine_handler_mode` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+determine_handler_mode(context: Context, needs_tools: bool) -> 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.
+
+**Returns:**
+- True if fallback handler should be used, False to use client.
+
+**Raises:**
+- `ValueError`: If client lacks required capability and no fallback configured.
+
+
+### `call_sampling_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_sampling_handler(context: Context, messages: list[SamplingMessage]) -> 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.
+
+
+### `execute_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L242" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `prepare_messages` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L352" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prepare_messages(messages: str | Sequence[str | SamplingMessage]) -> list[SamplingMessage]
+```
+
+
+Convert various message formats to a list of SamplingMessage objects.
+
+
+### `prepare_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `extract_tool_calls` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L407" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+extract_tool_calls(response: CreateMessageResult | CreateMessageResultWithTools) -> list[ToolUseContent]
+```
+
+
+Extract tool calls from a response.
+
+
+### `create_final_response_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L419" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `sample_step_impl` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L455" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample_step_impl(context: Context, messages: str | Sequence[str | SamplingMessage]) -> 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.
+
+
+### `sample_impl` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L572" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+sample_impl(context: Context, messages: str | Sequence[str | SamplingMessage]) -> 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.
+
+
+## Classes
+
+### `SamplingResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+### `SampleStep` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L69" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Result of a single sampling call.
+
+Represents what the LLM returned in this step plus the message history.
+
+
+**Methods:**
+
+#### `is_tool_use` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_tool_use(self) -> bool
+```
+
+True if the LLM is requesting tool execution.
+
+
+#### `text` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+text(self) -> str | None
+```
+
+Extract text from the response, if available.
+
+
+#### `tool_calls` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool_calls(self) -> list[ToolUseContent]
+```
+
+Get the list of tool calls from the response.
+
diff --git a/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx b/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx
new file mode 100644
index 000000000..cac91d36e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-sampling-sampling_tool.mdx
@@ -0,0 +1,101 @@
+---
+title: sampling_tool
+sidebarTitle: sampling_tool
+---
+
+# `fastmcp.server.sampling.sampling_tool`
+
+
+SamplingTool for use during LLM sampling requests.
+
+## Classes
+
+### `SamplingTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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")
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> 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.
+
+
+#### `from_callable_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/sampling_tool.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_callable_tool(cls, tool: FunctionTool | TransformedTool) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx
new file mode 100644
index 000000000..dbd0ad15a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-server.mdx
@@ -0,0 +1,910 @@
+---
+title: server
+sidebarTitle: server
+---
+
+# `fastmcp.server.server`
+
+
+FastMCP - A more ergonomic interface for MCP servers.
+
+## Functions
+
+### `default_lifespan` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `create_proxy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L2084" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_proxy(target: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | 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.
+
+
+## Classes
+
+### `StateValue` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Wrapper for stored context state values.
+
+
+### `FastMCP` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+name(self) -> str
+```
+
+#### `instructions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+instructions(self) -> str | None
+```
+
+#### `instructions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L361" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+instructions(self, value: str | None) -> None
+```
+
+#### `version` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L365" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+version(self) -> str | None
+```
+
+#### `website_url` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+website_url(self) -> str | None
+```
+
+#### `icons` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L373" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+icons(self) -> list[mcp.types.Icon]
+```
+
+#### `local_provider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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")
+
+
+#### `add_middleware` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_middleware(self, middleware: Middleware) -> None
+```
+
+#### `add_provider` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L405" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_provider(self, provider: Provider) -> 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"
+
+
+#### `get_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `add_transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L456" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `add_tool_transformation` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L476" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None
+```
+
+Add a tool transformation.
+
+.. deprecated::
+    Use ``add_transform(ToolTransform({...}))`` instead.
+
+
+#### `remove_tool_transformation` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L493" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_tool_transformation(self, _tool_name: str) -> None
+```
+
+Remove a tool transformation.
+
+.. deprecated::
+    Tool transformations are now immutable. Use enable/disable controls instead.
+
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L508" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self) -> 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.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L578" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `name`: The tool name.
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The tool if found and enabled, None otherwise.
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L604" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self) -> 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.
+
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L676" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `uri`: The resource URI.
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The resource if found and enabled, None otherwise.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L701" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self) -> 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.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L775" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `uri`: The template URI.
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The template if found and enabled, None otherwise.
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L800" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self) -> 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.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L870" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+**Args:**
+- `name`: The prompt name.
+- `version`: Version filter (None returns highest version).
+
+**Returns:**
+- The prompt if found and enabled, None otherwise.
+
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L896" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult
+```
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L907" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult
+```
+
+#### `call_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L917" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+call_tool(self, name: str, arguments: dict[str, Any] | 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
+
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1013" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self, uri: str) -> ResourceResult
+```
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1023" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self, uri: str) -> mcp.types.CreateTaskResult
+```
+
+#### `read_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1032" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+read_resource(self, uri: str) -> 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
+
+
+#### `render_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptResult
+```
+
+#### `render_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult
+```
+
+#### `render_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+render_prompt(self, name: str, arguments: dict[str, Any] | 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
+
+
+#### `add_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1263" 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 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.
+
+
+#### `remove_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+remove_tool(self, name: str, version: str | None = None) -> None
+```
+
+Remove tool(s) from the server.
+
+.. deprecated::
+    Use ``mcp.local_provider.remove_tool(name)`` instead.
+
+**Args:**
+- `name`: The name of the tool to remove.
+- `version`: If None, removes ALL versions. If specified, removes only that version.
+
+**Raises:**
+- `NotFoundError`: If no matching tool is found.
+
+
+#### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1307" 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/src/fastmcp/server/server.py#L1328" 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/src/fastmcp/server/server.py#L1348" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(self, name_or_fn: str | AnyFunction | None = None) -> 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
+- `exclude_args`: Optional list of argument names to exclude from the tool schema.
+Deprecated\: Use `Depends()` for dependency injection instead.
+- `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")
+```
+
+
+#### `add_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1447" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `add_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1471" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resource(self, uri: str) -> 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}"
+```
+
+
+#### `add_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1590" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1602" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: F) -> F
+```
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1618" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: str | None = None) -> Callable[[F], F]
+```
+
+#### `prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1633" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+prompt(self, name_or_fn: str | AnyFunction | 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:
+{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:
+{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")
+            ```
+
+
+#### `mount` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1733" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+mount(self, server: FastMCP[LifespanResultT], namespace: str | None = None, as_proxy: bool | None = None, tool_names: dict[str, str] | None = None, prefix: str | None = None) -> None
+```
+
+Mount another FastMCP server on this server with an optional namespace.
+
+Unlike importing (with import_server), 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.
+- `as_proxy`: Deprecated. Mounted servers now always have their lifespan and
+middleware invoked. To create a proxy server, use create_proxy()
+explicitly before mounting.
+- `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.
+- `prefix`: Deprecated. Use namespace instead.
+
+
+#### `import_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1827" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None) -> None
+```
+
+Import the MCP objects from another FastMCP server into this one,
+optionally with a given prefix.
+
+.. deprecated::
+    Use :meth:`mount` instead. ``import_server`` will be removed in a
+    future version.
+
+Note that when a server is *imported*, its objects are immediately
+registered to the importing server. This is a one-time operation and
+future changes to the imported server will not be reflected in the
+importing server. Server-level configurations and lifespans are not imported.
+
+When a server is imported with a prefix:
+- The tools are imported with prefixed names
+  Example: If server has a tool named "get_weather", it will be
+  available as "prefix_get_weather"
+- The resources are imported with prefixed URIs using the new format
+  Example: If server has a resource with URI "weather://forecast", it will
+  be available as "weather://prefix/forecast"
+- The templates are imported with prefixed URI templates using the new format
+  Example: If server has a template with URI "weather://location/{id}", it will
+  be available as "weather://prefix/location/{id}"
+- The prompts are imported with prefixed names
+  Example: If server has a prompt named "weather_prompt", it will be available as
+  "prefix_weather_prompt"
+
+When a server is imported without a prefix (prefix=None), its tools, resources,
+templates, and prompts are imported with their original names.
+
+**Args:**
+- `server`: The FastMCP server to import
+- `prefix`: Optional prefix to use for the imported server's objects. If None,
+objects are imported with their original names.
+
+
+#### `from_openapi` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1927" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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_fastapi` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L1978" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `as_proxy` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L2033" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy
+```
+
+Create a FastMCP proxy server for the given backend.
+
+.. deprecated::
+    Use :func:`fastmcp.server.create_proxy` instead.
+    This method will be removed in a future version.
+
+The `backend` argument can be either an existing `fastmcp.client.Client`
+instance or any value accepted as the `transport` argument of
+`fastmcp.client.Client`. This mirrors the convenience of the
+`fastmcp.client.Client` constructor.
+
+
+#### `generate_name` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/server.py#L2070" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_name(cls, name: str | None = None) -> str
+```
diff --git a/docs/python-sdk/fastmcp-server-tasks-__init__.mdx b/docs/python-sdk/fastmcp-server-tasks-__init__.mdx
new file mode 100644
index 000000000..9c9f5e88e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-__init__.mdx
@@ -0,0 +1,12 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.tasks`
+
+
+MCP SEP-1686 background tasks support.
+
+This module implements protocol-level background task execution for MCP servers.
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-capabilities.mdx b/docs/python-sdk/fastmcp-server-tasks-capabilities.mdx
new file mode 100644
index 000000000..03b1102dd
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-capabilities.mdx
@@ -0,0 +1,29 @@
+---
+title: capabilities
+sidebarTitle: capabilities
+---
+
+# `fastmcp.server.tasks.capabilities`
+
+
+SEP-1686 task capabilities declaration.
+
+## Functions
+
+### `get_task_capabilities` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/capabilities.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 pydocket is not installed (no task support).
+
+Note: prompts/resources are passed via extra_data since the SDK types
+don't include them yet (FastMCP supports them ahead of the spec).
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-config.mdx b/docs/python-sdk/fastmcp-server-tasks-config.mdx
new file mode 100644
index 000000000..0dc2bf4ba
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-config.mdx
@@ -0,0 +1,96 @@
+---
+title: config
+sidebarTitle: config
+---
+
+# `fastmcp.server.tasks.config`
+
+
+TaskConfig for MCP SEP-1686 background task execution modes.
+
+This module defines the configuration for how tools, resources, and prompts
+handle task-augmented execution as specified in SEP-1686.
+
+
+## Classes
+
+### `TaskMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata for task-augmented execution requests.
+
+When passed to call_tool/read_resource/get_prompt, signals that
+the operation should be submitted as a background task.
+
+**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/src/fastmcp/server/tasks/config.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Configuration for MCP background task execution (SEP-1686).
+
+Controls how a component handles task-augmented requests:
+
+- "forbidden": Component does not support task execution. Clients must not
+  request task augmentation; server returns -32601 if they do.
+- "optional": Component supports both synchronous and task execution.
+  Client may request task augmentation or call normally.
+- "required": Component requires task execution. Clients must request task
+  augmentation; server returns -32601 if they don't.
+
+
+**Methods:**
+
+#### `from_bool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_bool(cls, value: bool) -> TaskConfig
+```
+
+Convert boolean task flag to TaskConfig.
+
+**Args:**
+- `value`: True for "optional" mode, False for "forbidden" mode.
+
+**Returns:**
+- TaskConfig with appropriate mode.
+
+
+#### `supports_tasks` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+supports_tasks(self) -> bool
+```
+
+Check if this component supports task execution.
+
+**Returns:**
+- True if mode is "optional" or "required", False if "forbidden".
+
+
+#### `validate_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/config.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+validate_function(self, fn: Callable[..., Any], name: str) -> None
+```
+
+Validate that function is compatible with this task config.
+
+Task execution requires:
+1. fastmcp[tasks] to be installed (pydocket)
+2. Async functions
+
+Raises ImportError if mode is "optional" or "required" but pydocket
+is not installed. Raises ValueError if function is synchronous.
+
+**Args:**
+- `fn`: The function to validate (handles callable classes and staticmethods).
+- `name`: Name for error messages.
+
+**Raises:**
+- `ImportError`: If task execution is enabled but pydocket not installed.
+- `ValueError`: If task execution is enabled but function is sync.
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-elicitation.mdx b/docs/python-sdk/fastmcp-server-tasks-elicitation.mdx
new file mode 100644
index 000000000..cc6f3dea2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-elicitation.mdx
@@ -0,0 +1,96 @@
+---
+title: elicitation
+sidebarTitle: elicitation
+---
+
+# `fastmcp.server.tasks.elicitation`
+
+
+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.
+
+
+## Functions
+
+### `elicit_for_task` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `relay_elicitation` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+relay_elicitation(session: ServerSession, session_id: str, 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
+- `session_id`: Session identifier
+- `task_id`: Background task ID
+- `elicitation`: Elicitation metadata (message, requestedSchema)
+- `fastmcp`: FastMCP server instance
+
+
+### `handle_task_input` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+handle_task_input(task_id: str, session_id: str, 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
+- `session_id`: The MCP session ID
+- `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
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-handlers.mdx b/docs/python-sdk/fastmcp-server-tasks-handlers.mdx
new file mode 100644
index 000000000..31f228f14
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-handlers.mdx
@@ -0,0 +1,41 @@
+---
+title: handlers
+sidebarTitle: handlers
+---
+
+# `fastmcp.server.tasks.handlers`
+
+
+SEP-1686 task execution handlers.
+
+Handles queuing tool/prompt/resource executions to Docket as background tasks.
+
+
+## Functions
+
+### `submit_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/handlers.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- Task stub with proper Task object
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-keys.mdx b/docs/python-sdk/fastmcp-server-tasks-keys.mdx
new file mode 100644
index 000000000..a274d3c1d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-keys.mdx
@@ -0,0 +1,89 @@
+---
+title: keys
+sidebarTitle: keys
+---
+
+# `fastmcp.server.tasks.keys`
+
+
+Task key management for SEP-1686 background tasks.
+
+Task keys encode security scoping and metadata in the Docket key format:
+    `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
+
+This format provides:
+- Session-based security scoping (prevents cross-session access)
+- Task type identification (tool/prompt/resource)
+- Component identification (name or URI for result conversion)
+
+
+## Functions
+
+### `build_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+build_task_key(session_id: str, client_task_id: str, task_type: str, component_identifier: str) -> str
+```
+
+
+Build Docket task key with embedded metadata.
+
+Format: `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
+
+The component_identifier is URI-encoded to handle special characters (colons, slashes, etc.).
+
+**Args:**
+- `session_id`: Session ID for security scoping
+- `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("session123", "task456", "tool", "my_tool")
+'session123:task456:tool:my_tool'
+>>> build_task_key("session123", "task456", "resource", "file://data.txt")
+'session123:task456:resource:file%3A%2F%2Fdata.txt'
+
+
+### `parse_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse_task_key(task_key: str) -> dict[str, str]
+```
+
+
+Parse Docket task key to extract metadata.
+
+**Args:**
+- `task_key`: Encoded task key from Docket
+
+**Returns:**
+- Dict with keys: session_id, client_task_id, task_type, component_identifier
+
+**Examples:**
+
+>>> parse_task_key("session123:task456:tool:my_tool")
+`{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
+>>> parse_task_key("session123:task456:resource:file%3A%2F%2Fdata.txt")
+`{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'resource', 'component_identifier': 'file://data.txt'}`
+
+
+### `get_client_task_id_from_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 (second segment)
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-notifications.mdx b/docs/python-sdk/fastmcp-server-tasks-notifications.mdx
new file mode 100644
index 000000000..217b4b6ac
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-notifications.mdx
@@ -0,0 +1,113 @@
+---
+title: notifications
+sidebarTitle: notifications
+---
+
+# `fastmcp.server.tasks.notifications`
+
+
+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).
+
+
+## Functions
+
+### `push_notification` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/notifications.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `notification_subscriber_loop` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/notifications.py#L76" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `ensure_subscriber_running` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/notifications.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `stop_subscriber` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/notifications.py#L278" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `get_subscriber_count` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/notifications.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_subscriber_count() -> int
+```
+
+
+Get number of active subscribers (for monitoring).
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-requests.mdx b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
new file mode 100644
index 000000000..5cde802fc
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-requests.mdx
@@ -0,0 +1,91 @@
+---
+title: requests
+sidebarTitle: requests
+---
+
+# `fastmcp.server.tasks.requests`
+
+
+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.
+
+
+## Functions
+
+### `tasks_get_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- Task status response with spec-compliant fields
+
+
+### `tasks_result_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `tasks_list_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L398" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- Response with tasks list and pagination
+
+
+### `tasks_cancel_handler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/requests.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- Task status response showing cancelled state
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-routing.mdx b/docs/python-sdk/fastmcp-server-tasks-routing.mdx
new file mode 100644
index 000000000..435d62775
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-routing.mdx
@@ -0,0 +1,37 @@
+---
+title: routing
+sidebarTitle: routing
+---
+
+# `fastmcp.server.tasks.routing`
+
+
+Task routing helper for MCP components.
+
+Provides unified task mode enforcement and docket routing logic.
+
+
+## Functions
+
+### `check_background_task` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/routing.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx b/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx
new file mode 100644
index 000000000..2fd2e3cd4
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-tasks-subscriptions.mdx
@@ -0,0 +1,38 @@
+---
+title: subscriptions
+sidebarTitle: subscriptions
+---
+
+# `fastmcp.server.tasks.subscriptions`
+
+
+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.
+
+
+## Functions
+
+### `subscribe_to_task_updates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/subscriptions.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-server-telemetry.mdx b/docs/python-sdk/fastmcp-server-telemetry.mdx
new file mode 100644
index 000000000..09d2b0d76
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-telemetry.mdx
@@ -0,0 +1,56 @@
+---
+title: telemetry
+sidebarTitle: telemetry
+---
+
+# `fastmcp.server.telemetry`
+
+
+Server-side telemetry helpers.
+
+## Functions
+
+### `get_auth_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/telemetry.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_auth_span_attributes() -> dict[str, str]
+```
+
+
+Get auth attributes for the current request, if authenticated.
+
+
+### `get_session_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/telemetry.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_session_span_attributes() -> dict[str, str]
+```
+
+
+Get session attributes for the current request.
+
+
+### `server_span` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/telemetry.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+server_span(name: str, method: str, server_name: str, component_type: str, component_key: str, resource_uri: str | None = None) -> Generator[Span, None, None]
+```
+
+
+Create a SERVER span with standard MCP attributes and auth context.
+
+Automatically records any exception on the span and sets error status.
+
+
+### `delegate_span` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/telemetry.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+delegate_span(name: str, provider_type: str, component_key: str) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-__init__.mdx b/docs/python-sdk/fastmcp-server-transforms-__init__.mdx
new file mode 100644
index 000000000..f98150302
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-__init__.mdx
@@ -0,0 +1,193 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.transforms`
+
+
+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
+    ```
+
+
+## Classes
+
+### `GetToolNext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for get_tool call_next functions.
+
+
+### `GetResourceNext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L44" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for get_resource call_next functions.
+
+
+### `GetResourceTemplateNext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for get_resource_template call_next functions.
+
+
+### `GetPromptNext` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for get_prompt call_next functions.
+
+
+### `Transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> 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.
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L136" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str, call_next: GetResourceNext) -> 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.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> 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.
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/__init__.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str, call_next: GetPromptNext) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-catalog.mdx b/docs/python-sdk/fastmcp-server-transforms-catalog.mdx
new file mode 100644
index 000000000..1dd2cfe4a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-catalog.mdx
@@ -0,0 +1,220 @@
+---
+title: catalog
+sidebarTitle: catalog
+---
+
+# `fastmcp.server.transforms.catalog`
+
+
+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")
+
+
+## Classes
+
+### `CatalogTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]
+```
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence[ResourceTemplate]
+```
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]
+```
+
+#### `transform_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `transform_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `transform_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L140" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `transform_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `get_tool_catalog` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool_catalog(self, ctx: Context) -> Sequence[Tool]
+```
+
+Fetch the real tool 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_tools middleware has not yet run.
+
+
+#### `get_resource_catalog` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_catalog(self, ctx: Context) -> 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.
+
+
+#### `get_prompt_catalog` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt_catalog(self, ctx: Context) -> 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.
+
+
+#### `get_resource_template_catalog` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/catalog.py#L221" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template_catalog(self, ctx: Context) -> 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.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-namespace.mdx b/docs/python-sdk/fastmcp-server-transforms-namespace.mdx
new file mode 100644
index 000000000..9f590356d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-namespace.mdx
@@ -0,0 +1,96 @@
+---
+title: namespace
+sidebarTitle: namespace
+---
+
+# `fastmcp.server.transforms.namespace`
+
+
+Namespace transform for prefixing component names.
+
+## Classes
+
+### `Namespace` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Prefix tool names with namespace.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Get tool by namespaced name.
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]
+```
+
+Add namespace path segment to resource URIs.
+
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None
+```
+
+Get resource by namespaced URI.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence[ResourceTemplate]
+```
+
+Add namespace path segment to template URIs.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L155" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> ResourceTemplate | None
+```
+
+Get resource template by namespaced URI.
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]
+```
+
+Prefix prompt names with namespace.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/namespace.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str, call_next: GetPromptNext) -> Prompt | None
+```
+
+Get prompt by namespaced name.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-prompts_as_tools.mdx b/docs/python-sdk/fastmcp-server-transforms-prompts_as_tools.mdx
new file mode 100644
index 000000000..f1656c263
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-prompts_as_tools.mdx
@@ -0,0 +1,59 @@
+---
+title: prompts_as_tools
+sidebarTitle: prompts_as_tools
+---
+
+# `fastmcp.server.transforms.prompts_as_tools`
+
+
+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.
+
+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
+    ```
+
+
+## Classes
+
+### `PromptsAsTools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/prompts_as_tools.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transform that adds tools for listing and getting prompts.
+
+Generates two tools:
+- `list_prompts`: Lists all prompts from the provider
+- `get_prompt`: Gets a specific prompt with optional arguments
+
+The transform captures a provider reference at construction and queries it
+for prompts when the generated tools are called. When used with FastMCP,
+the provider's auth and visibility filtering is automatically applied.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/prompts_as_tools.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Add prompt tools to the tool list.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/prompts_as_tools.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Get a tool by name, including generated prompt tools.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-resources_as_tools.mdx b/docs/python-sdk/fastmcp-server-transforms-resources_as_tools.mdx
new file mode 100644
index 000000000..3b46e875c
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-resources_as_tools.mdx
@@ -0,0 +1,59 @@
+---
+title: resources_as_tools
+sidebarTitle: resources_as_tools
+---
+
+# `fastmcp.server.transforms.resources_as_tools`
+
+
+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.
+
+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
+    ```
+
+
+## Classes
+
+### `ResourcesAsTools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/resources_as_tools.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Transform that adds tools for listing and reading resources.
+
+Generates two tools:
+- `list_resources`: Lists all resources and templates from the provider
+- `read_resource`: Reads a resource by URI
+
+The transform captures a provider reference at construction and queries it
+for resources when the generated tools are called. When used with FastMCP,
+the provider's auth and visibility filtering is automatically applied.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/resources_as_tools.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Add resource tools to the tool list.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/resources_as_tools.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Get a tool by name, including generated resource tools.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-search-__init__.mdx b/docs/python-sdk/fastmcp-server-transforms-search-__init__.mdx
new file mode 100644
index 000000000..80b71d226
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-search-__init__.mdx
@@ -0,0 +1,23 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.server.transforms.search`
+
+
+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
+    ```
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-search-base.mdx b/docs/python-sdk/fastmcp-server-transforms-search-base.mdx
new file mode 100644
index 000000000..7ecd3b5f2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-search-base.mdx
@@ -0,0 +1,105 @@
+---
+title: base
+sidebarTitle: base
+---
+
+# `fastmcp.server.transforms.search.base`
+
+
+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())
+
+
+## Functions
+
+### `serialize_tools_for_output_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/base.py#L60" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+serialize_tools_for_output_json(tools: Sequence[Tool]) -> list[dict[str, Any]]
+```
+
+
+Serialize tools to the same dict format as ``list_tools`` output.
+
+
+### `serialize_tools_for_output_markdown` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/base.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+serialize_tools_for_output_markdown(tools: Sequence[Tool]) -> str
+```
+
+
+Serialize tools to compact markdown, using ~65-70% fewer tokens than JSON.
+
+
+## Classes
+
+### `BaseSearchTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/base.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `transform_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/base.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+transform_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Replace the catalog with pinned + synthetic search/call tools.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/base.py#L204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Intercept synthetic tool names; delegate everything else.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-search-bm25.mdx b/docs/python-sdk/fastmcp-server-transforms-search-bm25.mdx
new file mode 100644
index 000000000..d5264f46a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-search-bm25.mdx
@@ -0,0 +1,20 @@
+---
+title: bm25
+sidebarTitle: bm25
+---
+
+# `fastmcp.server.transforms.search.bm25`
+
+
+BM25-based search transform.
+
+## Classes
+
+### `BM25SearchTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/bm25.py#L86" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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).
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-search-regex.mdx b/docs/python-sdk/fastmcp-server-transforms-search-regex.mdx
new file mode 100644
index 000000000..e36c8d25e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-search-regex.mdx
@@ -0,0 +1,20 @@
+---
+title: regex
+sidebarTitle: regex
+---
+
+# `fastmcp.server.transforms.search.regex`
+
+
+Regex-based search transform.
+
+## Classes
+
+### `RegexSearchTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/search/regex.py#L15" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Search transform using regex pattern matching.
+
+Tools are matched against their name, description, and parameter
+information using ``re.search`` with ``re.IGNORECASE``.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-tool_transform.mdx b/docs/python-sdk/fastmcp-server-transforms-tool_transform.mdx
new file mode 100644
index 000000000..d911f4819
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-tool_transform.mdx
@@ -0,0 +1,40 @@
+---
+title: tool_transform
+sidebarTitle: tool_transform
+---
+
+# `fastmcp.server.transforms.tool_transform`
+
+
+Transform for applying tool transformations.
+
+## Classes
+
+### `ToolTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/tool_transform.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Applies tool transformations to modify tool schemas.
+
+Wraps ToolTransformConfig to apply argument renames, schema changes,
+hidden arguments, and other transformations at the transform level.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/tool_transform.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Apply transforms to matching tools.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/tool_transform.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Get tool by transformed name.
+
diff --git a/docs/python-sdk/fastmcp-server-transforms-version_filter.mdx b/docs/python-sdk/fastmcp-server-transforms-version_filter.mdx
new file mode 100644
index 000000000..7902c0a0a
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-version_filter.mdx
@@ -0,0 +1,89 @@
+---
+title: version_filter
+sidebarTitle: version_filter
+---
+
+# `fastmcp.server.transforms.version_filter`
+
+
+Version filter transform for filtering components by version range.
+
+## Classes
+
+### `VersionFilter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L24" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]
+```
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None
+```
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence[ResourceTemplate]
+```
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> ResourceTemplate | None
+```
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L138" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]
+```
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/version_filter.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str, call_next: GetPromptNext) -> Prompt | None
+```
diff --git a/docs/python-sdk/fastmcp-server-transforms-visibility.mdx b/docs/python-sdk/fastmcp-server-transforms-visibility.mdx
new file mode 100644
index 000000000..772cddc97
--- /dev/null
+++ b/docs/python-sdk/fastmcp-server-transforms-visibility.mdx
@@ -0,0 +1,261 @@
+---
+title: visibility
+sidebarTitle: visibility
+---
+
+# `fastmcp.server.transforms.visibility`
+
+
+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.
+
+
+## Functions
+
+### `is_enabled` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `get_visibility_rules` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L300" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_visibility_rules(context: Context) -> list[dict[str, Any]]
+```
+
+
+Load visibility rule dicts from session state.
+
+
+### `save_visibility_rules` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L305" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+save_visibility_rules(context: Context, rules: list[dict[str, Any]]) -> 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.
+
+
+### `create_visibility_transforms` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L332" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+create_visibility_transforms(rules: list[dict[str, Any]]) -> list[Visibility]
+```
+
+
+Convert rule dicts to Visibility transforms.
+
+
+### `get_session_transforms` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_session_transforms(context: Context) -> list[Visibility]
+```
+
+
+Get session-specific Visibility transforms from state store.
+
+
+### `enable_components` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+enable_components(context: Context) -> 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.
+
+
+### `disable_components` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+disable_components(context: Context) -> 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.
+
+
+### `reset_visibility` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L480" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `apply_session_transforms` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+## Classes
+
+### `Visibility` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `list_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]
+```
+
+Mark tools by visibility state.
+
+
+#### `get_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_tool(self, name: str, call_next: GetToolNext) -> Tool | None
+```
+
+Mark tool if found.
+
+
+#### `list_resources` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]
+```
+
+Mark resources by visibility state.
+
+
+#### `get_resource` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None
+```
+
+Mark resource if found.
+
+
+#### `list_resource_templates` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L234" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence[ResourceTemplate]
+```
+
+Mark resource templates by visibility state.
+
+
+#### `get_resource_template` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> ResourceTemplate | None
+```
+
+Mark resource template if found.
+
+
+#### `list_prompts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]
+```
+
+Mark prompts by visibility state.
+
+
+#### `get_prompt` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/transforms/visibility.py#L261" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_prompt(self, name: str, call_next: GetPromptNext) -> Prompt | None
+```
+
+Mark prompt if found.
+
diff --git a/docs/python-sdk/fastmcp-settings.mdx b/docs/python-sdk/fastmcp-settings.mdx
new file mode 100644
index 000000000..eeb1156f8
--- /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/src/fastmcp/settings.py#L29" 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/src/fastmcp/settings.py#L117" 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/src/fastmcp/settings.py#L129" 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/src/fastmcp/settings.py#L142" 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/src/fastmcp/settings.py#L164" 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 000000000..757e41fb9
--- /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/src/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/src/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/src/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/src/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-tools-__init__.mdx b/docs/python-sdk/fastmcp-tools-__init__.mdx
new file mode 100644
index 000000000..5b7c8b04d
--- /dev/null
+++ b/docs/python-sdk/fastmcp-tools-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.tools`
+
+*This module is empty or contains only private/internal implementations.*
diff --git a/docs/python-sdk/fastmcp-tools-function_parsing.mdx b/docs/python-sdk/fastmcp-tools-function_parsing.mdx
new file mode 100644
index 000000000..f9cd7f28e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-tools-function_parsing.mdx
@@ -0,0 +1,21 @@
+---
+title: function_parsing
+sidebarTitle: function_parsing
+---
+
+# `fastmcp.tools.function_parsing`
+
+
+Function introspection and schema generation for FastMCP tools.
+
+## Classes
+
+### `ParsedFunction` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_parsing.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_parsing.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any], exclude_args: list[str] | None = None, validate: bool = True, wrap_non_object_output_schema: bool = True) -> ParsedFunction
+```
diff --git a/docs/python-sdk/fastmcp-tools-function_tool.mdx b/docs/python-sdk/fastmcp-tools-function_tool.mdx
new file mode 100644
index 000000000..d25c6ecf8
--- /dev/null
+++ b/docs/python-sdk/fastmcp-tools-function_tool.mdx
@@ -0,0 +1,108 @@
+---
+title: function_tool
+sidebarTitle: function_tool
+---
+
+# `fastmcp.tools.function_tool`
+
+
+Standalone @tool decorator for FastMCP.
+
+## Functions
+
+### `tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L375" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+tool(name_or_fn: str | Callable[..., Any] | None = None) -> 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().
+
+
+## Classes
+
+### `DecoratedTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Protocol for functions decorated with @tool.
+
+
+### `ToolMeta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Metadata attached to functions by the @tool decorator.
+
+
+### `FunctionTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `to_mcp_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_tool(self, **overrides: Any) -> mcp.types.Tool
+```
+
+Convert the FastMCP tool to an MCP tool.
+
+Extends the base implementation to add task execution mode if enabled.
+
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L110" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> 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.
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+run(self, arguments: dict[str, Any]) -> ToolResult
+```
+
+Run the tool with arguments.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L298" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this tool with docket for background execution.
+
+FunctionTool registers the underlying function, which has the user's
+Depends parameters for docket to resolve.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/function_tool.py#L308" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any], **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()
+
diff --git a/docs/python-sdk/fastmcp-tools-tool.mdx b/docs/python-sdk/fastmcp-tools-tool.mdx
new file mode 100644
index 000000000..0394bf4a5
--- /dev/null
+++ b/docs/python-sdk/fastmcp-tools-tool.mdx
@@ -0,0 +1,116 @@
+---
+title: tool
+sidebarTitle: tool
+---
+
+# `fastmcp.tools.tool`
+
+## Functions
+
+### `default_serializer` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L64" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+default_serializer(data: Any) -> str
+```
+
+## Classes
+
+### `ToolResult` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `to_mcp_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_result(self) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult
+```
+
+### `Tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Internal tool registration info.
+
+
+**Methods:**
+
+#### `to_mcp_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_mcp_tool(self, **overrides: Any) -> MCPTool
+```
+
+Convert the FastMCP tool to an MCP tool.
+
+
+#### `from_function` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L206" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_function(cls, fn: Callable[..., Any]) -> FunctionTool
+```
+
+Create a Tool from a function.
+
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L246" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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).
+
+
+#### `convert_result` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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 (serializer, output_schema) for proper conversion.
+
+
+#### `register_with_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+register_with_docket(self, docket: Docket) -> None
+```
+
+Register this tool with docket for background execution.
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add_to_docket(self, docket: Docket, arguments: dict[str, Any], **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()
+
+
+#### `from_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+from_tool(cls, tool: Tool | Callable[..., Any]) -> TransformedTool
+```
+
+#### `get_span_attributes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_span_attributes(self) -> dict[str, Any]
+```
diff --git a/docs/python-sdk/fastmcp-tools-tool_transform.mdx b/docs/python-sdk/fastmcp-tools-tool_transform.mdx
new file mode 100644
index 000000000..84a1b66cf
--- /dev/null
+++ b/docs/python-sdk/fastmcp-tools-tool_transform.mdx
@@ -0,0 +1,311 @@
+---
+title: tool_transform
+sidebarTitle: tool_transform
+---
+
+# `fastmcp.tools.tool_transform`
+
+## Functions
+
+### `forward` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `forward_raw` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+### `apply_transformations_to_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L979" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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").
+
+
+## Classes
+
+### `ArgTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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)
+```
+
+
+### `ArgTransformConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L211" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+A model for requesting a single argument transform.
+
+
+**Methods:**
+
+#### `to_arg_transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L229" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+to_arg_transform(self) -> ArgTransform
+```
+
+Convert the argument transform to a FastMCP argument transform.
+
+
+### `TransformedTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+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.
+
+
+**Methods:**
+
+#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+#### `from_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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, serializer: Callable[[Any], str] | 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\:
+- Simple rename (str)
+- Complex transformation (rename/description/default/drop) (ArgTransform)
+- Drop the argument (None)
+- `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
+- False\: Disable output schema and structured outputs
+- `serializer`: Deprecated. Return ToolResult from your tools for full control over serialization.
+- `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}
+    )
+```
+
+
+### `ToolTransformConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L925" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Provides a way to transform a tool.
+
+
+**Methods:**
+
+#### `apply` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L958" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+apply(self, tool: Tool) -> TransformedTool
+```
+
+Create a TransformedTool from a provided tool and this transformation configuration.
+
diff --git a/docs/python-sdk/fastmcp-utilities-__init__.mdx b/docs/python-sdk/fastmcp-utilities-__init__.mdx
new file mode 100644
index 000000000..12e12b4ed
--- /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 000000000..cfd0cd7ab
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-async_utils.mdx
@@ -0,0 +1,44 @@
+---
+title: async_utils
+sidebarTitle: async_utils
+---
+
+# `fastmcp.utilities.async_utils`
+
+
+Async utilities for FastMCP.
+
+## Functions
+
+### `call_sync_fn_in_threadpool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/async_utils.py#L13" 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/src/fastmcp/utilities/async_utils.py#L38" 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 000000000..c2d23b9a5
--- /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/src/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/src/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/src/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-cli.mdx b/docs/python-sdk/fastmcp-utilities-cli.mdx
new file mode 100644
index 000000000..52f2addff
--- /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/src/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/src/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/src/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 000000000..eba2517c2
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-components.mdx
@@ -0,0 +1,148 @@
+---
+title: components
+sidebarTitle: components
+---
+
+# `fastmcp.utilities.components`
+
+## Functions
+
+### `get_fastmcp_metadata` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/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/src/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/src/fastmcp/utilities/components.py#L61" 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/src/fastmcp/utilities/components.py#L112" 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/src/fastmcp/utilities/components.py#L126" 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.
+
+
+#### `get_meta` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L141" 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/src/fastmcp/utilities/components.py#L189" 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/src/fastmcp/utilities/components.py#L196" 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/src/fastmcp/utilities/components.py#L203" 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/src/fastmcp/utilities/components.py#L207" 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).
+
+
+#### `add_to_docket` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L215" 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/src/fastmcp/utilities/components.py#L237" 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-exceptions.mdx b/docs/python-sdk/fastmcp-utilities-exceptions.mdx
new file mode 100644
index 000000000..5794f185e
--- /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/src/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/src/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 000000000..d274477c5
--- /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/src/fastmcp/utilities/http.py#L4" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+find_available_port() -> 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 000000000..a813eb51e
--- /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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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 000000000..e08643cb9
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx
@@ -0,0 +1,79 @@
+---
+title: json_schema
+sidebarTitle: json_schema
+---
+
+# `fastmcp.utilities.json_schema`
+
+## Functions
+
+### `dereference_refs` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/json_schema.py#L56" 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.
+
+**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/src/fastmcp/utilities/json_schema.py#L185" 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/src/fastmcp/utilities/json_schema.py#L418" 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 000000000..b1137e7de
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-json_schema_type.mdx
@@ -0,0 +1,110 @@
+---
+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
+
+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/src/fastmcp/utilities/json_schema_type.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+json_schema_to_type(schema: Mapping[str, Any], 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
+- `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/src/fastmcp/utilities/json_schema_type.py#L78" 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 000000000..912cbfad6
--- /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/src/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 000000000..2b5fea4ae
--- /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/src/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/src/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/src/fastmcp/utilities/logging.py#L111" 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 000000000..bc8fc9500
--- /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-__init__.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-__init__.mdx
new file mode 100644
index 000000000..d29664280
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities.mcp_server_config.v1`
+
+*This module is empty or contains only private/internal implementations.*
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 000000000..01f147482
--- /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 000000000..f59bb18b1
--- /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/src/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/src/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/src/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 000000000..e5a2d6a11
--- /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/src/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/src/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/src/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 000000000..460f1f83d
--- /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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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-__init__.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-__init__.mdx
new file mode 100644
index 000000000..38d102b15
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-__init__.mdx
@@ -0,0 +1,8 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities.mcp_server_config.v1.sources`
+
+*This module is empty or contains only private/internal implementations.*
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 000000000..764454b6d
--- /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/src/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/src/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/src/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 000000000..3d791f9cd
--- /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/src/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L15" 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/src/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L28" 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/src/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py#L63" 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-openapi-__init__.mdx b/docs/python-sdk/fastmcp-utilities-openapi-__init__.mdx
new file mode 100644
index 000000000..df0331f9e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-__init__.mdx
@@ -0,0 +1,9 @@
+---
+title: __init__
+sidebarTitle: __init__
+---
+
+# `fastmcp.utilities.openapi`
+
+
+OpenAPI utilities for FastMCP - refactored for better maintainability.
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-director.mdx b/docs/python-sdk/fastmcp-utilities-openapi-director.mdx
new file mode 100644
index 000000000..0d61900c6
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-director.mdx
@@ -0,0 +1,36 @@
+---
+title: director
+sidebarTitle: director
+---
+
+# `fastmcp.utilities.openapi.director`
+
+
+Request director using openapi-core for stateless HTTP request building.
+
+## Classes
+
+### `RequestDirector` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/director.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Builds httpx.Request objects from HTTPRoute and arguments using openapi-core.
+
+
+**Methods:**
+
+#### `build` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/director.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-formatters.mdx b/docs/python-sdk/fastmcp-utilities-openapi-formatters.mdx
new file mode 100644
index 000000000..4d5ad3a90
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-formatters.mdx
@@ -0,0 +1,96 @@
+---
+title: formatters
+sidebarTitle: formatters
+---
+
+# `fastmcp.utilities.openapi.formatters`
+
+
+Parameter formatting functions for OpenAPI operations.
+
+## Functions
+
+### `format_array_parameter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/formatters.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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)
+
+
+### `format_deep_object_parameter` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/formatters.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `generate_example_from_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/formatters.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+generate_example_from_schema(schema: JsonSchema | None) -> Any
+```
+
+
+Generate a simple example value from a JSON schema dictionary.
+Very basic implementation focusing on types.
+
+
+### `format_json_for_description` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/formatters.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_json_for_description(data: Any, indent: int = 2) -> str
+```
+
+
+Formats Python data as a JSON string block for Markdown.
+
+
+### `format_description_with_responses` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/formatters.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+format_description_with_responses(base_description: str, responses: dict[str, Any], parameters: list[ParameterInfo] | None = None, request_body: RequestBodyInfo | None = None) -> str
+```
+
+
+Formats the base description string with response, parameter, and request body information.
+
+**Args:**
+- `base_description`: The initial description to be formatted.
+- `responses`: A dictionary of response information, keyed by status code.
+- `parameters`: 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`: Information about the request body,
+including its description, whether it is required, and its content schema.
+
+**Returns:**
+- The formatted description string with additional details about responses, parameters,
+- and the request body.
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-json_schema_converter.mdx b/docs/python-sdk/fastmcp-utilities-openapi-json_schema_converter.mdx
new file mode 100644
index 000000000..abd1d6869
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-json_schema_converter.mdx
@@ -0,0 +1,62 @@
+---
+title: json_schema_converter
+sidebarTitle: json_schema_converter
+---
+
+# `fastmcp.utilities.openapi.json_schema_converter`
+
+
+
+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.
+
+
+## Functions
+
+### `convert_openapi_schema_to_json_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/json_schema_converter.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
+
+### `convert_schema_definitions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/json_schema_converter.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-models.mdx b/docs/python-sdk/fastmcp-utilities-openapi-models.mdx
new file mode 100644
index 000000000..02a3fbe9e
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-models.mdx
@@ -0,0 +1,35 @@
+---
+title: models
+sidebarTitle: models
+---
+
+# `fastmcp.utilities.openapi.models`
+
+
+Intermediate Representation (IR) models for OpenAPI operations.
+
+## Classes
+
+### `ParameterInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/models.py#L17" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Represents a single parameter for an HTTP operation in our IR.
+
+
+### `RequestBodyInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/models.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Represents the request body for an HTTP operation in our IR.
+
+
+### `ResponseInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/models.py#L39" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Represents response information in our IR.
+
+
+### `HTTPRoute` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/models.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Intermediate Representation for a single OpenAPI operation.
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-parser.mdx b/docs/python-sdk/fastmcp-utilities-openapi-parser.mdx
new file mode 100644
index 000000000..0a9a2a272
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-parser.mdx
@@ -0,0 +1,43 @@
+---
+title: parser
+sidebarTitle: parser
+---
+
+# `fastmcp.utilities.openapi.parser`
+
+
+OpenAPI parsing logic for converting OpenAPI specs to HTTPRoute objects.
+
+## Functions
+
+### `parse_openapi_to_http_routes` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/parser.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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.
+
+
+## Classes
+
+### `OpenAPIParser` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/parser.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Unified parser for OpenAPI schemas with generic type parameters to handle both 3.0 and 3.1.
+
+
+**Methods:**
+
+#### `parse` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/parser.py#L663" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+parse(self) -> list[HTTPRoute]
+```
+
+Parse the OpenAPI schema into HTTP routes.
+
diff --git a/docs/python-sdk/fastmcp-utilities-openapi-schemas.mdx b/docs/python-sdk/fastmcp-utilities-openapi-schemas.mdx
new file mode 100644
index 000000000..fad88ee5f
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-openapi-schemas.mdx
@@ -0,0 +1,43 @@
+---
+title: schemas
+sidebarTitle: schemas
+---
+
+# `fastmcp.utilities.openapi.schemas`
+
+
+Schema manipulation utilities for OpenAPI operations.
+
+## Functions
+
+### `clean_schema_for_display` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/schemas.py#L12" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None
+```
+
+
+Clean up a schema dictionary for display by removing internal/complex fields.
+
+
+### `extract_output_schema_from_responses` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/openapi/schemas.py#L474" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+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:**
+- MCP-compliant output schema with potential wrapping, or None if no suitable schema found
+
diff --git a/docs/python-sdk/fastmcp-utilities-pagination.mdx b/docs/python-sdk/fastmcp-utilities-pagination.mdx
new file mode 100644
index 000000000..0381a36aa
--- /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/src/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/src/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/src/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/src/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 000000000..ccb0c83b8
--- /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/src/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/src/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/src/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/src/fastmcp/utilities/skills.py#L214" 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/src/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/src/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/src/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-tests.mdx b/docs/python-sdk/fastmcp-utilities-tests.mdx
new file mode 100644
index 000000000..5a40ff61f
--- /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/src/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/src/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/src/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/src/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/src/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/src/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 000000000..3a8cb41b9
--- /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/src/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/src/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-types.mdx b/docs/python-sdk/fastmcp-utilities-types.mdx
new file mode 100644
index 000000000..6cae8cdc0
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-types.mdx
@@ -0,0 +1,169 @@
+---
+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/src/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/src/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/src/fastmcp/utilities/types.py#L120" 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/src/fastmcp/utilities/types.py#L130" 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/src/fastmcp/utilities/types.py#L152" 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/src/fastmcp/utilities/types.py#L178" 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/src/fastmcp/utilities/types.py#L451" 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 old_type with new_type.
+
+This is useful for transforming types when creating tools.
+
+**Args:**
+- `type_`: The type to replace instances of old_type with new_type.
+- `old_type`: The type to replace.
+- `new_type`: The type to replace old_type with.
+
+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/src/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/src/fastmcp/utilities/types.py#L235" 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/src/fastmcp/utilities/types.py#L286" 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/src/fastmcp/utilities/types.py#L301" 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/src/fastmcp/utilities/types.py#L307" 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/src/fastmcp/utilities/types.py#L344" 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/src/fastmcp/utilities/types.py#L365" 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/src/fastmcp/utilities/types.py#L404" 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/src/fastmcp/utilities/types.py#L488" 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 000000000..eb060d2d3
--- /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/src/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/src/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/src/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/src/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/src/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/src/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/src/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 000000000..b27951eda
--- /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/src/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/src/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 000000000..f5e44f296
--- /dev/null
+++ b/docs/python-sdk/fastmcp-utilities-versions.mdx
@@ -0,0 +1,194 @@
+---
+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/src/fastmcp/utilities/versions.py#L187" 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/src/fastmcp/utilities/versions.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+version_sort_key(component: FastMCPComponent) -> VersionKey
+```
+
+
+Get a sort key for a component based on its version.
+
+Use with sorted() or max() to order components by version.
+
+**Args:**
+- `component`: The component to get a sort key for.
+
+**Returns:**
+- A sortable VersionKey.
+
+
+### `compare_versions` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L219" 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/src/fastmcp/utilities/versions.py#L241" 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/src/fastmcp/utilities/versions.py#L254" 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/src/fastmcp/utilities/versions.py#L271" 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.
+
+
+## Classes
+
+### `VersionSpec` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L28" 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).
+
+
+**Methods:**
+
+#### `matches` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L45" 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/src/fastmcp/utilities/versions.py#L78" 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/src/fastmcp/utilities/versions.py#L114" 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 000000000..9a26df138
--- /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.providers.oauth import MyOAuthProvider
+
+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 000000000..529a01784
--- /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 000000000..ba54d25ab
--- /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 000000000..e8e79507c
--- /dev/null
+++ b/docs/servers/auth/oauth-proxy.mdx
@@ -0,0 +1,679 @@
+---
+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`](/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" required>
+  Client secret from your registered OAuth application
+</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="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="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](/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" default="True">
+  Whether to require user consent before authorizing MCP clients. When enabled (default), users see a consent screen that displays which client is requesting access, preventing [confused deputy attacks](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem) by ensuring users explicitly approve new clients.
+
+  **Default behavior (True):**
+  Users see a consent screen on first authorization. Consent choices are remembered via signed cookies, so users only need to approve each client once. This protects against malicious clients impersonating the user.
+
+  **Disabling consent (False):**
+  Authorization proceeds directly to the upstream provider without user confirmation. Only use this for local development or testing environments where the security trade-off is acceptable.
+
+  ```python
+  # Development/testing only - skip consent screen
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent=False  # ⚠️ Security warning: only for local/testing
+  )
+  ```
+
+  <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 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
+    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:**
+
+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.
+
+## 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. Once you approve a client, it's remembered so you don't see the consent page again for that client. 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.
+
+**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 000000000..86661bc16
--- /dev/null
+++ b/docs/servers/auth/oidc-proxy.mdx
@@ -0,0 +1,280 @@
+---
+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" 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="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](/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" default="True">
+  Whether to require user consent before authorizing MCP clients. When enabled (default), users see a consent screen that displays which client is requesting access. See [OAuthProxy documentation](/servers/auth/oauth-proxy#confused-deputy-attacks) for details on confused deputy attack protection.
+</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 000000000..7c94a937f
--- /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 (defaults to all for DCR compatibility)
+    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): All redirect URIs allowed (for DCR compatibility)
+- 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.
\ No newline at end of file
diff --git a/docs/servers/auth/token-verification.mdx b/docs/servers/auth/token-verification.mdx
new file mode 100644
index 000000000..a9146135f
--- /dev/null
+++ b/docs/servers/auth/token-verification.mdx
@@ -0,0 +1,426 @@
+---
+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 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 000000000..a48d2a9e8
--- /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 000000000..42523a5cd
--- /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 000000000..a10161baf
--- /dev/null
+++ b/docs/servers/context.mdx
@@ -0,0 +1,443 @@
+---
+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 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 000000000..d13f43952
--- /dev/null
+++ b/docs/servers/dependency-injection.mdx
@@ -0,0 +1,427 @@
+---
+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). Use HTTP Headers if you need graceful fallback.
+</Note>
+
+### HTTP Headers
+
+<VersionBadge version="2.2.11" />
+
+Access HTTP headers with graceful fallback—returns an empty dictionary when no HTTP request is available, 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 000000000..600a3d2fe
--- /dev/null
+++ b/docs/servers/elicitation.mdx
@@ -0,0 +1,357 @@
+---
+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>
+
+### 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 000000000..c9b558094
--- /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 mcp.types import Icon
+
+icon = Icon(
+    src="https://example.com/icon.png",
+    mimeType="image/png",
+    sizes=["48x48"]
+)
+```
+
+The fields serve different purposes:
+
+- **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"])
+
+## 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 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. This helps users visually distinguish between different component types and purposes.
+
+### 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 without external dependencies, use data URIs. This approach eliminates the need for hosting and ensures the icon is always available.
+
+```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 Data URIs from Files
+
+FastMCP provides the `Image` utility class to convert local image files into data URIs.
+
+```python
+from mcp.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 000000000..822e4f8a1
--- /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 000000000..e01fdd875
--- /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 000000000..424f5afa7
--- /dev/null
+++ b/docs/servers/middleware.mdx
@@ -0,0 +1,871 @@
+---
+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`.
+
+## 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 mcp import McpError
+from mcp.types import ErrorData
+
+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(ErrorData(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 fastmcp.server.middleware.caching import ResponseCachingMiddleware
+from key_value.aio.stores.disk import DiskStore
+
+mcp.add_middleware(ResponseCachingMiddleware(
+    cache_storage=DiskStore(directory="cache")
+))
+```
+
+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 |
+| `client_id_func` | `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.
+
+### 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 000000000..97ad2c7a2
--- /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 `nextCursor` 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.nextCursor:
+        result = await client.list_tools_mcp(cursor=result.nextCursor)
+        print(f"Next page: {len(result.tools)} tools")
+```
+
+The `_mcp` methods return the raw MCP protocol objects, which include both the items and the `nextCursor` for the next page. When `nextCursor` 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 000000000..9600a05ce
--- /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 000000000..bdfefc24e
--- /dev/null
+++ b/docs/servers/prompts.mdx
@@ -0,0 +1,459 @@
+---
+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 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">
+  <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>
+
+### 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
+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 000000000..f5673c683
--- /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 000000000..a5b798faa
--- /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 / "mcp")])
+```
+
+In your `mcp/` directory, create Python files with decorated functions.
+
+```python
+# mcp/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
+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.
+
+```
+mcp/
+├── 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.
+
+```
+mcp/
+├── 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
+# mcp/__init__.py exists
+
+# mcp/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 / "mcp", 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
+└── mcp/
+    ├── 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 / "mcp",
+    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 000000000..86726655a
--- /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 000000000..d3e3e4e5f
--- /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 000000000..a2def6892
--- /dev/null
+++ b/docs/servers/providers/proxy.mdx
@@ -0,0 +1,301 @@
+---
+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>
+
+## 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.
+
+For low-latency requirements, consider caching strategies or limiting mounting depth.
+
+## 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 000000000..3c810b3f2
--- /dev/null
+++ b/docs/servers/providers/skills.mdx
@@ -0,0 +1,301 @@
+---
+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
+```
+
+## 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 000000000..0a8a772aa
--- /dev/null
+++ b/docs/servers/resources.mdx
@@ -0,0 +1,719 @@
+---
+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 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. While standard parameters (`{param}`) only match a single path segment and don't cross "/" boundaries, 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.
+
+#### 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.
\ No newline at end of file
diff --git a/docs/servers/sampling.mdx b/docs/servers/sampling.mdx
new file mode 100644
index 000000000..8ea479eb0
--- /dev/null
+++ b/docs/servers/sampling.mdx
@@ -0,0 +1,573 @@
+---
+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" />
+
+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 mcp.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 mcp.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 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"
+
+    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",
+                    toolUseId=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 `isError=True` on the tool result:
+
+```python
+tool_result = ToolResultContent(
+    type="tool_result",
+    toolUseId=call.id,
+    content=[TextContent(type="text", text="Permission denied")],
+    isError=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 000000000..ed84b5e48
--- /dev/null
+++ b/docs/servers/server.mdx
@@ -0,0 +1,248 @@
+---
+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
+
+Instantiate a server by providing a name that identifies it in client applications and logs. You can also provide instructions that help clients understand the server's purpose.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="MyAssistantServer")
+
+# Instructions help clients understand 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 configuration options. The most commonly used parameters control server identity, authentication, and component behavior.
+
+<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](/servers/icons) for detailed examples
+</ParamField>
+
+<ParamField body="auth" type="OAuthProvider | TokenVerifier | None">
+  Authentication provider for securing HTTP-based transports. See [Authentication](/servers/auth/authentication) for configuration options
+</ParamField>
+
+<ParamField body="lifespan" type="Lifespan | AsyncContextManager | None">
+  Server-level setup and teardown logic. See [Lifespans](/servers/lifespan) for composable lifespans
+</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="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, and [CodeMode](/servers/transforms/code-mode) lets LLMs write scripts that chain tool calls in a sandbox
+</ParamField>
+
+<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" />
+  Controls how tool input parameters are validated. When `False` (default), FastMCP uses Pydantic's flexible validation that coerces compatible inputs (e.g., `"10"` to `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](/servers/tools#input-validation-modes) for details
+</ParamField>
+
+<ParamField body="list_page_size" type="int | None" default="None">
+  <VersionBadge version="3.0.0" />
+  Maximum number of items per page for list operations (`tools/list`, `resources/list`, etc.). When `None` (default), all results are returned in a single response. When set, responses are paginated and include a `nextCursor` for fetching additional pages. See [Pagination](/servers/pagination) for details
+</ParamField>
+
+</Card>
+
+## Components
+
+FastMCP servers expose three types of components to clients. Each type serves a distinct purpose in the MCP protocol.
+
+### Tools
+
+Tools are functions that clients can invoke to perform actions or access external systems. They're the primary way clients interact with your server's capabilities.
+
+```python
+@mcp.tool
+def multiply(a: float, b: float) -> float:
+    """Multiplies two numbers together."""
+    return a * b
+```
+
+See [Tools](/servers/tools) for detailed documentation.
+
+### Resources
+
+Resources expose data that clients can read. Unlike tools, resources are passive data sources that clients pull from rather than invoke.
+
+```python
+@mcp.resource("data://config")
+def get_config() -> dict:
+    """Provides the application configuration."""
+    return {"theme": "dark", "version": "1.0"}
+```
+
+See [Resources](/servers/resources) for detailed documentation.
+
+### Resource Templates
+
+Resource templates are parameterized resources. The client provides values for template parameters in the URI, and the server returns data specific to those parameters.
+
+```python
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: int) -> dict:
+    """Retrieves a user's profile by ID."""
+    return {"id": user_id, "name": f"User {user_id}", "status": "active"}
+```
+
+See [Resource Templates](/servers/resources#resource-templates) for detailed documentation.
+
+### Prompts
+
+Prompts are reusable message templates that guide LLM interactions. They help establish consistent patterns for how clients should frame requests.
+
+```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](/servers/prompts) for detailed documentation.
+
+## Tag-Based Filtering
+
+<VersionBadge version="2.8.0" />
+
+Tags let you categorize components and selectively expose them based on configurable include/exclude sets. This is useful for creating different views of your server for different environments or user types.
+
+Components can be tagged when defined using the `tags` parameter. A component can have multiple tags, and filtering operates on tag membership.
+
+```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>
+
+Configure tag-based filtering after creating your server.
+
+```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.
+
+## Running the Server
+
+FastMCP servers communicate with clients through transport mechanisms. Start your server by calling `mcp.run()`, typically within an `if __name__ == "__main__":` block. This pattern ensures compatibility with various MCP clients.
+
+```python
+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__":
+    # Defaults to STDIO transport
+    mcp.run()
+
+    # Or use HTTP transport
+    # mcp.run(transport="http", host="127.0.0.1", port=9000)
+```
+
+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)
+
+The server can also be run using the FastMCP CLI. For detailed information on transports and configuration, see the [Running Your Server](/deployment/running-server) guide.
+
+## Custom Routes
+
+When running with HTTP transport, you can add custom web routes alongside your MCP endpoint using the `@custom_route` decorator. This is useful for auxiliary endpoints like health checks.
+
+```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](/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 000000000..1bdb19b20
--- /dev/null
+++ b/docs/servers/storage-backends.mdx
@@ -0,0 +1,294 @@
+---
+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)
+```
+
+The sanitization strategies ensure keys and collection names are safe for the filesystem — alphanumeric names pass through as-is for readability, while special characters are hashed to prevent path traversal.
+
+**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 OAuthClientProvider
+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 = OAuthClientProvider(
+    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 000000000..d4aae9f54
--- /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 000000000..1055dc0c0
--- /dev/null
+++ b/docs/servers/telemetry.mdx
@@ -0,0 +1,280 @@
+---
+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 {uri}` | Resource read (e.g., `resources/read config://database`) |
+| `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 {uri}`, `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
+```
+
+## 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
+# - exception event with stack trace
+```
+
+## Attributes Reference
+
+### RPC Semantic Conventions
+
+Standard [RPC semantic conventions](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/):
+
+| Attribute | Value |
+|-----------|-------|
+| `rpc.system` | `"mcp"` |
+| `rpc.service` | Server name |
+| `rpc.method` | MCP protocol method |
+
+### 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) |
+
+### 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 000000000..7bd8600c5
--- /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/tools.mdx b/docs/servers/tools.mdx
new file mode 100644
index 000000000..91d96d1be
--- /dev/null
+++ b/docs/servers/tools.mdx
@@ -0,0 +1,1088 @@
+---
+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">
+  <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>
+</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.
+
+## 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:
+
+#### 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 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.
+
+### 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:
+
+```python
+@mcp.tool(
+    annotations={
+        "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={"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={"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 000000000..f09c22b6f
--- /dev/null
+++ b/docs/servers/transforms/code-mode.mdx
@@ -0,0 +1,339 @@
+---
+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` can enforce execution limits — timeouts, memory caps, recursion depth, and more. Without limits, LLM-generated scripts can run indefinitely.
+
+```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 |
+
+### 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 000000000..715bebd39
--- /dev/null
+++ b/docs/servers/transforms/namespace.mdx
@@ -0,0 +1,64 @@
+---
+title: Namespace Transform
+sidebarTitle: Namespace
+description: Prefix component names to prevent conflicts
+icon: tag
+tag: NEW
+---
+
+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 000000000..009a1ee39
--- /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 000000000..b68c0891d
--- /dev/null
+++ b/docs/servers/transforms/prompts-as-tools.mdx
@@ -0,0 +1,126 @@
+---
+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 server to `PromptsAsTools` when adding the transform. The transform queries that server for prompts whenever the generated tools are called.
+
+```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 000000000..8c7e8bbed
--- /dev/null
+++ b/docs/servers/transforms/resources-as-tools.mdx
@@ -0,0 +1,105 @@
+---
+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 server to `ResourcesAsTools` when adding the transform. The transform queries that server for resources whenever the generated tools are called.
+
+```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`.
+
+## 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 000000000..204004f5c
--- /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 000000000..393b47b5a
--- /dev/null
+++ b/docs/servers/transforms/tool-transformation.mdx
@@ -0,0 +1,231 @@
+---
+title: Tool Transformation
+sidebarTitle: Tool Transformation
+description: Modify tool schemas - rename, reshape arguments, and customize behavior
+icon: wrench
+tag: NEW
+---
+
+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 000000000..4008f86b4
--- /dev/null
+++ b/docs/servers/transforms/transforms.mdx
@@ -0,0 +1,174 @@
+---
+title: Transforms Overview
+sidebarTitle: Overview
+description: Modify components as they flow through your server
+icon: wand-magic-sparkles
+tag: NEW
+---
+
+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 000000000..4c44a73bd
--- /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 000000000..509bd7068
--- /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 000000000..4da6ac752
--- /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/version-badge.mdx b/docs/snippets/version-badge.mdx
new file mode 100644
index 000000000..3442524b8
--- /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 000000000..1c36e6cfd
--- /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 000000000..de1000703
--- /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 000000000..fd3995fff
--- /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 000000000..a0857aca9
--- /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.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 000000000..25eafe494
--- /dev/null
+++ b/docs/unify-intent.js
@@ -0,0 +1,68 @@
+// Load Unify intent tag on authentication pages only
+(function () {
+  if (typeof window === "undefined") return;
+
+  function isAuthPage() {
+    var path = window.location.pathname;
+    return path.includes("/servers/auth/") || path.includes("/clients/auth/");
+  }
+
+  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 (isAuthPage() && !document.getElementById("unifytag")) {
+      loadUnify();
+    } else if (!isAuthPage() && 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 000000000..e3134fb61
--- /dev/null
+++ b/docs/updates.mdx
@@ -0,0 +1,542 @@
+---
+title: "FastMCP Updates"
+sidebarTitle: "Updates"
+icon: "sparkles"
+tag: NEW
+---
+
+<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.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 000000000..71d98d18d
--- /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/changelog.mdx b/docs/v2/changelog.mdx
new file mode 100644
index 000000000..f46b08b04
--- /dev/null
+++ b/docs/v2/changelog.mdx
@@ -0,0 +1,2312 @@
+---
+title: "Changelog"
+icon: "list-check"
+rss: true
+---
+
+<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 000000000..2e12fbc13
--- /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 000000000..adc1160c7
--- /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 000000000..4293e0239
--- /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 000000000..15b0e5030
--- /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 000000000..ffebdf87f
--- /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 000000000..426ff7f25
--- /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 000000000..ff3e0aa85
--- /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 000000000..291503f7b
--- /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 000000000..b5120fdf1
--- /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 000000000..2a8d8c1f9
--- /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 000000000..1bfea5b18
--- /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/src/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 000000000..57b2a4a2f
--- /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 000000000..d9321f721
--- /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 000000000..b7129acc2
--- /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 000000000..1e7a50ce9
--- /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 000000000..eafa773b3
--- /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).
+
+## 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 bearer token authentication (though OAuth is recommended for production):
+
+```python
+import os
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerTokenAuth
+
+# Read configuration from environment
+auth_token = os.environ.get("MCP_AUTH_TOKEN")
+if auth_token:
+    auth = BearerTokenAuth(token=auth_token)
+    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 000000000..381b8016d
--- /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 000000000..f9b0e4781
--- /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 000000000..31df31de6
--- /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 000000000..346462736
--- /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 000000000..6a9973fe8
--- /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 `src/` directory structure, creating a predictable mapping between code and tests. When you're working on `src/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.
\ No newline at end of file
diff --git a/docs/v2/development/upgrade-guide.mdx b/docs/v2/development/upgrade-guide.mdx
new file mode 100644
index 000000000..2e98b4a02
--- /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 Before
+from fastmcp.experimental.server.openapi import FastMCPOpenAPI, RouteMap, MCPType
+```
+
+```python 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 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 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 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 000000000..d70eac1ac
--- /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 000000000..678d8cd5e
--- /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) 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) 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 000000000..c00788f72
--- /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) (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="SearchFastMcp", 
+            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 000000000..7490bcf35
--- /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.
+
+```python
+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 000000000..9e5b186fc
--- /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 000000000..aa7799a35
--- /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 000000000..4f39e1953
--- /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 000000000..208b3f2ed
--- /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 000000000..18028c69d
--- /dev/null
+++ b/docs/v2/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
+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={"readOnlyHint": True}` to skip confirmation prompts for read-only tools:
+
+```python
+@mcp.tool(annotations={"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 000000000..2b04c10a8
--- /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 000000000..98a6ffef7
--- /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 000000000..5681d70d7
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 000000000..5b98cbd1a
--- /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 000000000..abba9069d
--- /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 000000000..b9154e3d6
--- /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 000000000..2fd2ca4a5
--- /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 000000000..3737345f1
--- /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.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 000000000..af63a5d32
--- /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 000000000..b037c1110
--- /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) 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 000000000..5c920063c
--- /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 000000000..3285765e1
--- /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 000000000..e5942f60e
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 000000000..a5592abca
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 000000000..bd4b5cf33
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 000000000..d100b1eab
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 000000000..c65e34181
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 000000000..a9b758fb7
--- /dev/null
+++ b/docs/v2/integrations/mcp-json-configuration.mdx
@@ -0,0 +1,422 @@
+---
+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"
+```
+
+## 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 000000000..282a51e17
--- /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 000000000..63b5e28b4
--- /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:
+
+```python
+pythonAPIStatusError: 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 000000000..8662a0c05
--- /dev/null
+++ b/docs/v2/integrations/openapi.mdx
@@ -0,0 +1,451 @@
+---
+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.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.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.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.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.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.openapi import RouteMap, MCPType, 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.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.openapi import (
+    HTTPRoute,
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+
+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 000000000..066f5b1ea
--- /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 000000000..abe41a2ba
--- /dev/null
+++ b/docs/v2/integrations/scalekit.mdx
@@ -0,0 +1,194 @@
+---
+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.context import request_ctx
+import jwt
+
+@mcp.tool
+def inspect_token() -> dict:
+    """Inspect the current JWT token claims."""
+    context = request_ctx.get()
+
+    # Extract token from Authorization header
+    if hasattr(context, 'request') and hasattr(context.request, 'headers'):
+        auth_header = context.request.headers.get('authorization', '')
+        if auth_header.startswith('Bearer '):
+            token = auth_header[7:]
+            # Decode without verification (already verified by provider)
+            claims = jwt.decode(token, options={"verify_signature": False})
+            return claims
+
+    return {"error": "No token found"}
+```
diff --git a/docs/v2/integrations/supabase.mdx b/docs/v2/integrations/supabase.mdx
new file mode 100644
index 000000000..94a57e0a2
--- /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 000000000..b8c01a1d6
--- /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 000000000..1aa90457d
--- /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 000000000..d2f812f52
--- /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/src/fastmcp/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python
+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 `src/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 000000000..2b48aa4d9
--- /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 000000000..7bd8600c5
--- /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 000000000..0808f6878
--- /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 000000000..c42bfa8bf
--- /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.providers.oauth import MyOAuthProvider
+
+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 000000000..eaaba6a7f
--- /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 000000000..b9bc03430
--- /dev/null
+++ b/docs/v2/servers/auth/oauth-proxy.mdx
@@ -0,0 +1,594 @@
+---
+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="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" default="True">
+  Whether to require user consent before authorizing MCP clients. When enabled (default), users see a consent screen that displays which client is requesting access, preventing [confused deputy attacks](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem) by ensuring users explicitly approve new clients.
+
+  **Default behavior (True):**
+  Users see a consent screen on first authorization. Consent choices are remembered via signed cookies, so users only need to approve each client once. This protects against malicious clients impersonating the user.
+
+  **Disabling consent (False):**
+  Authorization proceeds directly to the upstream provider without user confirmation. Only use this for local development or testing environments where the security trade-off is acceptable.
+
+  ```python
+  # Development/testing only - skip consent screen
+  auth = OAuthProxy(
+      ...,
+      require_authorization_consent=False  # ⚠️ Security warning: only for local/testing
+  )
+  ```
+
+  <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 any new or unrecognized 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. Once you approve a client, it's remembered so you don't see the consent page again for that client. 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.
+
+
+
+**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 000000000..0b3a21d71
--- /dev/null
+++ b/docs/v2/servers/auth/oidc-proxy.mdx
@@ -0,0 +1,269 @@
+---
+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="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" default="True">
+  Whether to require user consent before authorizing MCP clients. When enabled (default), users see a consent screen that displays which client is requesting access. See [OAuthProxy documentation](/v2/servers/auth/oauth-proxy#confused-deputy-attacks) for details on confused deputy attack protection.
+</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 000000000..39c43c559
--- /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 000000000..e14282663
--- /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 000000000..8fb93430a
--- /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 000000000..3b224fdca
--- /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 000000000..a63f171b1
--- /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 000000000..a7d038f6a
--- /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 000000000..14f9a9d59
--- /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 000000000..f5cf71ee6
--- /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 000000000..c5bbad398
--- /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 000000000..bccba2bdc
--- /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 000000000..c60b628f7
--- /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.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.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.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.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.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 000000000..a76734f12
--- /dev/null
+++ b/docs/v2/servers/resources.mdx
@@ -0,0 +1,637 @@
+---
+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. While standard parameters (`{param}`) only match a single path segment and don't cross "/" boundaries, 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.
+
+#### 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.
\ No newline at end of file
diff --git a/docs/v2/servers/sampling.mdx b/docs/v2/servers/sampling.mdx
new file mode 100644
index 000000000..5c21a0bde
--- /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 000000000..f8519f6e8
--- /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 000000000..cd14ab80e
--- /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 OAuthClientProvider
+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 = OAuthClientProvider(
+    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 000000000..daae4750b
--- /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 000000000..1ec8d62be
--- /dev/null
+++ b/docs/v2/servers/tools.mdx
@@ -0,0 +1,986 @@
+---
+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:
+
+```python
+@mcp.tool(
+    annotations={
+        "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={"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={"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 000000000..280733a8b
--- /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 000000000..07a8db549
--- /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 000000000..362eb0026
--- /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.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 000000000..65e212e8d
--- /dev/null
+++ b/docs/v2/updates.mdx
@@ -0,0 +1,425 @@
+---
+title: "FastMCP Updates"
+sidebarTitle: "Updates"
+icon: "sparkles"
+tag: NEW
+---
+
+<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/chart_server.py b/examples/apps/chart_server.py
new file mode 100644
index 000000000..94130f777
--- /dev/null
+++ b/examples/apps/chart_server.py
@@ -0,0 +1,102 @@
+"""Chart MCP App — interactive data visualizations with Prefab.
+
+Demonstrates `fastmcp[apps]` with Prefab chart components:
+- `BarChart` and `LineChart` for categorical and trend data
+- Multiple series, stacking, and curve styles
+- Layout composition with `Column`, `Heading`, and `Muted`
+- Custom text fallback via `ToolResult`
+
+Usage:
+    uv run python chart_server.py              # HTTP (port 8000)
+    uv run python chart_server.py --stdio       # stdio for MCP clients
+"""
+
+from __future__ import annotations
+
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    BarChart,
+    ChartSeries,
+    Column,
+    Heading,
+    LineChart,
+    Muted,
+)
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Sales Dashboard")
+
+MONTHLY_SALES = [
+    {"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_overview(stacked: bool = False) -> PrefabApp:
+    """View monthly sales broken down by channel.
+
+    Args:
+        stacked: Stack bars to show total revenue per month.
+    """
+    total = sum(row["online"] + row["retail"] for row in MONTHLY_SALES)
+
+    with Column(gap=6, css_class="p-6") as view:
+        with Column(gap=1):
+            Heading("Monthly Sales")
+            Muted(f"${total:,} total revenue")
+
+        BarChart(
+            data=MONTHLY_SALES,
+            series=[
+                ChartSeries(data_key="online", label="Online"),
+                ChartSeries(data_key="retail", label="Retail"),
+            ],
+            x_axis="month",
+            stacked=stacked,
+            show_legend=True,
+        )
+
+    return PrefabApp(
+        title="Sales Dashboard",
+        view=view,
+    )
+
+
+@mcp.tool(app=True)
+def sales_trend(curve: str = "linear") -> PrefabApp:
+    """View sales trends over time as a line chart.
+
+    Args:
+        curve: Line style — "linear", "smooth", or "step".
+    """
+    with Column(gap=6, css_class="p-6") as view:
+        with Column(gap=1):
+            Heading("Sales Trend")
+            Muted("Online vs. retail over 6 months")
+
+        LineChart(
+            data=MONTHLY_SALES,
+            series=[
+                ChartSeries(data_key="online", label="Online"),
+                ChartSeries(data_key="retail", label="Retail"),
+            ],
+            x_axis="month",
+            curve=curve,
+            show_dots=True,
+            show_legend=True,
+        )
+
+    return PrefabApp(
+        title="Sales Trend",
+        view=view,
+    )
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/datatable_server.py b/examples/apps/datatable_server.py
new file mode 100644
index 000000000..1f79c51dd
--- /dev/null
+++ b/examples/apps/datatable_server.py
@@ -0,0 +1,165 @@
+"""DataTable MCP App — interactive, sortable data views with Prefab.
+
+Demonstrates `fastmcp[apps]` with Prefab UI components:
+- `app=True` for automatic renderer wiring
+- `PrefabApp` with `DataTable` for rich tabular views
+- Searchable, sortable, paginated tables
+- Layout composition with `Column`, `Heading`, `Text`, and `Badge`
+
+Usage:
+    uv run python datatable_server.py              # HTTP (port 8000)
+    uv run python datatable_server.py --stdio       # stdio for MCP clients
+"""
+
+from __future__ import annotations
+
+from prefab_ui.app import PrefabApp
+from prefab_ui.components import (
+    Badge,
+    Column,
+    DataTable,
+    DataTableColumn,
+    Heading,
+    Muted,
+    Row,
+)
+
+from fastmcp import FastMCP
+
+mcp = FastMCP("Team Directory")
+
+EMPLOYEES = [
+    {
+        "name": "Alice Chen",
+        "role": "Engineering",
+        "level": "Senior",
+        "location": "San Francisco",
+        "status": "active",
+    },
+    {
+        "name": "Bob Martinez",
+        "role": "Design",
+        "level": "Lead",
+        "location": "New York",
+        "status": "active",
+    },
+    {
+        "name": "Carol Johnson",
+        "role": "Engineering",
+        "level": "Staff",
+        "location": "London",
+        "status": "active",
+    },
+    {
+        "name": "David Kim",
+        "role": "Product",
+        "level": "Senior",
+        "location": "San Francisco",
+        "status": "away",
+    },
+    {
+        "name": "Eva Müller",
+        "role": "Engineering",
+        "level": "Mid",
+        "location": "Berlin",
+        "status": "active",
+    },
+    {
+        "name": "Frank Okafor",
+        "role": "Data Science",
+        "level": "Senior",
+        "location": "Lagos",
+        "status": "active",
+    },
+    {
+        "name": "Grace Liu",
+        "role": "Engineering",
+        "level": "Junior",
+        "location": "Singapore",
+        "status": "active",
+    },
+    {
+        "name": "Hassan Ali",
+        "role": "Design",
+        "level": "Senior",
+        "location": "Dubai",
+        "status": "away",
+    },
+    {
+        "name": "Iris Tanaka",
+        "role": "Product",
+        "level": "Lead",
+        "location": "Tokyo",
+        "status": "active",
+    },
+    {
+        "name": "James Wright",
+        "role": "Engineering",
+        "level": "Senior",
+        "location": "London",
+        "status": "inactive",
+    },
+    {
+        "name": "Karen Petrov",
+        "role": "Data Science",
+        "level": "Lead",
+        "location": "Berlin",
+        "status": "active",
+    },
+    {
+        "name": "Liam O'Brien",
+        "role": "Engineering",
+        "level": "Mid",
+        "location": "Dublin",
+        "status": "active",
+    },
+]
+
+
+@mcp.tool(app=True)
+def list_team(department: str | None = None) -> PrefabApp:
+    """Browse the team directory with sorting and search.
+
+    Args:
+        department: Filter by department (e.g. "Engineering", "Design").
+                    Leave empty to show everyone.
+    """
+    if department:
+        rows = [e for e in EMPLOYEES if e["role"].lower() == department.lower()]
+    else:
+        rows = EMPLOYEES
+
+    active = sum(1 for e in rows if e["status"] == "active")
+
+    with Column(gap=6, css_class="p-6") as view:
+        with Column(gap=1):
+            Heading("Team Directory")
+            with Row(gap=2):
+                Muted(f"{len(rows)} members")
+                Muted(f"{active} active", css_class="text-success")
+                if department:
+                    Badge(department, variant="outline")
+
+        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),
+                DataTableColumn(key="status", header="Status", sortable=True),
+            ],
+            rows=rows,
+            searchable=True,
+            paginated=True,
+            page_size=10,
+        )
+
+    return PrefabApp(
+        title="Team Directory",
+        view=view,
+        state={"total": len(rows), "active": active},
+    )
+
+
+if __name__ == "__main__":
+    mcp.run()
diff --git a/examples/apps/patterns_server.py b/examples/apps/patterns_server.py
new file mode 100644
index 000000000..9b5b8ac79
--- /dev/null
+++ b/examples/apps/patterns_server.py
@@ -0,0 +1,489 @@
+"""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,
+    AreaChart,
+    Badge,
+    BarChart,
+    Button,
+    Card,
+    CardContent,
+    ChartSeries,
+    Column,
+    DataTable,
+    DataTableColumn,
+    ForEach,
+    Form,
+    Grid,
+    Heading,
+    If,
+    Input,
+    Muted,
+    PieChart,
+    Progress,
+    Row,
+    Select,
+    Separator,
+    Switch,
+    Tab,
+    Tabs,
+    Text,
+    Textarea,
+)
+
+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,
+            searchable=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"):
+            with Row(gap=2, align="center"):
+                Text("{{ name }}", css_class="font-medium")
+                Muted("{{ email }}")
+                Badge("{{ 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("{{ dark_mode }}"):
+            Alert(title="Dark mode enabled", description="UI will use dark theme.")
+        with If("{{ 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"):
+                    with Row(gap=2):
+                        Muted("{{ timestamp }}")
+                        Text("{{ 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 000000000..2cfe806b1
--- /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 000000000..7e74faa31
--- /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 000000000..815ea0a75
--- /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 000000000..7a3d5ee64
--- /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.server.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/atproto_mcp/README.md b/examples/atproto_mcp/README.md
new file mode 100644
index 000000000..754355400
--- /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 000000000..154e111d8
--- /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 000000000..d51fdc209
--- /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 000000000..2f1b67ad9
--- /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 000000000..9752f9b8c
--- /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 000000000..bb4c12e7a
--- /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 000000000..ae9b7660e
--- /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 000000000..40ee8e160
--- /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 000000000..daf8c340a
--- /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 000000000..956ae5412
--- /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 000000000..189185a4a
--- /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 000000000..87bd02976
--- /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/tests/servers/__init__.py b/examples/atproto_mcp/src/atproto_mcp/py.typed
similarity index 100%
rename from tests/servers/__init__.py
rename to examples/atproto_mcp/src/atproto_mcp/py.typed
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 000000000..4f9ef4ec2
--- /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 000000000..9eed40837
--- /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 000000000..e95fc2119
--- /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_dcr/README.md b/examples/auth/authkit_dcr/README.md
new file mode 100644
index 000000000..808246199
--- /dev/null
+++ b/examples/auth/authkit_dcr/README.md
@@ -0,0 +1,25 @@
+# AuthKit DCR Example
+
+Demonstrates FastMCP server protection with AuthKit Dynamic Client Registration.
+
+## Setup
+
+1. Set your AuthKit domain:
+
+   ```bash
+   export 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 AuthKit authentication.
diff --git a/examples/auth/authkit_dcr/client.py b/examples/auth/authkit_dcr/client.py
new file mode 100644
index 000000000..562637bec
--- /dev/null
+++ b/examples/auth/authkit_dcr/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_dcr/server.py b/examples/auth/authkit_dcr/server.py
new file mode 100644
index 000000000..8974376d2
--- /dev/null
+++ b/examples/auth/authkit_dcr/server.py
@@ -0,0 +1,32 @@
+"""AuthKit DCR server example for FastMCP.
+
+This example demonstrates how to protect a FastMCP server with AuthKit DCR.
+
+Required environment variables:
+- FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_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://localhost:8000",
+)
+
+mcp = FastMCP("AuthKit DCR 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 000000000..9abff838c
--- /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://localhost: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 000000000..4043e6d4f
--- /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://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}")
+
+            # 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 000000000..9c7f15cd1
--- /dev/null
+++ b/examples/auth/aws_oauth/requirements.txt
@@ -0,0 +1,2 @@
+fastmcp
+python-dotenv
\ No newline at end of file
diff --git a/examples/auth/aws_oauth/server.py b/examples/auth/aws_oauth/server.py
new file mode 100644
index 000000000..dfe596a83
--- /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://localhost: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 000000000..ba0757ca7
--- /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://localhost: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 000000000..5f1f39bb2
--- /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 000000000..d214389aa
--- /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://localhost: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/discord_oauth/README.md b/examples/auth/discord_oauth/README.md
new file mode 100644
index 000000000..74217f833
--- /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://localhost: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 000000000..880b86f4d
--- /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 000000000..424c97bdb
--- /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://localhost: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 000000000..557ba7774
--- /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://localhost: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 000000000..7158583bc
--- /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://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/github_oauth/server.py b/examples/auth/github_oauth/server.py
new file mode 100644
index 000000000..1f88c6977
--- /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://localhost: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 000000000..869718344
--- /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://localhost: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 000000000..5f1f39bb2
--- /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 000000000..2a5b1c7df
--- /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://localhost: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/mounted/README.md b/examples/auth/mounted/README.md
new file mode 100644
index 000000000..5810dab4c
--- /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://localhost:8000/api/mcp/github/mcp`
+- **Google MCP**: `http://localhost:8000/api/mcp/google/mcp`
+
+Discovery endpoints (RFC 8414 path-aware):
+- **GitHub**: `http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/github`
+- **Google**: `http://localhost: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://localhost:8000/api/mcp/github/auth/callback/github`
+- Google: `http://localhost: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 000000000..2b691951f
--- /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 000000000..24aefdd59
--- /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://localhost:8000/api/mcp/github/mcp
+- Google MCP: http://localhost:8000/api/mcp/google/mcp
+- GitHub discovery: http://localhost:8000/.well-known/oauth-authorization-server/api/mcp/github
+- Google discovery: http://localhost: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://localhost: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/propelauth_oauth/README.md b/examples/auth/propelauth_oauth/README.md
new file mode 100644
index 000000000..575ea7314
--- /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://localhost: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://localhost: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 000000000..fd6a84b4e
--- /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 000000000..8401882aa
--- /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://localhost: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://localhost: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 000000000..c241d76f7
--- /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://localhost: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://localhost: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 000000000..4146b2c49
--- /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 000000000..68cef23b5
--- /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://localhost: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://localhost: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 000000000..62afa8df2
--- /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 000000000..5f1f39bb2
--- /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 000000000..08c1db62b
--- /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://localhost: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 000000000..28834f350
--- /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 000000000..3757becf6
--- /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 000000000..70aca8bfa
--- /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 000000000..014482a4a
--- /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 000000000..9d6976d8b
--- /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 000000000..7075b7238
--- /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
index 7c708ce9b..b32a31484 100644
--- a/examples/desktop.py
+++ b/examples/desktop.py
@@ -6,7 +6,7 @@
 
 from pathlib import Path
 
-from fastmcp.server import FastMCP
+from fastmcp import FastMCP
 
 # Create server
 mcp = FastMCP("Demo")
@@ -19,11 +19,14 @@ def desktop() -> list[str]:
     return [str(f) for f in desktop.iterdir()]
 
 
-@mcp.tool()
+# 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
-
-
-if __name__ == "__main__":
-    mcp.run()
diff --git a/examples/diagnostics/client_with_tracing.py b/examples/diagnostics/client_with_tracing.py
new file mode 100644
index 000000000..0b56ddc65
--- /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 000000000..211c5d893
--- /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
index 2a81ca4c0..c98f23d2f 100644
--- a/examples/echo.py
+++ b/examples/echo.py
@@ -4,16 +4,27 @@
 
 from fastmcp import FastMCP
 
-
 # Create server
 mcp = FastMCP("Echo Server")
 
 
-@mcp.tool()
-def echo(text: str) -> str:
+@mcp.tool
+def echo_tool(text: str) -> str:
     """Echo the input text"""
     return text
 
 
-if __name__ == "__main__":
-    mcp.run()
+@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 000000000..368980ea1
--- /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 000000000..0eb4af048
--- /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 000000000..3511d1153
--- /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 000000000..e31a4f8cb
--- /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 000000000..40f116bf9
--- /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 000000000..40541fefc
--- /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 000000000..7abf11c3d
--- /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 000000000..9027c6c81
--- /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 000000000..5453a06fe
--- /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/mcp/prompts/assistant.py b/examples/filesystem-provider/mcp/prompts/assistant.py
new file mode 100644
index 000000000..0950e3423
--- /dev/null
+++ b/examples/filesystem-provider/mcp/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/mcp/resources/config.py b/examples/filesystem-provider/mcp/resources/config.py
new file mode 100644
index 000000000..03a3f7b11
--- /dev/null
+++ b/examples/filesystem-provider/mcp/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/mcp/tools/calculator.py b/examples/filesystem-provider/mcp/tools/calculator.py
new file mode 100644
index 000000000..f8d901067
--- /dev/null
+++ b/examples/filesystem-provider/mcp/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/mcp/tools/greeting.py b/examples/filesystem-provider/mcp/tools/greeting.py
new file mode 100644
index 000000000..f124902a1
--- /dev/null
+++ b/examples/filesystem-provider/mcp/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 000000000..2f3cf47a6
--- /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 / "mcp",
+    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 000000000..b86ca9223
--- /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 000000000..45e7a10b2
--- /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 ``FastMCP.as_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 mcp.types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+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 FastMCP.as_proxy to wrap '{original_server.name}' directly)"
+    )
+    proxy_server = FastMCP.as_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 and isinstance(result[0], TextContent):
+                print(f"      Result from proxied 'echo' call: '{result[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 000000000..5ee1aea97
--- /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 000000000..792bd48c6
--- /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 000000000..d30d2e3e9
--- /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 000000000..9e8c0fb42
--- /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, prefix="weather")
+
+app.mount(server=news_app, prefix="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 000000000..3dffb146d
--- /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 000000000..7090f27e4
--- /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 000000000..f906d9f15
--- /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 000000000..efe5579c0
--- /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 000000000..a5bb6368f
--- /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 000000000..5264a80cc
--- /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 000000000..df44cd94c
--- /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 000000000..43f9bb477
--- /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 000000000..912ef0331
--- /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 000000000..9175a5e43
--- /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 000000000..dd9f19ff6
--- /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 000000000..beeb4283e
--- /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 000000000..8a23b12a6
--- /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 000000000..25141591e
--- /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 000000000..f49255e56
--- /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 000000000..3f9225b19
--- /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 000000000..1c3fb10af
--- /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 000000000..fa7afe7ad
--- /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 000000000..6d354e7c2
--- /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 000000000..e7869a16c
--- /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 000000000..9ff06d797
--- /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
index bfef5d8e9..866133733 100644
--- a/examples/screenshot.py
+++ b/examples/screenshot.py
@@ -1,5 +1,5 @@
 # /// script
-# dependencies = ["fastmcp", "pyautogui", "Pillow"]
+# dependencies = ["pyautogui", "Pillow", "fastmcp"]
 # ///
 
 """
@@ -10,23 +10,25 @@
 
 import io
 
-from fastmcp import FastMCP, Image
+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()
+@mcp.tool
 def take_screenshot() -> Image:
-    """Take a screenshot of the user's screen and return it as an 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
 
-    screenshot = pyautogui.screenshot()
     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")
-
-
-if __name__ == "__main__":
-    mcp.run()
diff --git a/examples/search/README.md b/examples/search/README.md
new file mode 100644
index 000000000..32a26390d
--- /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 000000000..b33e395a3
--- /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 000000000..ccccefbd2
--- /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 000000000..63cdf8048
--- /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 000000000..261ef6a55
--- /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 000000000..b1dc1f35a
--- /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 000000000..7f5ae14b5
--- /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 000000000..a376fe235
--- /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 000000000..69b8d0373
--- /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 000000000..0c57545d8
--- /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 000000000..2490f6792
--- /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 000000000..7b7b329d7
--- /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 000000000..a5cd49947
--- /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 000000000..5d065f594
--- /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 000000000..25daabbbd
--- /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 000000000..534cab55c
--- /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 000000000..e38609d6e
--- /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 000000000..dad7ea2e0
--- /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 000000000..ea5ae478a
--- /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 000000000..827eae159
--- /dev/null
+++ b/examples/smart_home/src/smart_home/hub.py
@@ -0,0 +1,31 @@
+from mcp.types import ToolAnnotations
+from phue import Bridge
+
+from fastmcp import FastMCP
+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 000000000..e69de29bb
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 000000000..4ec5e7106
--- /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 000000000..7af3953d0
--- /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 mcp.types import ToolAnnotations
+from phue.exceptions import PhueException
+from pydantic import Field
+from typing_extensions import NotRequired
+
+from fastmcp import FastMCP
+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 000000000..e69de29bb
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 000000000..d6b09acdd
--- /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 000000000..c5ff6ae0e
--- /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.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 000000000..51f7b046a
--- /dev/null
+++ b/examples/task_elicitation.py
@@ -0,0 +1,82 @@
+"""
+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 mcp.types import TextContent
+
+from fastmcp import Context, FastMCP
+from fastmcp.client import Client
+from fastmcp.server.elicitation import AcceptedElicitation
+
+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/.envrc b/examples/tasks/.envrc
new file mode 100644
index 000000000..87a7dfef9
--- /dev/null
+++ b/examples/tasks/.envrc
@@ -0,0 +1,10 @@
+# FastMCP Tasks Example Environment Configuration
+# This file is loaded by direnv (https://direnv.net/) when you cd into this directory
+# Run `direnv allow` to enable automatic environment loading
+
+# Configure Docket backend URL
+# Use Redis backend (requires docker-compose up)
+export FASTMCP_DOCKET_URL=redis://localhost:24242/0
+
+# Or uncomment to use memory:// for single-process testing
+# export FASTMCP_DOCKET_URL=memory://
diff --git a/examples/tasks/README.md b/examples/tasks/README.md
new file mode 100644
index 000000000..8013968d5
--- /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 000000000..f72814889
--- /dev/null
+++ b/examples/tasks/client.py
@@ -0,0 +1,160 @@
+"""
+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, TextContent
+from rich.console import Console
+
+from fastmcp.client import Client
+
+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 statusMessage 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.statusMessage == _last_notification_message:
+        return
+
+    _last_notification_message = status.statusMessage
+
+    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.statusMessage}[/{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 000000000..d5643b2b3
--- /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 000000000..77b3cde82
--- /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 000000000..e4e711111
--- /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 000000000..dce14d85e
--- /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>=8.3.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 000000000..2bac46e8c
--- /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 000000000..921d6c3fc
--- /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 000000000..8f07579f9
--- /dev/null
+++ b/examples/testing_demo/uv.lock
@@ -0,0 +1,1871 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[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.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "idna" },
+    { name = "sniffio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c6/78/7d432127c41b50bccba979505f272c16cbcadcc33645d5fa3a738110ae75/anyio-4.11.0.tar.gz", hash = "sha256:82a8d0b81e318cc5ce71a5f1f8b5c4e63619620b63141ef8c995fa0db95a57c4", size = 219094, upload-time = "2025-09-23T09:19:12.58Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/15/b3/9b1a8074496371342ec1e796a96f99c82c945a339cd81a8e73de28b4cf9e/anyio-4.11.0-py3-none-any.whl", hash = "sha256:0287e96f4d26d4149305414d4e3bc32f0dcd0862365a4bddea19d7a1ec38c4fc", size = 109097, upload-time = "2025-09-23T09:19:10.601Z" },
+]
+
+[[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 = "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.6.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bb/9b/b1661026ff24bc641b76b78c5222d614776b0c085bcfdac9bd15a1cb4b35/authlib-1.6.6.tar.gz", hash = "sha256:45770e8e056d0f283451d9996fbb59b70d45722b45d854d58f32878d0a40c38e", size = 164894, upload-time = "2025-12-12T08:01:41.464Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/51/321e821856452f7386c4e9df866f196720b1ad0c5ea1623ea7399969ae3b/authlib-1.6.6-py2.py3-none-any.whl", hash = "sha256:7d9e9bc535c13974313a87f53e8430eb6ea3d1cf6ae4f6efcd793f2e949143fd", size = 244005, upload-time = "2025-12-12T08:01:40.209Z" },
+]
+
+[[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.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/09/9003e5662691056e0e8b2e6f57c799e71875fac0be0e785d8cb11557cd2a/beartype-0.22.5.tar.gz", hash = "sha256:516a9096cc77103c96153474fa35c3ebcd9d36bd2ec8d0e3a43307ced0fa6341", size = 1586256, upload-time = "2025-11-01T05:49:20.771Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/f6/073d19f7b571c08327fbba3f8e011578da67ab62a11f98911274ff80653f/beartype-0.22.5-py3-none-any.whl", hash = "sha256:d9743dd7cd6d193696eaa1e025f8a70fb09761c154675679ff236e61952dfba0", size = 1321700, upload-time = "2025-11-01T05:49:18.436Z" },
+]
+
+[[package]]
+name = "cachetools"
+version = "6.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cc/7e/b975b5814bd36faf009faebe22c1072a1fa1168db34d285ef0ba071ad78c/cachetools-6.2.1.tar.gz", hash = "sha256:3f391e4bd8f8bf0931169baf7456cc822705f4e2a31f840d218f445b9a854201", size = 31325, upload-time = "2025-10-12T14:55:30.139Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/c5/1e741d26306c42e2bf6ab740b2202872727e0f606033c9dd713f8b93f5a8/cachetools-6.2.1-py3-none-any.whl", hash = "sha256:09868944b6dde876dfd44e1d47e18484541eaf12f26f29b7af91b26cc892d701", size = 11280, upload-time = "2025-10-12T14:55:28.382Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2025.10.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4c/5b/b6ce21586237c77ce67d01dc5507039d444b630dd76611bbca2d8e5dcd91/certifi-2025.10.5.tar.gz", hash = "sha256:47c09d31ccf2acf0be3f701ea53595ee7e0b8fa08801c6624be771df09ae7b43", size = 164519, upload-time = "2025-10-05T04:12:15.808Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e4/37/af0d2ef3967ac0d6113837b44a4f0bfe1328c2b9763bd5b1744520e5cfed/certifi-2025.10.5-py3-none-any.whl", hash = "sha256:0f212c2744a9bb6de0c56639a6f68afe01ecd92d91f14ae897c4fe7bbeeef0de", size = 163286, upload-time = "2025-10-05T04:12:14.03Z" },
+]
+
+[[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.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/13/69/33ddede1939fdd074bce5434295f38fae7136463422fe4fd3e0e89b98062/charset_normalizer-3.4.4.tar.gz", hash = "sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a", size = 129418, upload-time = "2025-10-14T04:42:32.879Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1f/b8/6d51fc1d52cbd52cd4ccedd5b5b2f0f6a11bbf6765c782298b0f3e808541/charset_normalizer-3.4.4-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:e824f1492727fa856dd6eda4f7cee25f8518a12f3c4a56a74e8095695089cf6d", size = 209709, upload-time = "2025-10-14T04:40:11.385Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/af/1f9d7f7faafe2ddfb6f72a2e07a548a629c61ad510fe60f9630309908fef/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4bd5d4137d500351a30687c2d3971758aac9a19208fc110ccb9d7188fbe709e8", size = 148814, upload-time = "2025-10-14T04:40:13.135Z" },
+    { url = "https://files.pythonhosted.org/packages/79/3d/f2e3ac2bbc056ca0c204298ea4e3d9db9b4afe437812638759db2c976b5f/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:027f6de494925c0ab2a55eab46ae5129951638a49a34d87f4c3eda90f696b4ad", size = 144467, upload-time = "2025-10-14T04:40:14.728Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/85/1bf997003815e60d57de7bd972c57dc6950446a3e4ccac43bc3070721856/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f820802628d2694cb7e56db99213f930856014862f3fd943d290ea8438d07ca8", size = 162280, upload-time = "2025-10-14T04:40:16.14Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/8e/6aa1952f56b192f54921c436b87f2aaf7c7a7c3d0d1a765547d64fd83c13/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:798d75d81754988d2565bff1b97ba5a44411867c0cf32b77a7e8f8d84796b10d", size = 159454, upload-time = "2025-10-14T04:40:17.567Z" },
+    { url = "https://files.pythonhosted.org/packages/36/3b/60cbd1f8e93aa25d1c669c649b7a655b0b5fb4c571858910ea9332678558/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d1bb833febdff5c8927f922386db610b49db6e0d4f4ee29601d71e7c2694313", size = 153609, upload-time = "2025-10-14T04:40:19.08Z" },
+    { url = "https://files.pythonhosted.org/packages/64/91/6a13396948b8fd3c4b4fd5bc74d045f5637d78c9675585e8e9fbe5636554/charset_normalizer-3.4.4-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9cd98cdc06614a2f768d2b7286d66805f94c48cde050acdbbb7db2600ab3197e", size = 151849, upload-time = "2025-10-14T04:40:20.607Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/7a/59482e28b9981d105691e968c544cc0df3b7d6133152fb3dcdc8f135da7a/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:077fbb858e903c73f6c9db43374fd213b0b6a778106bc7032446a8e8b5b38b93", size = 151586, upload-time = "2025-10-14T04:40:21.719Z" },
+    { url = "https://files.pythonhosted.org/packages/92/59/f64ef6a1c4bdd2baf892b04cd78792ed8684fbc48d4c2afe467d96b4df57/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:244bfb999c71b35de57821b8ea746b24e863398194a4014e4c76adc2bbdfeff0", size = 145290, upload-time = "2025-10-14T04:40:23.069Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/63/3bf9f279ddfa641ffa1962b0db6a57a9c294361cc2f5fcac997049a00e9c/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:64b55f9dce520635f018f907ff1b0df1fdc31f2795a922fb49dd14fbcdf48c84", size = 163663, upload-time = "2025-10-14T04:40:24.17Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/09/c9e38fc8fa9e0849b172b581fd9803bdf6e694041127933934184e19f8c3/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:faa3a41b2b66b6e50f84ae4a68c64fcd0c44355741c6374813a800cd6695db9e", size = 151964, upload-time = "2025-10-14T04:40:25.368Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/d1/d28b747e512d0da79d8b6a1ac18b7ab2ecfd81b2944c4c710e166d8dd09c/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:6515f3182dbe4ea06ced2d9e8666d97b46ef4c75e326b79bb624110f122551db", size = 161064, upload-time = "2025-10-14T04:40:26.806Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/9a/31d62b611d901c3b9e5500c36aab0ff5eb442043fb3a1c254200d3d397d9/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:cc00f04ed596e9dc0da42ed17ac5e596c6ccba999ba6bd92b0e0aef2f170f2d6", size = 155015, upload-time = "2025-10-14T04:40:28.284Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f3/107e008fa2bff0c8b9319584174418e5e5285fef32f79d8ee6a430d0039c/charset_normalizer-3.4.4-cp310-cp310-win32.whl", hash = "sha256:f34be2938726fc13801220747472850852fe6b1ea75869a048d6f896838c896f", size = 99792, upload-time = "2025-10-14T04:40:29.613Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/66/e396e8a408843337d7315bab30dbf106c38966f1819f123257f5520f8a96/charset_normalizer-3.4.4-cp310-cp310-win_amd64.whl", hash = "sha256:a61900df84c667873b292c3de315a786dd8dac506704dea57bc957bd31e22c7d", size = 107198, upload-time = "2025-10-14T04:40:30.644Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/58/01b4f815bf0312704c267f2ccb6e5d42bcc7752340cd487bc9f8c3710597/charset_normalizer-3.4.4-cp310-cp310-win_arm64.whl", hash = "sha256:cead0978fc57397645f12578bfd2d5ea9138ea0fac82b2f63f7f7c6877986a69", size = 100262, upload-time = "2025-10-14T04:40:32.108Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/27/c6491ff4954e58a10f69ad90aca8a1b6fe9c5d3c6f380907af3c37435b59/charset_normalizer-3.4.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6e1fcf0720908f200cd21aa4e6750a48ff6ce4afe7ff5a79a90d5ed8a08296f8", size = 206988, upload-time = "2025-10-14T04:40:33.79Z" },
+    { url = "https://files.pythonhosted.org/packages/94/59/2e87300fe67ab820b5428580a53cad894272dbb97f38a7a814a2a1ac1011/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5f819d5fe9234f9f82d75bdfa9aef3a3d72c4d24a6e57aeaebba32a704553aa0", size = 147324, upload-time = "2025-10-14T04:40:34.961Z" },
+    { url = "https://files.pythonhosted.org/packages/07/fb/0cf61dc84b2b088391830f6274cb57c82e4da8bbc2efeac8c025edb88772/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:a59cb51917aa591b1c4e6a43c132f0cdc3c76dbad6155df4e28ee626cc77a0a3", size = 142742, upload-time = "2025-10-14T04:40:36.105Z" },
+    { url = "https://files.pythonhosted.org/packages/62/8b/171935adf2312cd745d290ed93cf16cf0dfe320863ab7cbeeae1dcd6535f/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8ef3c867360f88ac904fd3f5e1f902f13307af9052646963ee08ff4f131adafc", size = 160863, upload-time = "2025-10-14T04:40:37.188Z" },
+    { url = "https://files.pythonhosted.org/packages/09/73/ad875b192bda14f2173bfc1bc9a55e009808484a4b256748d931b6948442/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d9e45d7faa48ee908174d8fe84854479ef838fc6a705c9315372eacbc2f02897", size = 157837, upload-time = "2025-10-14T04:40:38.435Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/fc/de9cce525b2c5b94b47c70a4b4fb19f871b24995c728e957ee68ab1671ea/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:840c25fb618a231545cbab0564a799f101b63b9901f2569faecd6b222ac72381", size = 151550, upload-time = "2025-10-14T04:40:40.053Z" },
+    { url = "https://files.pythonhosted.org/packages/55/c2/43edd615fdfba8c6f2dfbd459b25a6b3b551f24ea21981e23fb768503ce1/charset_normalizer-3.4.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ca5862d5b3928c4940729dacc329aa9102900382fea192fc5e52eb69d6093815", size = 149162, upload-time = "2025-10-14T04:40:41.163Z" },
+    { url = "https://files.pythonhosted.org/packages/03/86/bde4ad8b4d0e9429a4e82c1e8f5c659993a9a863ad62c7df05cf7b678d75/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d9c7f57c3d666a53421049053eaacdd14bbd0a528e2186fcb2e672effd053bb0", size = 150019, upload-time = "2025-10-14T04:40:42.276Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/86/a151eb2af293a7e7bac3a739b81072585ce36ccfb4493039f49f1d3cae8c/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:277e970e750505ed74c832b4bf75dac7476262ee2a013f5574dd49075879e161", size = 143310, upload-time = "2025-10-14T04:40:43.439Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/fe/43dae6144a7e07b87478fdfc4dbe9efd5defb0e7ec29f5f58a55aeef7bf7/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:31fd66405eaf47bb62e8cd575dc621c56c668f27d46a61d975a249930dd5e2a4", size = 162022, upload-time = "2025-10-14T04:40:44.547Z" },
+    { url = "https://files.pythonhosted.org/packages/80/e6/7aab83774f5d2bca81f42ac58d04caf44f0cc2b65fc6db2b3b2e8a05f3b3/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:0d3d8f15c07f86e9ff82319b3d9ef6f4bf907608f53fe9d92b28ea9ae3d1fd89", size = 149383, upload-time = "2025-10-14T04:40:46.018Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/e8/b289173b4edae05c0dde07f69f8db476a0b511eac556dfe0d6bda3c43384/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:9f7fcd74d410a36883701fafa2482a6af2ff5ba96b9a620e9e0721e28ead5569", size = 159098, upload-time = "2025-10-14T04:40:47.081Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/df/fe699727754cae3f8478493c7f45f777b17c3ef0600e28abfec8619eb49c/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ebf3e58c7ec8a8bed6d66a75d7fb37b55e5015b03ceae72a8e7c74495551e224", size = 152991, upload-time = "2025-10-14T04:40:48.246Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/86/584869fe4ddb6ffa3bd9f491b87a01568797fb9bd8933f557dba9771beaf/charset_normalizer-3.4.4-cp311-cp311-win32.whl", hash = "sha256:eecbc200c7fd5ddb9a7f16c7decb07b566c29fa2161a16cf67b8d068bd21690a", size = 99456, upload-time = "2025-10-14T04:40:49.376Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f6/62fdd5feb60530f50f7e38b4f6a1d5203f4d16ff4f9f0952962c044e919a/charset_normalizer-3.4.4-cp311-cp311-win_amd64.whl", hash = "sha256:5ae497466c7901d54b639cf42d5b8c1b6a4fead55215500d2f486d34db48d016", size = 106978, upload-time = "2025-10-14T04:40:50.844Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/9d/0710916e6c82948b3be62d9d398cb4fcf4e97b56d6a6aeccd66c4b2f2bd5/charset_normalizer-3.4.4-cp311-cp311-win_arm64.whl", hash = "sha256:65e2befcd84bc6f37095f5961e68a6f077bf44946771354a28ad434c2cce0ae1", size = 99969, upload-time = "2025-10-14T04:40:52.272Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/85/1637cd4af66fa687396e757dec650f28025f2a2f5a5531a3208dc0ec43f2/charset_normalizer-3.4.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0a98e6759f854bd25a58a73fa88833fba3b7c491169f86ce1180c948ab3fd394", size = 208425, upload-time = "2025-10-14T04:40:53.353Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/6a/04130023fef2a0d9c62d0bae2649b69f7b7d8d24ea5536feef50551029df/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b5b290ccc2a263e8d185130284f8501e3e36c5e02750fc6b6bdeb2e9e96f1e25", size = 148162, upload-time = "2025-10-14T04:40:54.558Z" },
+    { url = "https://files.pythonhosted.org/packages/78/29/62328d79aa60da22c9e0b9a66539feae06ca0f5a4171ac4f7dc285b83688/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74bb723680f9f7a6234dcf67aea57e708ec1fbdf5699fb91dfd6f511b0a320ef", size = 144558, upload-time = "2025-10-14T04:40:55.677Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bb/b32194a4bf15b88403537c2e120b817c61cd4ecffa9b6876e941c3ee38fe/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f1e34719c6ed0b92f418c7c780480b26b5d9c50349e9a9af7d76bf757530350d", size = 161497, upload-time = "2025-10-14T04:40:57.217Z" },
+    { url = "https://files.pythonhosted.org/packages/19/89/a54c82b253d5b9b111dc74aca196ba5ccfcca8242d0fb64146d4d3183ff1/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2437418e20515acec67d86e12bf70056a33abdacb5cb1655042f6538d6b085a8", size = 159240, upload-time = "2025-10-14T04:40:58.358Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/10/d20b513afe03acc89ec33948320a5544d31f21b05368436d580dec4e234d/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:11d694519d7f29d6cd09f6ac70028dba10f92f6cdd059096db198c283794ac86", size = 153471, upload-time = "2025-10-14T04:40:59.468Z" },
+    { url = "https://files.pythonhosted.org/packages/61/fa/fbf177b55bdd727010f9c0a3c49eefa1d10f960e5f09d1d887bf93c2e698/charset_normalizer-3.4.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ac1c4a689edcc530fc9d9aa11f5774b9e2f33f9a0c6a57864e90908f5208d30a", size = 150864, upload-time = "2025-10-14T04:41:00.623Z" },
+    { url = "https://files.pythonhosted.org/packages/05/12/9fbc6a4d39c0198adeebbde20b619790e9236557ca59fc40e0e3cebe6f40/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:21d142cc6c0ec30d2efee5068ca36c128a30b0f2c53c1c07bd78cb6bc1d3be5f", size = 150647, upload-time = "2025-10-14T04:41:01.754Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/1f/6a9a593d52e3e8c5d2b167daf8c6b968808efb57ef4c210acb907c365bc4/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:5dbe56a36425d26d6cfb40ce79c314a2e4dd6211d51d6d2191c00bed34f354cc", size = 145110, upload-time = "2025-10-14T04:41:03.231Z" },
+    { url = "https://files.pythonhosted.org/packages/30/42/9a52c609e72471b0fc54386dc63c3781a387bb4fe61c20231a4ebcd58bdd/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:5bfbb1b9acf3334612667b61bd3002196fe2a1eb4dd74d247e0f2a4d50ec9bbf", size = 162839, upload-time = "2025-10-14T04:41:04.715Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/5b/c0682bbf9f11597073052628ddd38344a3d673fda35a36773f7d19344b23/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:d055ec1e26e441f6187acf818b73564e6e6282709e9bcb5b63f5b23068356a15", size = 150667, upload-time = "2025-10-14T04:41:05.827Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/24/a41afeab6f990cf2daf6cb8c67419b63b48cf518e4f56022230840c9bfb2/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:af2d8c67d8e573d6de5bc30cdb27e9b95e49115cd9baad5ddbd1a6207aaa82a9", size = 160535, upload-time = "2025-10-14T04:41:06.938Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/e5/6a4ce77ed243c4a50a1fecca6aaaab419628c818a49434be428fe24c9957/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:780236ac706e66881f3b7f2f32dfe90507a09e67d1d454c762cf642e6e1586e0", size = 154816, upload-time = "2025-10-14T04:41:08.101Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/ef/89297262b8092b312d29cdb2517cb1237e51db8ecef2e9af5edbe7b683b1/charset_normalizer-3.4.4-cp312-cp312-win32.whl", hash = "sha256:5833d2c39d8896e4e19b689ffc198f08ea58116bee26dea51e362ecc7cd3ed26", size = 99694, upload-time = "2025-10-14T04:41:09.23Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/2d/1e5ed9dd3b3803994c155cd9aacb60c82c331bad84daf75bcb9c91b3295e/charset_normalizer-3.4.4-cp312-cp312-win_amd64.whl", hash = "sha256:a79cfe37875f822425b89a82333404539ae63dbdddf97f84dcbc3d339aae9525", size = 107131, upload-time = "2025-10-14T04:41:10.467Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/d9/0ed4c7098a861482a7b6a95603edce4c0d9db2311af23da1fb2b75ec26fc/charset_normalizer-3.4.4-cp312-cp312-win_arm64.whl", hash = "sha256:376bec83a63b8021bb5c8ea75e21c4ccb86e7e45ca4eb81146091b56599b80c3", size = 100390, upload-time = "2025-10-14T04:41:11.915Z" },
+    { url = "https://files.pythonhosted.org/packages/97/45/4b3a1239bbacd321068ea6e7ac28875b03ab8bc0aa0966452db17cd36714/charset_normalizer-3.4.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794", size = 208091, upload-time = "2025-10-14T04:41:13.346Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/62/73a6d7450829655a35bb88a88fca7d736f9882a27eacdca2c6d505b57e2e/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed", size = 147936, upload-time = "2025-10-14T04:41:14.461Z" },
+    { url = "https://files.pythonhosted.org/packages/89/c5/adb8c8b3d6625bef6d88b251bbb0d95f8205831b987631ab0c8bb5d937c2/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72", size = 144180, upload-time = "2025-10-14T04:41:15.588Z" },
+    { url = "https://files.pythonhosted.org/packages/91/ed/9706e4070682d1cc219050b6048bfd293ccf67b3d4f5a4f39207453d4b99/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328", size = 161346, upload-time = "2025-10-14T04:41:16.738Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/0d/031f0d95e4972901a2f6f09ef055751805ff541511dc1252ba3ca1f80cf5/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede", size = 158874, upload-time = "2025-10-14T04:41:17.923Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/83/6ab5883f57c9c801ce5e5677242328aa45592be8a00644310a008d04f922/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894", size = 153076, upload-time = "2025-10-14T04:41:19.106Z" },
+    { url = "https://files.pythonhosted.org/packages/75/1e/5ff781ddf5260e387d6419959ee89ef13878229732732ee73cdae01800f2/charset_normalizer-3.4.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1", size = 150601, upload-time = "2025-10-14T04:41:20.245Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/57/71be810965493d3510a6ca79b90c19e48696fb1ff964da319334b12677f0/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490", size = 150376, upload-time = "2025-10-14T04:41:21.398Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/d5/c3d057a78c181d007014feb7e9f2e65905a6c4ef182c0ddf0de2924edd65/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44", size = 144825, upload-time = "2025-10-14T04:41:22.583Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8c/d0406294828d4976f275ffbe66f00266c4b3136b7506941d87c00cab5272/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133", size = 162583, upload-time = "2025-10-14T04:41:23.754Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/24/e2aa1f18c8f15c4c0e932d9287b8609dd30ad56dbe41d926bd846e22fb8d/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3", size = 150366, upload-time = "2025-10-14T04:41:25.27Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/5b/1e6160c7739aad1e2df054300cc618b06bf784a7a164b0f238360721ab86/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e", size = 160300, upload-time = "2025-10-14T04:41:26.725Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/10/f882167cd207fbdd743e55534d5d9620e095089d176d55cb22d5322f2afd/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc", size = 154465, upload-time = "2025-10-14T04:41:28.322Z" },
+    { url = "https://files.pythonhosted.org/packages/89/66/c7a9e1b7429be72123441bfdbaf2bc13faab3f90b933f664db506dea5915/charset_normalizer-3.4.4-cp313-cp313-win32.whl", hash = "sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac", size = 99404, upload-time = "2025-10-14T04:41:29.95Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/26/b9924fa27db384bdcd97ab83b4f0a8058d96ad9626ead570674d5e737d90/charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14", size = 107092, upload-time = "2025-10-14T04:41:31.188Z" },
+    { url = "https://files.pythonhosted.org/packages/af/8f/3ed4bfa0c0c72a7ca17f0380cd9e4dd842b09f664e780c13cff1dcf2ef1b/charset_normalizer-3.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2", size = 100408, upload-time = "2025-10-14T04:41:32.624Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/35/7051599bd493e62411d6ede36fd5af83a38f37c4767b92884df7301db25d/charset_normalizer-3.4.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:da3326d9e65ef63a817ecbcc0df6e94463713b754fe293eaa03da99befb9a5bd", size = 207746, upload-time = "2025-10-14T04:41:33.773Z" },
+    { url = "https://files.pythonhosted.org/packages/10/9a/97c8d48ef10d6cd4fcead2415523221624bf58bcf68a802721a6bc807c8f/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8af65f14dc14a79b924524b1e7fffe304517b2bff5a58bf64f30b98bbc5079eb", size = 147889, upload-time = "2025-10-14T04:41:34.897Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/979224a919a1b606c82bd2c5fa49b5c6d5727aa47b4312bb27b1734f53cd/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74664978bb272435107de04e36db5a9735e78232b85b77d45cfb38f758efd33e", size = 143641, upload-time = "2025-10-14T04:41:36.116Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/33/0ad65587441fc730dc7bd90e9716b30b4702dc7b617e6ba4997dc8651495/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:752944c7ffbfdd10c074dc58ec2d5a8a4cd9493b314d367c14d24c17684ddd14", size = 160779, upload-time = "2025-10-14T04:41:37.229Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ed/331d6b249259ee71ddea93f6f2f0a56cfebd46938bde6fcc6f7b9a3d0e09/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d1f13550535ad8cff21b8d757a3257963e951d96e20ec82ab44bc64aeb62a191", size = 159035, upload-time = "2025-10-14T04:41:38.368Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ff/f6b948ca32e4f2a4576aa129d8bed61f2e0543bf9f5f2b7fc3758ed005c9/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ecaae4149d99b1c9e7b88bb03e3221956f68fd6d50be2ef061b2381b61d20838", size = 152542, upload-time = "2025-10-14T04:41:39.862Z" },
+    { url = "https://files.pythonhosted.org/packages/16/85/276033dcbcc369eb176594de22728541a925b2632f9716428c851b149e83/charset_normalizer-3.4.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cb6254dc36b47a990e59e1068afacdcd02958bdcce30bb50cc1700a8b9d624a6", size = 149524, upload-time = "2025-10-14T04:41:41.319Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/f2/6a2a1f722b6aba37050e626530a46a68f74e63683947a8acff92569f979a/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c8ae8a0f02f57a6e61203a31428fa1d677cbe50c93622b4149d5c0f319c1d19e", size = 150395, upload-time = "2025-10-14T04:41:42.539Z" },
+    { url = "https://files.pythonhosted.org/packages/60/bb/2186cb2f2bbaea6338cad15ce23a67f9b0672929744381e28b0592676824/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:47cc91b2f4dd2833fddaedd2893006b0106129d4b94fdb6af1f4ce5a9965577c", size = 143680, upload-time = "2025-10-14T04:41:43.661Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/a5/bf6f13b772fbb2a90360eb620d52ed8f796f3c5caee8398c3b2eb7b1c60d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:82004af6c302b5d3ab2cfc4cc5f29db16123b1a8417f2e25f9066f91d4411090", size = 162045, upload-time = "2025-10-14T04:41:44.821Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c5/d1be898bf0dc3ef9030c3825e5d3b83f2c528d207d246cbabe245966808d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b7d8f6c26245217bd2ad053761201e9f9680f8ce52f0fcd8d0755aeae5b2152", size = 149687, upload-time = "2025-10-14T04:41:46.442Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/42/90c1f7b9341eef50c8a1cb3f098ac43b0508413f33affd762855f67a410e/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:799a7a5e4fb2d5898c60b640fd4981d6a25f1c11790935a44ce38c54e985f828", size = 160014, upload-time = "2025-10-14T04:41:47.631Z" },
+    { url = "https://files.pythonhosted.org/packages/76/be/4d3ee471e8145d12795ab655ece37baed0929462a86e72372fd25859047c/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:99ae2cffebb06e6c22bdc25801d7b30f503cc87dbd283479e7b606f70aff57ec", size = 154044, upload-time = "2025-10-14T04:41:48.81Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/6f/8f7af07237c34a1defe7defc565a9bc1807762f672c0fde711a4b22bf9c0/charset_normalizer-3.4.4-cp314-cp314-win32.whl", hash = "sha256:f9d332f8c2a2fcbffe1378594431458ddbef721c1769d78e2cbc06280d8155f9", size = 99940, upload-time = "2025-10-14T04:41:49.946Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/51/8ade005e5ca5b0d80fb4aff72a3775b325bdc3d27408c8113811a7cbe640/charset_normalizer-3.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:8a6562c3700cce886c5be75ade4a5db4214fda19fede41d9792d100288d8f94c", size = 107104, upload-time = "2025-10-14T04:41:51.051Z" },
+    { url = "https://files.pythonhosted.org/packages/da/5f/6b8f83a55bb8278772c5ae54a577f3099025f9ade59d0136ac24a0df4bde/charset_normalizer-3.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:de00632ca48df9daf77a2c65a484531649261ec9f25489917f09e455cb09ddb2", size = 100743, upload-time = "2025-10-14T04:41:52.122Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/4c/925909008ed5a988ccbb72dcc897407e5d6d3bd72410d69e051fc0c14647/charset_normalizer-3.4.4-py3-none-any.whl", hash = "sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f", size = 53402, upload-time = "2025-10-14T04:42:31.76Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/46/61/de6cd827efad202d7057d93e0fed9294b96952e188f7384832791c7b2254/click-8.3.0.tar.gz", hash = "sha256:e7b8232224eba16f4ebe410c25ced9f7875cb5f3263ffc93cc3e8da705e229c4", size = 276943, upload-time = "2025-09-18T17:32:23.696Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/db/d3/9dcc0f5797f070ec8edf30fbadfb200e71d9db6b84d211e3b2085a7589a0/click-8.3.0-py3-none-any.whl", hash = "sha256:9b9f285302c6e3064f4330c05f05b81945b2a39544279343e6e7c5f27a9baddc", size = 107295, upload-time = "2025-09-18T17:32:22.42Z" },
+]
+
+[[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 = "cryptography"
+version = "46.0.5"
+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/60/04/ee2a9e8542e4fa2773b81771ff8349ff19cdd56b7258a0cc442639052edb/cryptography-46.0.5.tar.gz", hash = "sha256:abace499247268e3757271b2f1e244b36b06f8515cf27c4d49468fc9eb16e93d", size = 750064, upload-time = "2026-02-10T19:18:38.255Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/81/b0bb27f2ba931a65409c6b8a8b358a7f03c0e46eceacddff55f7c84b1f3b/cryptography-46.0.5-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:351695ada9ea9618b3500b490ad54c739860883df6c1f555e088eaf25b1bbaad", size = 7176289, upload-time = "2026-02-10T19:17:08.274Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/9e/6b4397a3e3d15123de3b1806ef342522393d50736c13b20ec4c9ea6693a6/cryptography-46.0.5-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c18ff11e86df2e28854939acde2d003f7984f721eba450b56a200ad90eeb0e6b", size = 4275637, upload-time = "2026-02-10T19:17:10.53Z" },
+    { url = "https://files.pythonhosted.org/packages/63/e7/471ab61099a3920b0c77852ea3f0ea611c9702f651600397ac567848b897/cryptography-46.0.5-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d7e3d356b8cd4ea5aff04f129d5f66ebdc7b6f8eae802b93739ed520c47c79b", size = 4424742, upload-time = "2026-02-10T19:17:12.388Z" },
+    { url = "https://files.pythonhosted.org/packages/37/53/a18500f270342d66bf7e4d9f091114e31e5ee9e7375a5aba2e85a91e0044/cryptography-46.0.5-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:50bfb6925eff619c9c023b967d5b77a54e04256c4281b0e21336a130cd7fc263", size = 4277528, upload-time = "2026-02-10T19:17:13.853Z" },
+    { url = "https://files.pythonhosted.org/packages/22/29/c2e812ebc38c57b40e7c583895e73c8c5adb4d1e4a0cc4c5a4fdab2b1acc/cryptography-46.0.5-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:803812e111e75d1aa73690d2facc295eaefd4439be1023fefc4995eaea2af90d", size = 4947993, upload-time = "2026-02-10T19:17:15.618Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/e7/237155ae19a9023de7e30ec64e5d99a9431a567407ac21170a046d22a5a3/cryptography-46.0.5-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ee190460e2fbe447175cda91b88b84ae8322a104fc27766ad09428754a618ed", size = 4456855, upload-time = "2026-02-10T19:17:17.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/87/fc628a7ad85b81206738abbd213b07702bcbdada1dd43f72236ef3cffbb5/cryptography-46.0.5-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:f145bba11b878005c496e93e257c1e88f154d278d2638e6450d17e0f31e558d2", size = 3984635, upload-time = "2026-02-10T19:17:18.792Z" },
+    { url = "https://files.pythonhosted.org/packages/84/29/65b55622bde135aedf4565dc509d99b560ee4095e56989e815f8fd2aa910/cryptography-46.0.5-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e9251e3be159d1020c4030bd2e5f84d6a43fe54b6c19c12f51cde9542a2817b2", size = 4277038, upload-time = "2026-02-10T19:17:20.256Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/36/45e76c68d7311432741faf1fbf7fac8a196a0a735ca21f504c75d37e2558/cryptography-46.0.5-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:47fb8a66058b80e509c47118ef8a75d14c455e81ac369050f20ba0d23e77fee0", size = 4912181, upload-time = "2026-02-10T19:17:21.825Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/1a/c1ba8fead184d6e3d5afcf03d569acac5ad063f3ac9fb7258af158f7e378/cryptography-46.0.5-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4c3341037c136030cb46e4b1e17b7418ea4cbd9dd207e4a6f3b2b24e0d4ac731", size = 4456482, upload-time = "2026-02-10T19:17:25.133Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/e5/3fb22e37f66827ced3b902cf895e6a6bc1d095b5b26be26bd13c441fdf19/cryptography-46.0.5-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:890bcb4abd5a2d3f852196437129eb3667d62630333aacc13dfd470fad3aaa82", size = 4405497, upload-time = "2026-02-10T19:17:26.66Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/df/9d58bb32b1121a8a2f27383fabae4d63080c7ca60b9b5c88be742be04ee7/cryptography-46.0.5-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80a8d7bfdf38f87ca30a5391c0c9ce4ed2926918e017c29ddf643d0ed2778ea1", size = 4667819, upload-time = "2026-02-10T19:17:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/ed/325d2a490c5e94038cdb0117da9397ece1f11201f425c4e9c57fe5b9f08b/cryptography-46.0.5-cp311-abi3-win32.whl", hash = "sha256:60ee7e19e95104d4c03871d7d7dfb3d22ef8a9b9c6778c94e1c8fcc8365afd48", size = 3028230, upload-time = "2026-02-10T19:17:30.518Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/5a/ac0f49e48063ab4255d9e3b79f5def51697fce1a95ea1370f03dc9db76f6/cryptography-46.0.5-cp311-abi3-win_amd64.whl", hash = "sha256:38946c54b16c885c72c4f59846be9743d699eee2b69b6988e0a00a01f46a61a4", size = 3480909, upload-time = "2026-02-10T19:17:32.083Z" },
+    { url = "https://files.pythonhosted.org/packages/00/13/3d278bfa7a15a96b9dc22db5a12ad1e48a9eb3d40e1827ef66a5df75d0d0/cryptography-46.0.5-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:94a76daa32eb78d61339aff7952ea819b1734b46f73646a07decb40e5b3448e2", size = 7119287, upload-time = "2026-02-10T19:17:33.801Z" },
+    { url = "https://files.pythonhosted.org/packages/67/c8/581a6702e14f0898a0848105cbefd20c058099e2c2d22ef4e476dfec75d7/cryptography-46.0.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5be7bf2fb40769e05739dd0046e7b26f9d4670badc7b032d6ce4db64dddc0678", size = 4265728, upload-time = "2026-02-10T19:17:35.569Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/4a/ba1a65ce8fc65435e5a849558379896c957870dd64fecea97b1ad5f46a37/cryptography-46.0.5-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fe346b143ff9685e40192a4960938545c699054ba11d4f9029f94751e3f71d87", size = 4408287, upload-time = "2026-02-10T19:17:36.938Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/67/8ffdbf7b65ed1ac224d1c2df3943553766914a8ca718747ee3871da6107e/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:c69fd885df7d089548a42d5ec05be26050ebcd2283d89b3d30676eb32ff87dee", size = 4270291, upload-time = "2026-02-10T19:17:38.748Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/e5/f52377ee93bc2f2bba55a41a886fd208c15276ffbd2569f2ddc89d50e2c5/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:8293f3dea7fc929ef7240796ba231413afa7b68ce38fd21da2995549f5961981", size = 4927539, upload-time = "2026-02-10T19:17:40.241Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/02/cfe39181b02419bbbbcf3abdd16c1c5c8541f03ca8bda240debc467d5a12/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:1abfdb89b41c3be0365328a410baa9df3ff8a9110fb75e7b52e66803ddabc9a9", size = 4442199, upload-time = "2026-02-10T19:17:41.789Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/96/2fcaeb4873e536cf71421a388a6c11b5bc846e986b2b069c79363dc1648e/cryptography-46.0.5-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:d66e421495fdb797610a08f43b05269e0a5ea7f5e652a89bfd5a7d3c1dee3648", size = 3960131, upload-time = "2026-02-10T19:17:43.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/d2/b27631f401ddd644e94c5cf33c9a4069f72011821cf3dc7309546b0642a0/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:4e817a8920bfbcff8940ecfd60f23d01836408242b30f1a708d93198393a80b4", size = 4270072, upload-time = "2026-02-10T19:17:45.481Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/a7/60d32b0370dae0b4ebe55ffa10e8599a2a59935b5ece1b9f06edb73abdeb/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:68f68d13f2e1cb95163fa3b4db4bf9a159a418f5f6e7242564fc75fcae667fd0", size = 4892170, upload-time = "2026-02-10T19:17:46.997Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b9/cf73ddf8ef1164330eb0b199a589103c363afa0cf794218c24d524a58eab/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:a3d1fae9863299076f05cb8a778c467578262fae09f9dc0ee9b12eb4268ce663", size = 4441741, upload-time = "2026-02-10T19:17:48.661Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/eb/eee00b28c84c726fe8fa0158c65afe312d9c3b78d9d01daf700f1f6e37ff/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c4143987a42a2397f2fc3b4d7e3a7d313fbe684f67ff443999e803dd75a76826", size = 4396728, upload-time = "2026-02-10T19:17:50.058Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f4/6bc1a9ed5aef7145045114b75b77c2a8261b4d38717bd8dea111a63c3442/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:7d731d4b107030987fd61a7f8ab512b25b53cef8f233a97379ede116f30eb67d", size = 4652001, upload-time = "2026-02-10T19:17:51.54Z" },
+    { url = "https://files.pythonhosted.org/packages/86/ef/5d00ef966ddd71ac2e6951d278884a84a40ffbd88948ef0e294b214ae9e4/cryptography-46.0.5-cp314-cp314t-win32.whl", hash = "sha256:c3bcce8521d785d510b2aad26ae2c966092b7daa8f45dd8f44734a104dc0bc1a", size = 3003637, upload-time = "2026-02-10T19:17:52.997Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/57/f3f4160123da6d098db78350fdfd9705057aad21de7388eacb2401dceab9/cryptography-46.0.5-cp314-cp314t-win_amd64.whl", hash = "sha256:4d8ae8659ab18c65ced284993c2265910f6c9e650189d4e3f68445ef82a810e4", size = 3469487, upload-time = "2026-02-10T19:17:54.549Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/fa/a66aa722105ad6a458bebd64086ca2b72cdd361fed31763d20390f6f1389/cryptography-46.0.5-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:4108d4c09fbbf2789d0c926eb4152ae1760d5a2d97612b92d508d96c861e4d31", size = 7170514, upload-time = "2026-02-10T19:17:56.267Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/04/c85bdeab78c8bc77b701bf0d9bdcf514c044e18a46dcff330df5448631b0/cryptography-46.0.5-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7d1f30a86d2757199cb2d56e48cce14deddf1f9c95f1ef1b64ee91ea43fe2e18", size = 4275349, upload-time = "2026-02-10T19:17:58.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/32/9b87132a2f91ee7f5223b091dc963055503e9b442c98fc0b8a5ca765fab0/cryptography-46.0.5-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:039917b0dc418bb9f6edce8a906572d69e74bd330b0b3fea4f79dab7f8ddd235", size = 4420667, upload-time = "2026-02-10T19:18:00.619Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/a6/a7cb7010bec4b7c5692ca6f024150371b295ee1c108bdc1c400e4c44562b/cryptography-46.0.5-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:ba2a27ff02f48193fc4daeadf8ad2590516fa3d0adeeb34336b96f7fa64c1e3a", size = 4276980, upload-time = "2026-02-10T19:18:02.379Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/7c/c4f45e0eeff9b91e3f12dbd0e165fcf2a38847288fcfd889deea99fb7b6d/cryptography-46.0.5-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:61aa400dce22cb001a98014f647dc21cda08f7915ceb95df0c9eaf84b4b6af76", size = 4939143, upload-time = "2026-02-10T19:18:03.964Z" },
+    { url = "https://files.pythonhosted.org/packages/37/19/e1b8f964a834eddb44fa1b9a9976f4e414cbb7aa62809b6760c8803d22d1/cryptography-46.0.5-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ce58ba46e1bc2aac4f7d9290223cead56743fa6ab94a5d53292ffaac6a91614", size = 4453674, upload-time = "2026-02-10T19:18:05.588Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ed/db15d3956f65264ca204625597c410d420e26530c4e2943e05a0d2f24d51/cryptography-46.0.5-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:420d0e909050490d04359e7fdb5ed7e667ca5c3c402b809ae2563d7e66a92229", size = 3978801, upload-time = "2026-02-10T19:18:07.167Z" },
+    { url = "https://files.pythonhosted.org/packages/41/e2/df40a31d82df0a70a0daf69791f91dbb70e47644c58581d654879b382d11/cryptography-46.0.5-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:582f5fcd2afa31622f317f80426a027f30dc792e9c80ffee87b993200ea115f1", size = 4276755, upload-time = "2026-02-10T19:18:09.813Z" },
+    { url = "https://files.pythonhosted.org/packages/33/45/726809d1176959f4a896b86907b98ff4391a8aa29c0aaaf9450a8a10630e/cryptography-46.0.5-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:bfd56bb4b37ed4f330b82402f6f435845a5f5648edf1ad497da51a8452d5d62d", size = 4901539, upload-time = "2026-02-10T19:18:11.263Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0f/a3076874e9c88ecb2ecc31382f6e7c21b428ede6f55aafa1aa272613e3cd/cryptography-46.0.5-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:a3d507bb6a513ca96ba84443226af944b0f7f47dcc9a399d110cd6146481d24c", size = 4452794, upload-time = "2026-02-10T19:18:12.914Z" },
+    { url = "https://files.pythonhosted.org/packages/02/ef/ffeb542d3683d24194a38f66ca17c0a4b8bf10631feef44a7ef64e631b1a/cryptography-46.0.5-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9f16fbdf4da055efb21c22d81b89f155f02ba420558db21288b3d0035bafd5f4", size = 4404160, upload-time = "2026-02-10T19:18:14.375Z" },
+    { url = "https://files.pythonhosted.org/packages/96/93/682d2b43c1d5f1406ed048f377c0fc9fc8f7b0447a478d5c65ab3d3a66eb/cryptography-46.0.5-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ced80795227d70549a411a4ab66e8ce307899fad2220ce5ab2f296e687eacde9", size = 4667123, upload-time = "2026-02-10T19:18:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/45/2d/9c5f2926cb5300a8eefc3f4f0b3f3df39db7f7ce40c8365444c49363cbda/cryptography-46.0.5-cp38-abi3-win32.whl", hash = "sha256:02f547fce831f5096c9a567fd41bc12ca8f11df260959ecc7c3202555cc47a72", size = 3010220, upload-time = "2026-02-10T19:18:17.361Z" },
+    { url = "https://files.pythonhosted.org/packages/48/ef/0c2f4a8e31018a986949d34a01115dd057bf536905dca38897bacd21fac3/cryptography-46.0.5-cp38-abi3-win_amd64.whl", hash = "sha256:556e106ee01aa13484ce9b0239bca667be5004efb0aabbed28d353df86445595", size = 3467050, upload-time = "2026-02-10T19:18:18.899Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/dd/2d9fdb07cebdf3d51179730afb7d5e576153c6744c3ff8fded23030c204e/cryptography-46.0.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:3b4995dc971c9fb83c25aa44cf45f02ba86f71ee600d81091c2f0cbae116b06c", size = 3476964, upload-time = "2026-02-10T19:18:20.687Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/6f/6cc6cc9955caa6eaf83660b0da2b077c7fe8ff9950a3c5e45d605038d439/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:bc84e875994c3b445871ea7181d424588171efec3e185dced958dad9e001950a", size = 4218321, upload-time = "2026-02-10T19:18:22.349Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/5d/c4da701939eeee699566a6c1367427ab91a8b7088cc2328c09dbee940415/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:2ae6971afd6246710480e3f15824ed3029a60fc16991db250034efd0b9fb4356", size = 4381786, upload-time = "2026-02-10T19:18:24.529Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/97/a538654732974a94ff96c1db621fa464f455c02d4bb7d2652f4edc21d600/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:d861ee9e76ace6cf36a6a89b959ec08e7bc2493ee39d07ffe5acb23ef46d27da", size = 4217990, upload-time = "2026-02-10T19:18:25.957Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/11/7e500d2dd3ba891197b9efd2da5454b74336d64a7cc419aa7327ab74e5f6/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:2b7a67c9cd56372f3249b39699f2ad479f6991e62ea15800973b956f4b73e257", size = 4381252, upload-time = "2026-02-10T19:18:27.496Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/58/6b3d24e6b9bc474a2dcdee65dfd1f008867015408a271562e4b690561a4d/cryptography-46.0.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:8456928655f856c6e1533ff59d5be76578a7157224dbd9ce6872f25055ab9ab7", size = 3407605, upload-time = "2026-02-10T19:18:29.233Z" },
+]
+
+[[package]]
+name = "cyclopts"
+version = "4.2.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/8a/51/a67b17fac2530d22216a335bd10f48631412dd824013ea559ec236668f76/cyclopts-4.2.1.tar.gz", hash = "sha256:49bb4c35644e7a9658f706ade4cf1a9958834b2dca4425e2fafecf8a0537fac7", size = 148693, upload-time = "2025-10-31T14:30:58.681Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4d/1d/2b313e157c9c7bba319e42f464d15073d32a81ac4827bdc5b7de38832b3e/cyclopts-4.2.1-py3-none-any.whl", hash = "sha256:17a801faa814988b0307385ef8aaeb6b14b4d64473015a2d66bde9ea13f14d9c", size = 184333, upload-time = "2025-10-31T14:30:57.581Z" },
+]
+
+[[package]]
+name = "dirty-equals"
+version = "0.10.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/30/69/f8a63f97166565dbf01e6a3fdf4665313719a6781125f105e4ffde82c5cd/dirty_equals-0.10.0.tar.gz", hash = "sha256:623d7a07c5ba437f1a834c6246d1e3eb97238ca70331c61a499d9aabd757b899", size = 125778, upload-time = "2025-09-19T16:05:31.371Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/87/0fc6e51f9db3a3b3de88fb0c9cf6414d4572d565f4ba4d166023cbd4354d/dirty_equals-0.10.0-py3-none-any.whl", hash = "sha256:bbf4a4eaafd56e371dafe2edf2265315ebd71a441b142ed801511aa33e4c3438", size = 28014, upload-time = "2025-09-19T16:05:29.953Z" },
+]
+
+[[package]]
+name = "diskcache"
+version = "5.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3f/21/1c1ffc1a039ddcc459db43cc108658f32c57d271d7289a2794e401d0fdb6/diskcache-5.6.3.tar.gz", hash = "sha256:2c3a3fa2743d8535d832ec61c2054a1641f41775aa7c556758a109941e33e4fc", size = 67916, upload-time = "2023-08-31T06:12:00.316Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3f/27/4570e78fc0bf5ea0ca45eb1de3818a23787af9b390c0b0a0033a1b8236f9/diskcache-5.6.3-py3-none-any.whl", hash = "sha256:5e31b2d5fbad117cc363ebaf6b689474db18a1f6438bc82358b024abd4c2ca19", size = 45550, upload-time = "2023-08-31T06:11:58.822Z" },
+]
+
+[[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.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d9/02/111134bfeb6e6c7ac4c74594e39a59f6c0195dc4846afbeac3cba60f1927/docutils-0.22.3.tar.gz", hash = "sha256:21486ae730e4ca9f622677b1412b879af1791efcfba517e4c6f60be543fc8cdd", size = 2290153, upload-time = "2025-11-06T02:35:55.655Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/11/a8/c6a4b901d17399c77cd81fb001ce8961e9f5e04d3daf27e8925cb012e163/docutils-0.22.3-py3-none-any.whl", hash = "sha256:bd772e4aca73aff037958d44f2be5229ded4c09927fcf8690c577b66234d6ceb", size = 633032, upload-time = "2025-11-06T02:35:52.391Z" },
+]
+
+[[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.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/36/f4/c6e662dade71f56cd2f3735141b265c3c79293c109549c1e6933b0651ffc/exceptiongroup-1.3.0-py3-none-any.whl", hash = "sha256:4d111e6e0c13d0644cad6ddaa7ed0261a0b36971f6d23e7ec9b4b9097da78a10", size = 16674, upload-time = "2025-05-10T17:42:49.33Z" },
+]
+
+[[package]]
+name = "fakeredis"
+version = "2.33.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "redis" },
+    { name = "sortedcontainers" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5f/f9/57464119936414d60697fcbd32f38909bb5688b616ae13de6e98384433e0/fakeredis-2.33.0.tar.gz", hash = "sha256:d7bc9a69d21df108a6451bbffee23b3eba432c21a654afc7ff2d295428ec5770", size = 175187, upload-time = "2025-12-16T19:45:52.269Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6e/78/a850fed8aeef96d4a99043c90b818b2ed5419cd5b24a4049fd7cfb9f1471/fakeredis-2.33.0-py3-none-any.whl", hash = "sha256:de535f3f9ccde1c56672ab2fdd6a8efbc4f2619fc2f1acc87b8737177d71c965", size = 119605, upload-time = "2025-12-16T19:45:51.08Z" },
+]
+
+[package.optional-dependencies]
+lua = [
+    { name = "lupa" },
+]
+
+[[package]]
+name = "fastmcp"
+version = "2.14.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "authlib" },
+    { name = "cyclopts" },
+    { name = "exceptiongroup" },
+    { name = "httpx" },
+    { name = "jsonschema-path" },
+    { name = "mcp" },
+    { name = "openapi-pydantic" },
+    { name = "platformdirs" },
+    { name = "py-key-value-aio", extra = ["disk", "keyring", "memory"] },
+    { name = "pydantic", extra = ["email"] },
+    { name = "pydocket" },
+    { name = "pyperclip" },
+    { name = "python-dotenv" },
+    { name = "rich" },
+    { name = "uvicorn" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/35/50/9bb042a2d290ccadb35db3580ac507f192e1a39c489eb8faa167cd5e3b57/fastmcp-2.14.0.tar.gz", hash = "sha256:c1f487b36a3e4b043dbf3330e588830047df2e06f8ef0920d62dfb34d0905727", size = 8232562, upload-time = "2025-12-11T23:04:27.134Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/73/b5656172a6beb2eacec95f04403ddea1928e4b22066700fd14780f8f45d1/fastmcp-2.14.0-py3-none-any.whl", hash = "sha256:7b374c0bcaf1ef1ef46b9255ea84c607f354291eaf647ff56a47c69f5ec0c204", size = 398965, upload-time = "2025-12-11T23:04:25.587Z" },
+]
+
+[[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.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+]
+
+[[package]]
+name = "importlib-metadata"
+version = "8.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/76/66/650a33bd90f786193e4de4b3ad86ea60b53c89b669a5c7be931fac31cdb0/importlib_metadata-8.7.0.tar.gz", hash = "sha256:d13b81ad223b890aa16c5471f2ac3056cf76c5f10f82d6f9292f0b415f389000", size = 56641, upload-time = "2025-04-27T15:29:01.736Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/b0/36bd937216ec521246249be3bf9855081de4c5e06a0c9b4219dbeda50373/importlib_metadata-8.7.0-py3-none-any.whl", hash = "sha256:e5dd1551894c77868a30651cef00984d50e1002d06942a7101d34870c5f02afd", size = 27656, upload-time = "2025-04-27T15:29:00.214Z" },
+]
+
+[[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.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-tarfile", marker = "python_full_version < '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/df/ad/f3777b81bf0b6e7bc7514a1656d3e637b2e8e15fab2ce3235730b3e7a4e6/jaraco_context-6.0.1.tar.gz", hash = "sha256:9bae4ea555cf0b14938dc0aee7c9f32ed303aa20a3b73e7dc80111628792d1b3", size = 13912, upload-time = "2024-08-20T03:39:27.358Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ff/db/0c52c4cf5e4bd9f5d7135ec7669a3a767af21b3a308e1ed3674881e52b62/jaraco.context-6.0.1-py3-none-any.whl", hash = "sha256:f797fc481b490edb305122c9181830a3a5b76d84ef6d1aef2fb9b47ab956f9e4", size = 6825, upload-time = "2024-08-20T03:39:25.966Z" },
+]
+
+[[package]]
+name = "jaraco-functools"
+version = "4.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "more-itertools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f7/ed/1aa2d585304ec07262e1a83a9889880701079dde796ac7b1d1826f40c63d/jaraco_functools-4.3.0.tar.gz", hash = "sha256:cfd13ad0dd2c47a3600b439ef72d8615d482cedcff1632930d6f28924d92f294", size = 19755, upload-time = "2025-08-18T20:05:09.91Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b4/09/726f168acad366b11e420df31bf1c702a54d373a83f968d94141a8c3fde0/jaraco_functools-4.3.0-py3-none-any.whl", hash = "sha256:227ff8ed6f7b8f62c56deff101545fa7543cf2c8e7b82a7c2116e672f29c26e8", size = 10408, upload-time = "2025-08-18T20:05:08.69Z" },
+]
+
+[[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 = "jsonschema"
+version = "4.25.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/74/69/f7185de793a29082a9f3c7728268ffb31cb5095131a9c139a74078e27336/jsonschema-4.25.1.tar.gz", hash = "sha256:e4a9655ce0da0c0b67a085847e00a3a51449e1157f4f75e9fb5aa545e122eb85", size = 357342, upload-time = "2025-08-18T17:03:50.038Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bf/9c/8c95d856233c1f82500c2450b8c68576b4cf1c871db3afac5c34ff84e6fd/jsonschema-4.25.1-py3-none-any.whl", hash = "sha256:3fba0169e345c7175110351d456342c364814cfcf3b964ba4587f22915230a63", size = 90040, upload-time = "2025-08-18T17:03:48.373Z" },
+]
+
+[[package]]
+name = "jsonschema-path"
+version = "0.3.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6e/45/41ebc679c2a4fced6a722f624c18d658dee42612b83ea24c1caf7c0eb3a8/jsonschema_path-0.3.4.tar.gz", hash = "sha256:8365356039f16cc65fddffafda5f58766e34bebab7d6d105616ab52bc4297001", size = 11159, upload-time = "2025-01-24T14:33:16.547Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/58/3485da8cb93d2f393bce453adeef16896751f14ba3e2024bc21dc9597646/jsonschema_path-0.3.4-py3-none-any.whl", hash = "sha256:f502191fdc2b22050f9a81c9237be9d27145b9001c55842bece5e94e382e52f8", size = 14810, upload-time = "2025-01-24T14:33:14.652Z" },
+]
+
+[[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.6.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/70/09/d904a6e96f76ff214be59e7aa6ef7190008f52a0ab6689760a98de0bf37d/keyring-25.6.0.tar.gz", hash = "sha256:0b39998aa941431eb3d9b0d4b2460bc773b9df6fed7621c2dfb291a7e0187a66", size = 62750, upload-time = "2024-12-25T15:26:45.782Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d3/32/da7f44bcb1105d3e88a0b74ebdca50c59121d2ddf71c9e34ba47df7f3a56/keyring-25.6.0-py3-none-any.whl", hash = "sha256:552a3f7af126ece7ed5c89753650eec89c7eaae8617d0aa4d9ad2b75111266bd", size = 39085, upload-time = "2024-12-25T15:26:44.377Z" },
+]
+
+[[package]]
+name = "lupa"
+version = "2.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b8/1c/191c3e6ec6502e3dbe25a53e27f69a5daeac3e56de1f73c0138224171ead/lupa-2.6.tar.gz", hash = "sha256:9a770a6e89576be3447668d7ced312cd6fd41d3c13c2462c9dc2c2ab570e45d9", size = 7240282, upload-time = "2025-10-24T07:20:29.738Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a1/15/713cab5d0dfa4858f83b99b3e0329072df33dc14fc3ebbaa017e0f9755c4/lupa-2.6-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6b3dabda836317e63c5ad052826e156610f356a04b3003dfa0dbe66b5d54d671", size = 954828, upload-time = "2025-10-24T07:17:15.726Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/71/704740cbc6e587dd6cc8dabf2f04820ac6a671784e57cc3c29db795476db/lupa-2.6-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:8726d1c123bbe9fbb974ce29825e94121824e66003038ff4532c14cc2ed0c51c", size = 1919259, upload-time = "2025-10-24T07:17:18.586Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/18/f248341c423c5d48837e35584c6c3eb4acab7e722b6057d7b3e28e42dae8/lupa-2.6-cp310-cp310-macosx_11_0_x86_64.whl", hash = "sha256:f4e159e7d814171199b246f9235ca8961f6461ea8c1165ab428afa13c9289a94", size = 984998, upload-time = "2025-10-24T07:17:20.428Z" },
+    { url = "https://files.pythonhosted.org/packages/44/1e/8a4bd471e018aad76bcb9455d298c2c96d82eced20f2ae8fcec8cd800948/lupa-2.6-cp310-cp310-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:202160e80dbfddfb79316692a563d843b767e0f6787bbd1c455f9d54052efa6c", size = 1174871, upload-time = "2025-10-24T07:17:22.755Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/5c/3a3f23fd6a91b0986eea1ceaf82ad3f9b958fe3515a9981fb9c4eb046c8b/lupa-2.6-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5deede7c5b36ab64f869dae4831720428b67955b0bb186c8349cf6ea121c852b", size = 1057471, upload-time = "2025-10-24T07:17:24.908Z" },
+    { url = "https://files.pythonhosted.org/packages/45/ac/01be1fed778fb0c8f46ee8cbe344e4d782f6806fac12717f08af87aa4355/lupa-2.6-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:86f04901f920bbf7c0cac56807dc9597e42347123e6f1f3ca920f15f54188ce5", size = 2100592, upload-time = "2025-10-24T07:17:27.089Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/6c/1a05bb873e30830f8574e10cd0b4cdbc72e9dbad2a09e25810b5e3b1f75d/lupa-2.6-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:6deef8f851d6afb965c84849aa5b8c38856942df54597a811ce0369ced678610", size = 1081396, upload-time = "2025-10-24T07:17:29.064Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/c2/a19dd80d6dc98b39bbf8135b8198e38aa7ca3360b720eac68d1d7e9286b5/lupa-2.6-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:21f2b5549681c2a13b1170a26159d30875d367d28f0247b81ca347222c755038", size = 1192007, upload-time = "2025-10-24T07:17:31.362Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/43/e1b297225c827f55752e46fdbfb021c8982081b0f24490e42776ea69ae3b/lupa-2.6-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:66eea57630eab5e6f49fdc5d7811c0a2a41f2011be4ea56a087ea76112011eb7", size = 2196661, upload-time = "2025-10-24T07:17:33.484Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/8f/2272d429a7fa9dc8dbd6e9c5c9073a03af6007eb22a4c78829fec6a34b80/lupa-2.6-cp310-cp310-win32.whl", hash = "sha256:60a403de8cab262a4fe813085dd77010effa6e2eb1886db2181df803140533b1", size = 1412738, upload-time = "2025-10-24T07:17:35.11Z" },
+    { url = "https://files.pythonhosted.org/packages/35/2a/1708911271dd49ad87b4b373b5a4b0e0a0516d3d2af7b76355946c7ee171/lupa-2.6-cp310-cp310-win_amd64.whl", hash = "sha256:e4656a39d93dfa947cf3db56dc16c7916cb0cc8024acd3a952071263f675df64", size = 1656898, upload-time = "2025-10-24T07:17:36.949Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/29/1f66907c1ebf1881735afa695e646762c674f00738ebf66d795d59fc0665/lupa-2.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6d988c0f9331b9f2a5a55186701a25444ab10a1432a1021ee58011499ecbbdd5", size = 962875, upload-time = "2025-10-24T07:17:39.107Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/67/4a748604be360eb9c1c215f6a0da921cd1a2b44b2c5951aae6fb83019d3a/lupa-2.6-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:ebe1bbf48259382c72a6fe363dea61a0fd6fe19eab95e2ae881e20f3654587bf", size = 1935390, upload-time = "2025-10-24T07:17:41.427Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/0c/8ef9ee933a350428b7bdb8335a37ef170ab0bb008bbf9ca8f4f4310116b6/lupa-2.6-cp311-cp311-macosx_11_0_x86_64.whl", hash = "sha256:a8fcee258487cf77cdd41560046843bb38c2e18989cd19671dd1e2596f798306", size = 992193, upload-time = "2025-10-24T07:17:43.231Z" },
+    { url = "https://files.pythonhosted.org/packages/65/46/e6c7facebdb438db8a65ed247e56908818389c1a5abbf6a36aab14f1057d/lupa-2.6-cp311-cp311-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:561a8e3be800827884e767a694727ed8482d066e0d6edfcbf423b05e63b05535", size = 1165844, upload-time = "2025-10-24T07:17:45.437Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/26/9f1154c6c95f175ccbf96aa96c8f569c87f64f463b32473e839137601a8b/lupa-2.6-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:af880a62d47991cae78b8e9905c008cbfdc4a3a9723a66310c2634fc7644578c", size = 1048069, upload-time = "2025-10-24T07:17:47.181Z" },
+    { url = "https://files.pythonhosted.org/packages/68/67/2cc52ab73d6af81612b2ea24c870d3fa398443af8e2875e5befe142398b1/lupa-2.6-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:80b22923aa4023c86c0097b235615f89d469a0c4eee0489699c494d3367c4c85", size = 2079079, upload-time = "2025-10-24T07:17:49.755Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/dc/f843f09bbf325f6e5ee61730cf6c3409fc78c010d968c7c78acba3019ca7/lupa-2.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:153d2cc6b643f7efb9cfc0c6bb55ec784d5bac1a3660cfc5b958a7b8f38f4a75", size = 1071428, upload-time = "2025-10-24T07:17:51.991Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/60/37533a8d85bf004697449acb97ecdacea851acad28f2ad3803662487dd2a/lupa-2.6-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:3fa8777e16f3ded50b72967dc17e23f5a08e4f1e2c9456aff2ebdb57f5b2869f", size = 1181756, upload-time = "2025-10-24T07:17:53.752Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/f2/cf29b20dbb4927b6a3d27c339ac5d73e74306ecc28c8e2c900b2794142ba/lupa-2.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:8dbdcbe818c02a2f56f5ab5ce2de374dab03e84b25266cfbaef237829bc09b3f", size = 2175687, upload-time = "2025-10-24T07:17:56.228Z" },
+    { url = "https://files.pythonhosted.org/packages/94/7c/050e02f80c7131b63db1474bff511e63c545b5a8636a24cbef3fc4da20b6/lupa-2.6-cp311-cp311-win32.whl", hash = "sha256:defaf188fde8f7a1e5ce3a5e6d945e533b8b8d547c11e43b96c9b7fe527f56dc", size = 1412592, upload-time = "2025-10-24T07:17:59.062Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/9a/6f2af98aa5d771cea661f66c8eb8f53772ec1ab1dfbce24126cfcd189436/lupa-2.6-cp311-cp311-win_amd64.whl", hash = "sha256:9505ae600b5c14f3e17e70f87f88d333717f60411faca1ddc6f3e61dce85fa9e", size = 1669194, upload-time = "2025-10-24T07:18:01.647Z" },
+    { url = "https://files.pythonhosted.org/packages/94/86/ce243390535c39d53ea17ccf0240815e6e457e413e40428a658ea4ee4b8d/lupa-2.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:47ce718817ef1cc0c40d87c3d5ae56a800d61af00fbc0fad1ca9be12df2f3b56", size = 951707, upload-time = "2025-10-24T07:18:03.884Z" },
+    { url = "https://files.pythonhosted.org/packages/86/85/cedea5e6cbeb54396fdcc55f6b741696f3f036d23cfaf986d50d680446da/lupa-2.6-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:7aba985b15b101495aa4b07112cdc08baa0c545390d560ad5cfde2e9e34f4d58", size = 1916703, upload-time = "2025-10-24T07:18:05.6Z" },
+    { url = "https://files.pythonhosted.org/packages/24/be/3d6b5f9a8588c01a4d88129284c726017b2089f3a3fd3ba8bd977292fea0/lupa-2.6-cp312-cp312-macosx_11_0_x86_64.whl", hash = "sha256:b766f62f95b2739f2248977d29b0722e589dcf4f0ccfa827ccbd29f0148bd2e5", size = 985152, upload-time = "2025-10-24T07:18:08.561Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/23/9f9a05beee5d5dce9deca4cb07c91c40a90541fc0a8e09db4ee670da550f/lupa-2.6-cp312-cp312-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:00a934c23331f94cb51760097ebfab14b005d55a6b30a2b480e3c53dd2fa290d", size = 1159599, upload-time = "2025-10-24T07:18:10.346Z" },
+    { url = "https://files.pythonhosted.org/packages/40/4e/e7c0583083db9d7f1fd023800a9767d8e4391e8330d56c2373d890ac971b/lupa-2.6-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:21de9f38bd475303e34a042b7081aabdf50bd9bafd36ce4faea2f90fd9f15c31", size = 1038686, upload-time = "2025-10-24T07:18:12.112Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/9f/5a4f7d959d4feba5e203ff0c31889e74d1ca3153122be4a46dca7d92bf7c/lupa-2.6-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cf3bda96d3fc41237e964a69c23647d50d4e28421111360274d4799832c560e9", size = 2071956, upload-time = "2025-10-24T07:18:14.572Z" },
+    { url = "https://files.pythonhosted.org/packages/92/34/2f4f13ca65d01169b1720176aedc4af17bc19ee834598c7292db232cb6dc/lupa-2.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:5a76ead245da54801a81053794aa3975f213221f6542d14ec4b859ee2e7e0323", size = 1057199, upload-time = "2025-10-24T07:18:16.379Z" },
+    { url = "https://files.pythonhosted.org/packages/35/2a/5f7d2eebec6993b0dcd428e0184ad71afb06a45ba13e717f6501bfed1da3/lupa-2.6-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8dd0861741caa20886ddbda0a121d8e52fb9b5bb153d82fa9bba796962bf30e8", size = 1173693, upload-time = "2025-10-24T07:18:18.153Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/29/089b4d2f8e34417349af3904bb40bec40b65c8731f45e3fd8d497ca573e5/lupa-2.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:239e63948b0b23023f81d9a19a395e768ed3da6a299f84e7963b8f813f6e3f9c", size = 2164394, upload-time = "2025-10-24T07:18:20.403Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/1b/79c17b23c921f81468a111cad843b076a17ef4b684c4a8dff32a7969c3f0/lupa-2.6-cp312-cp312-win32.whl", hash = "sha256:325894e1099499e7a6f9c351147661a2011887603c71086d36fe0f964d52d1ce", size = 1420647, upload-time = "2025-10-24T07:18:23.368Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/15/5121e68aad3584e26e1425a5c9a79cd898f8a152292059e128c206ee817c/lupa-2.6-cp312-cp312-win_amd64.whl", hash = "sha256:c735a1ce8ee60edb0fe71d665f1e6b7c55c6021f1d340eb8c865952c602cd36f", size = 1688529, upload-time = "2025-10-24T07:18:25.523Z" },
+    { url = "https://files.pythonhosted.org/packages/28/1d/21176b682ca5469001199d8b95fa1737e29957a3d185186e7a8b55345f2e/lupa-2.6-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:663a6e58a0f60e7d212017d6678639ac8df0119bc13c2145029dcba084391310", size = 947232, upload-time = "2025-10-24T07:18:27.878Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/4c/d327befb684660ca13cf79cd1f1d604331808f9f1b6fb6bf57832f8edf80/lupa-2.6-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:d1f5afda5c20b1f3217a80e9bc1b77037f8a6eb11612fd3ada19065303c8f380", size = 1908625, upload-time = "2025-10-24T07:18:29.944Z" },
+    { url = "https://files.pythonhosted.org/packages/66/8e/ad22b0a19454dfd08662237a84c792d6d420d36b061f239e084f29d1a4f3/lupa-2.6-cp313-cp313-macosx_11_0_x86_64.whl", hash = "sha256:26f2b3c085fe76e9119e48c1013c1cccdc1f51585d456858290475aa38e7089e", size = 981057, upload-time = "2025-10-24T07:18:31.553Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/48/74859073ab276bd0566c719f9ca0108b0cfc1956ca0d68678d117d47d155/lupa-2.6-cp313-cp313-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:60d2f902c7b96fb8ab98493dcff315e7bb4d0b44dc9dd76eb37de575025d5685", size = 1156227, upload-time = "2025-10-24T07:18:33.981Z" },
+    { url = "https://files.pythonhosted.org/packages/09/6c/0e9ded061916877253c2266074060eb71ed99fb21d73c8c114a76725bce2/lupa-2.6-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a02d25dee3a3250967c36590128d9220ae02f2eda166a24279da0b481519cbff", size = 1035752, upload-time = "2025-10-24T07:18:36.32Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/ef/f8c32e454ef9f3fe909f6c7d57a39f950996c37a3deb7b391fec7903dab7/lupa-2.6-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6eae1ee16b886b8914ff292dbefbf2f48abfbdee94b33a88d1d5475e02423203", size = 2069009, upload-time = "2025-10-24T07:18:38.072Z" },
+    { url = "https://files.pythonhosted.org/packages/53/dc/15b80c226a5225815a890ee1c11f07968e0aba7a852df41e8ae6fe285063/lupa-2.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:b0edd5073a4ee74ab36f74fe61450148e6044f3952b8d21248581f3c5d1a58be", size = 1056301, upload-time = "2025-10-24T07:18:40.165Z" },
+    { url = "https://files.pythonhosted.org/packages/31/14/2086c1425c985acfb30997a67e90c39457122df41324d3c179d6ee2292c6/lupa-2.6-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:0c53ee9f22a8a17e7d4266ad48e86f43771951797042dd51d1494aaa4f5f3f0a", size = 1170673, upload-time = "2025-10-24T07:18:42.426Z" },
+    { url = "https://files.pythonhosted.org/packages/10/e5/b216c054cf86576c0191bf9a9f05de6f7e8e07164897d95eea0078dca9b2/lupa-2.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:de7c0f157a9064a400d828789191a96da7f4ce889969a588b87ec80de9b14772", size = 2162227, upload-time = "2025-10-24T07:18:46.112Z" },
+    { url = "https://files.pythonhosted.org/packages/59/2f/33ecb5bedf4f3bc297ceacb7f016ff951331d352f58e7e791589609ea306/lupa-2.6-cp313-cp313-win32.whl", hash = "sha256:ee9523941ae0a87b5b703417720c5d78f72d2f5bc23883a2ea80a949a3ed9e75", size = 1419558, upload-time = "2025-10-24T07:18:48.371Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/b4/55e885834c847ea610e111d87b9ed4768f0afdaeebc00cd46810f25029f6/lupa-2.6-cp313-cp313-win_amd64.whl", hash = "sha256:b1335a5835b0a25ebdbc75cf0bda195e54d133e4d994877ef025e218c2e59db9", size = 1683424, upload-time = "2025-10-24T07:18:50.976Z" },
+    { url = "https://files.pythonhosted.org/packages/66/9d/d9427394e54d22a35d1139ef12e845fd700d4872a67a34db32516170b746/lupa-2.6-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:dcb6d0a3264873e1653bc188499f48c1fb4b41a779e315eba45256cfe7bc33c1", size = 953818, upload-time = "2025-10-24T07:18:53.378Z" },
+    { url = "https://files.pythonhosted.org/packages/10/41/27bbe81953fb2f9ecfced5d9c99f85b37964cfaf6aa8453bb11283983721/lupa-2.6-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:a37e01f2128f8c36106726cb9d360bac087d58c54b4522b033cc5691c584db18", size = 1915850, upload-time = "2025-10-24T07:18:55.259Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/98/f9ff60db84a75ba8725506bbf448fb085bc77868a021998ed2a66d920568/lupa-2.6-cp314-cp314-macosx_11_0_x86_64.whl", hash = "sha256:458bd7e9ff3c150b245b0fcfbb9bd2593d1152ea7f0a7b91c1d185846da033fe", size = 982344, upload-time = "2025-10-24T07:18:57.05Z" },
+    { url = "https://files.pythonhosted.org/packages/41/f7/f39e0f1c055c3b887d86b404aaf0ca197b5edfd235a8b81b45b25bac7fc3/lupa-2.6-cp314-cp314-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:052ee82cac5206a02df77119c325339acbc09f5ce66967f66a2e12a0f3211cad", size = 1156543, upload-time = "2025-10-24T07:18:59.251Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/9c/59e6cffa0d672d662ae17bd7ac8ecd2c89c9449dee499e3eb13ca9cd10d9/lupa-2.6-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96594eca3c87dd07938009e95e591e43d554c1dbd0385be03c100367141db5a8", size = 1047974, upload-time = "2025-10-24T07:19:01.449Z" },
+    { url = "https://files.pythonhosted.org/packages/23/c6/a04e9cef7c052717fcb28fb63b3824802488f688391895b618e39be0f684/lupa-2.6-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e8faddd9d198688c8884091173a088a8e920ecc96cda2ffed576a23574c4b3f6", size = 2073458, upload-time = "2025-10-24T07:19:03.369Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/10/824173d10f38b51fc77785228f01411b6ca28826ce27404c7c912e0e442c/lupa-2.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:daebb3a6b58095c917e76ba727ab37b27477fb926957c825205fbda431552134", size = 1067683, upload-time = "2025-10-24T07:19:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/dc/9692fbcf3c924d9c4ece2d8d2f724451ac2e09af0bd2a782db1cef34e799/lupa-2.6-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:f3154e68972befe0f81564e37d8142b5d5d79931a18309226a04ec92487d4ea3", size = 1171892, upload-time = "2025-10-24T07:19:08.544Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ff/e318b628d4643c278c96ab3ddea07fc36b075a57383c837f5b11e537ba9d/lupa-2.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e4dadf77b9fedc0bfa53417cc28dc2278a26d4cbd95c29f8927ad4d8fe0a7ef9", size = 2166641, upload-time = "2025-10-24T07:19:10.485Z" },
+    { url = "https://files.pythonhosted.org/packages/12/f7/a6f9ec2806cf2d50826980cdb4b3cffc7691dc6f95e13cc728846d5cb793/lupa-2.6-cp314-cp314-win32.whl", hash = "sha256:cb34169c6fa3bab3e8ac58ca21b8a7102f6a94b6a5d08d3636312f3f02fafd8f", size = 1456857, upload-time = "2025-10-24T07:19:37.989Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/de/df71896f25bdc18360fdfa3b802cd7d57d7fede41a0e9724a4625b412c85/lupa-2.6-cp314-cp314-win_amd64.whl", hash = "sha256:b74f944fe46c421e25d0f8692aef1e842192f6f7f68034201382ac440ef9ea67", size = 1731191, upload-time = "2025-10-24T07:19:40.281Z" },
+    { url = "https://files.pythonhosted.org/packages/47/3c/a1f23b01c54669465f5f4c4083107d496fbe6fb45998771420e9aadcf145/lupa-2.6-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0e21b716408a21ab65723f8841cf7f2f37a844b7a965eeabb785e27fca4099cf", size = 999343, upload-time = "2025-10-24T07:19:12.519Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/6d/501994291cb640bfa2ccf7f554be4e6914afa21c4026bd01bff9ca8aac57/lupa-2.6-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:589db872a141bfff828340079bbdf3e9a31f2689f4ca0d88f97d9e8c2eae6142", size = 2000730, upload-time = "2025-10-24T07:19:14.869Z" },
+    { url = "https://files.pythonhosted.org/packages/53/a5/457ffb4f3f20469956c2d4c4842a7675e884efc895b2f23d126d23e126cc/lupa-2.6-cp314-cp314t-macosx_11_0_x86_64.whl", hash = "sha256:cd852a91a4a9d4dcbb9a58100f820a75a425703ec3e3f049055f60b8533b7953", size = 1021553, upload-time = "2025-10-24T07:19:17.123Z" },
+    { url = "https://files.pythonhosted.org/packages/51/6b/36bb5a5d0960f2a5c7c700e0819abb76fd9bf9c1d8a66e5106416d6e9b14/lupa-2.6-cp314-cp314t-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:0334753be028358922415ca97a64a3048e4ed155413fc4eaf87dd0a7e2752983", size = 1133275, upload-time = "2025-10-24T07:19:20.51Z" },
+    { url = "https://files.pythonhosted.org/packages/19/86/202ff4429f663013f37d2229f6176ca9f83678a50257d70f61a0a97281bf/lupa-2.6-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:661d895cd38c87658a34780fac54a690ec036ead743e41b74c3fb81a9e65a6aa", size = 1038441, upload-time = "2025-10-24T07:19:22.509Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/42/d8125f8e420714e5b52e9c08d88b5329dfb02dcca731b4f21faaee6cc5b5/lupa-2.6-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6aa58454ccc13878cc177c62529a2056be734da16369e451987ff92784994ca7", size = 2058324, upload-time = "2025-10-24T07:19:24.979Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/2c/47bf8b84059876e877a339717ddb595a4a7b0e8740bacae78ba527562e1c/lupa-2.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:1425017264e470c98022bba8cff5bd46d054a827f5df6b80274f9cc71dafd24f", size = 1060250, upload-time = "2025-10-24T07:19:27.262Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/06/d88add2b6406ca1bdec99d11a429222837ca6d03bea42ca75afa169a78cb/lupa-2.6-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:224af0532d216e3105f0a127410f12320f7c5f1aa0300bdf9646b8d9afb0048c", size = 1151126, upload-time = "2025-10-24T07:19:29.522Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/a0/89e6a024c3b4485b89ef86881c9d55e097e7cb0bdb74efb746f2fa6a9a76/lupa-2.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9abb98d5a8fd27c8285302e82199f0e56e463066f88f619d6594a450bf269d80", size = 2153693, upload-time = "2025-10-24T07:19:31.379Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/36/a0f007dc58fc1bbf51fb85dcc82fcb1f21b8c4261361de7dab0e3d8521ef/lupa-2.6-cp314-cp314t-win32.whl", hash = "sha256:1849efeba7a8f6fb8aa2c13790bee988fd242ae404bd459509640eeea3d1e291", size = 1590104, upload-time = "2025-10-24T07:19:33.514Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/5e/db903ce9cf82c48d6b91bf6d63ae4c8d0d17958939a4e04ba6b9f38b8643/lupa-2.6-cp314-cp314t-win_amd64.whl", hash = "sha256:fc1498d1a4fc028bc521c26d0fad4ca00ed63b952e32fb95949bda76a04bad52", size = 1913818, upload-time = "2025-10-24T07:19:36.039Z" },
+]
+
+[[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.25.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/d5/2d/649d80a0ecf6a1f82632ca44bec21c0461a9d9fc8934d38cb5b319f2db5e/mcp-1.25.0.tar.gz", hash = "sha256:56310361ebf0364e2d438e5b45f7668cbb124e158bb358333cd06e49e83a6802", size = 605387, upload-time = "2025-12-19T10:19:56.985Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e2/fc/6dc7659c2ae5ddf280477011f4213a74f806862856b796ef08f028e664bf/mcp-1.25.0-py3-none-any.whl", hash = "sha256:b37c38144a666add0862614cc79ec276e97d72aa8ca26d622818d4e278b9721a", size = 233076, upload-time = "2025-12-19T10:19:55.416Z" },
+]
+
+[[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.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/97/b9/3161be15bb8e3ad01be8be5a968a9237c3027c5be504362ff800fca3e442/opentelemetry_api-1.39.1.tar.gz", hash = "sha256:fbde8c80e1b937a2c61f20347e91c0c18a1940cecf012d62e65a7caf08967c9c", size = 65767, upload-time = "2025-12-11T13:32:39.182Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/df/d3f1ddf4bb4cb50ed9b1139cc7b1c54c34a1e7ce8fd1b9a37c0d1551a6bd/opentelemetry_api-1.39.1-py3-none-any.whl", hash = "sha256:2edd8463432a7f8443edce90972169b195e7d6a05500cd29e6d13898187c9950", size = 66356, upload-time = "2025-12-11T13:32:17.304Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-prometheus"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-sdk" },
+    { name = "prometheus-client" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/14/39/7dafa6fff210737267bed35a8855b6ac7399b9e582b8cf1f25f842517012/opentelemetry_exporter_prometheus-0.60b1.tar.gz", hash = "sha256:a4011b46906323f71724649d301b4dc188aaa068852e814f4df38cc76eac616b", size = 14976, upload-time = "2025-12-11T13:32:42.944Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/0d/4be6bf5477a3eb3d917d2f17d3c0b6720cd6cb97898444a61d43cc983f5c/opentelemetry_exporter_prometheus-0.60b1-py3-none-any.whl", hash = "sha256:49f59178de4f4590e3cef0b8b95cf6e071aae70e1f060566df5546fad773b8fd", size = 13019, upload-time = "2025-12-11T13:32:23.974Z" },
+]
+
+[[package]]
+name = "opentelemetry-instrumentation"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "packaging" },
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/41/0f/7e6b713ac117c1f5e4e3300748af699b9902a2e5e34c9cf443dde25a01fa/opentelemetry_instrumentation-0.60b1.tar.gz", hash = "sha256:57ddc7974c6eb35865af0426d1a17132b88b2ed8586897fee187fd5b8944bd6a", size = 31706, upload-time = "2025-12-11T13:36:42.515Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/77/d2/6788e83c5c86a2690101681aeef27eeb2a6bf22df52d3f263a22cee20915/opentelemetry_instrumentation-0.60b1-py3-none-any.whl", hash = "sha256:04480db952b48fb1ed0073f822f0ee26012b7be7c3eac1a3793122737c78632d", size = 33096, upload-time = "2025-12-11T13:35:33.067Z" },
+]
+
+[[package]]
+name = "opentelemetry-sdk"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/fb/c76080c9ba07e1e8235d24cdcc4d125ef7aa3edf23eb4e497c2e50889adc/opentelemetry_sdk-1.39.1.tar.gz", hash = "sha256:cf4d4563caf7bff906c9f7967e2be22d0d6b349b908be0d90fb21c8e9c995cc6", size = 171460, upload-time = "2025-12-11T13:32:49.369Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7c/98/e91cf858f203d86f4eccdf763dcf01cf03f1dae80c3750f7e635bfa206b6/opentelemetry_sdk-1.39.1-py3-none-any.whl", hash = "sha256:4d5482c478513ecb0a5d938dcc61394e647066e0cc2676bee9f3af3f3f45f01c", size = 132565, upload-time = "2025-12-11T13:32:35.069Z" },
+]
+
+[[package]]
+name = "opentelemetry-semantic-conventions"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/91/df/553f93ed38bf22f4b999d9be9c185adb558982214f33eae539d3b5cd0858/opentelemetry_semantic_conventions-0.60b1.tar.gz", hash = "sha256:87c228b5a0669b748c76d76df6c364c369c28f1c465e50f661e39737e84bc953", size = 137935, upload-time = "2025-12-11T13:32:50.487Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7a/5e/5958555e09635d09b75de3c4f8b9cae7335ca545d77392ffe7331534c402/opentelemetry_semantic_conventions-0.60b1-py3-none-any.whl", hash = "sha256:9fa8c8b0c110da289809292b0591220d3a7b53c1526a23021e977d68597893fb", size = 219982, upload-time = "2025-12-11T13:32:36.955Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "25.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a1/d4/1fc4078c65507b51b96ca8f8c3ba19e6a61c8253c72794544580a7b6c24d/packaging-25.0.tar.gz", hash = "sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f", size = 165727, upload-time = "2025-04-19T11:48:59.673Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
+]
+
+[[package]]
+name = "pathable"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/67/93/8f2c2075b180c12c1e9f6a09d1a985bc2036906b13dff1d8917e395f2048/pathable-0.4.4.tar.gz", hash = "sha256:6905a3cd17804edfac7875b5f6c9142a218c7caef78693c2dbbbfbac186d88b2", size = 8124, upload-time = "2025-01-10T18:43:13.247Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7d/eb/b6260b31b1a96386c0a880edebe26f89669098acea8e0318bff6adb378fd/pathable-0.4.4-py3-none-any.whl", hash = "sha256:5ae9e94793b6ef5a4cbe0a7ce9dbbefc1eec38df253763fd0aeeacf2762dbbc2", size = 9592, upload-time = "2025-01-10T18:43:11.88Z" },
+]
+
+[[package]]
+name = "pathvalidate"
+version = "3.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fa/2a/52a8da6fe965dea6192eb716b357558e103aea0a1e9a8352ad575a8406ca/pathvalidate-3.3.1.tar.gz", hash = "sha256:b18c07212bfead624345bb8e1d6141cdcf15a39736994ea0b94035ad2b1ba177", size = 63262, upload-time = "2025-06-15T09:07:20.736Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/70/875f4a23bfc4731703a5835487d0d2fb999031bd415e7d17c0ae615c18b7/pathvalidate-3.3.1-py3-none-any.whl", hash = "sha256:5263baab691f8e1af96092fa5137ee17df5bdfbd6cff1fcac4d6ef4bc2e1735f", size = 24305, upload-time = "2025-06-15T09:07:19.117Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/61/33/9611380c2bdb1225fdef633e2a9610622310fed35ab11dac9620972ee088/platformdirs-4.5.0.tar.gz", hash = "sha256:70ddccdd7c99fc5942e9fc25636a8b34d04c24b335100223152c2803e4063312", size = 21632, upload-time = "2025-10-08T17:44:48.791Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/73/cb/ac7874b3e5d58441674fb70742e6c374b28b0c7cb988d37d991cde47166c/platformdirs-4.5.0-py3-none-any.whl", hash = "sha256:e578a81bb873cbb89a41fcc904c7ef523cc18284b7e3b3ccf06aca1403b7ebd3", size = 18651, upload-time = "2025-10-08T17:44:47.223Z" },
+]
+
+[[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 = "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 = "py-key-value-aio"
+version = "0.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "py-key-value-shared" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/93/ce/3136b771dddf5ac905cc193b461eb67967cf3979688c6696e1f2cdcde7ea/py_key_value_aio-0.3.0.tar.gz", hash = "sha256:858e852fcf6d696d231266da66042d3355a7f9871650415feef9fca7a6cd4155", size = 50801, upload-time = "2025-11-17T16:50:04.711Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/99/10/72f6f213b8f0bce36eff21fda0a13271834e9eeff7f9609b01afdc253c79/py_key_value_aio-0.3.0-py3-none-any.whl", hash = "sha256:1c781915766078bfd608daa769fefb97e65d1d73746a3dfb640460e322071b64", size = 96342, upload-time = "2025-11-17T16:50:03.801Z" },
+]
+
+[package.optional-dependencies]
+disk = [
+    { name = "diskcache" },
+    { name = "pathvalidate" },
+]
+keyring = [
+    { name = "keyring" },
+]
+memory = [
+    { name = "cachetools" },
+]
+redis = [
+    { name = "redis" },
+]
+
+[[package]]
+name = "py-key-value-shared"
+version = "0.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beartype" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7b/e4/1971dfc4620a3a15b4579fe99e024f5edd6e0967a71154771a059daff4db/py_key_value_shared-0.3.0.tar.gz", hash = "sha256:8fdd786cf96c3e900102945f92aa1473138ebe960ef49da1c833790160c28a4b", size = 11666, upload-time = "2025-11-17T16:50:06.849Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/e4/b8b0a03ece72f47dce2307d36e1c34725b7223d209fc679315ffe6a4e2c3/py_key_value_shared-0.3.0-py3-none-any.whl", hash = "sha256:5b0efba7ebca08bb158b1e93afc2f07d30b8f40c2fc12ce24a4c0d84f42f9298", size = 19560, upload-time = "2025-11-17T16:50:05.954Z" },
+]
+
+[[package]]
+name = "pycparser"
+version = "2.23"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fe/cf/d2d3b9f5699fb1e4615c8e32ff220203e43b248e1dfcc6736ad9057731ca/pycparser-2.23.tar.gz", hash = "sha256:78816d4f24add8f10a06d6f05b4d424ad9e96cfebf68a4ddc99c65c0720d00c2", size = 173734, upload-time = "2025-09-09T13:23:47.91Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/e3/59cd50310fc9b59512193629e1984c1f95e5c8ae6e5d8c69532ccc65a7fe/pycparser-2.23-py3-none-any.whl", hash = "sha256:e5c6e8d3fbad53479cab09ac03729e0a9faf2bee3db8208a550daf5af81a5934", size = 118140, upload-time = "2025-09-09T13:23:46.651Z" },
+]
+
+[[package]]
+name = "pydantic"
+version = "2.12.4"
+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/96/ad/a17bc283d7d81837c061c49e3eaa27a45991759a1b7eae1031921c6bd924/pydantic-2.12.4.tar.gz", hash = "sha256:0f8cb9555000a4b5b617f66bfd2566264c4984b27589d3b845685983e8ea85ac", size = 821038, upload-time = "2025-11-05T10:50:08.59Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/2f/e68750da9b04856e2a7ec56fc6f034a5a79775e9b9a81882252789873798/pydantic-2.12.4-py3-none-any.whl", hash = "sha256:92d3d202a745d46f9be6df459ac5a064fdaa3c1c4cd8adcfa332ccf3c05f871e", size = 463400, upload-time = "2025-11-05T10:50:06.732Z" },
+]
+
+[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.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/20/c5/dbbc27b814c71676593d1c3f718e6cd7d4f00652cefa24b75f7aa3efb25e/pydantic_settings-2.11.0.tar.gz", hash = "sha256:d0e87a1c7d33593beb7194adb8470fc426e95ba02af83a0f23474a04c9a08180", size = 188394, upload-time = "2025-09-24T14:19:11.764Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/83/d6/887a1ff844e64aa823fb4905978d882a633cfe295c32eacad582b78a7d8b/pydantic_settings-2.11.0-py3-none-any.whl", hash = "sha256:fe2cea3413b9530d10f3a5875adffb17ada5c1e1bab0b2885546d7310415207c", size = 48608, upload-time = "2025-09-24T14:19:10.015Z" },
+]
+
+[[package]]
+name = "pydocket"
+version = "0.16.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cloudpickle" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "fakeredis", extra = ["lua"] },
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-exporter-prometheus" },
+    { name = "opentelemetry-instrumentation" },
+    { name = "prometheus-client" },
+    { name = "py-key-value-aio", extra = ["memory", "redis"] },
+    { name = "python-json-logger" },
+    { name = "redis" },
+    { name = "rich" },
+    { name = "typer" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/00/26befe5f58df7cd1aeda4a8d10bc7d1908ffd86b80fd995e57a2a7b3f7bd/pydocket-0.16.6.tar.gz", hash = "sha256:b96c96ad7692827214ed4ff25fcf941ec38371314db5dcc1ae792b3e9d3a0294", size = 299054, upload-time = "2026-01-09T22:09:15.405Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0a/3f/7483e5a6dc6326b6e0c640619b5c5bd1d6e3c20e54d58f5fb86267cef00e/pydocket-0.16.6-py3-none-any.whl", hash = "sha256:683d21e2e846aa5106274e7d59210331b242d7fb0dce5b08d3b82065663ed183", size = 67697, upload-time = "2026-01-09T22:09:13.436Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "pyjwt"
+version = "2.10.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/46/bd74733ff231675599650d3e47f361794b22ef3e3770998dda30d3b63726/pyjwt-2.10.1.tar.gz", hash = "sha256:3cc5772eb20009233caf06e9d8a0577824723b44e6648ee0a2aedb6cf9381953", size = 87785, upload-time = "2024-11-28T03:43:29.933Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/61/ad/689f02752eeec26aed679477e80e632ef1b682313be70793d798c1d5fc8f/PyJWT-2.10.1-py3-none-any.whl", hash = "sha256:dcdd193e30abefd5debf142f9adfcdd2b58004e644f25406ffaebd50bd98dacb", size = 22997, upload-time = "2024-11-28T03:43:27.893Z" },
+]
+
+[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 = "8.4.2"
+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/a3/5c/00a0e072241553e1a7496d638deababa67c5058571567b92a7eaa258397c/pytest-8.4.2.tar.gz", hash = "sha256:86c0d0b93306b961d58d62a4db4879f27fe25513d4b969df351abdddb3c30e01", size = 1519618, upload-time = "2025-09-04T14:34:22.711Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a8/a4/20da314d277121d6534b3a980b29035dcd51e6744bd79075a6ce8fa4eb8d/pytest-8.4.2-py3-none-any.whl", hash = "sha256:872f880de3fc3a5bdc88a11b39c9710c3497a547cfa9320bc3c5e62fbf272e79", size = 365750, upload-time = "2025-09-04T14:34:20.226Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.2.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/42/86/9e3c5f48f7b7b638b216e4b9e645f54d199d7abbbab7a64a13b4e12ba10f/pytest_asyncio-1.2.0.tar.gz", hash = "sha256:c609a64a2a8768462d0c99811ddb8bd2583c33fd33cf7f21af1c142e824ffb57", size = 50119, upload-time = "2025-09-12T07:33:53.816Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/93/2fa34714b7a4ae72f2f8dad66ba17dd9a2c793220719e736dda28b7aec27/pytest_asyncio-1.2.0-py3-none-any.whl", hash = "sha256:8e17ae5e46d8e7efe51ab6494dd2010f4ca8dae51652aa3c8d55acf50bfb2e99", size = 15095, upload-time = "2025-09-12T07:33:52.639Z" },
+]
+
+[[package]]
+name = "python-dotenv"
+version = "1.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f0/26/19cadc79a718c5edbec86fd4919a6b6d3f681039a2f6d66d14be94e75fb9/python_dotenv-1.2.1.tar.gz", hash = "sha256:42667e897e16ab0d66954af0e60a9caa94f0fd4ecf3aaf6d2d260eec1aa36ad6", size = 44221, upload-time = "2025-10-26T15:12:10.434Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/1b/a298b06749107c305e1fe0f814c6c74aea7b2f1e10989cb30f544a1b3253/python_dotenv-1.2.1-py3-none-any.whl", hash = "sha256:b81ee9561e9ca4004139c6cbba3a238c32b03e4894671e181b671e8cb8425d61", size = 21230, upload-time = "2025-10-26T15:12:09.109Z" },
+]
+
+[[package]]
+name = "python-json-logger"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/29/bf/eca6a3d43db1dae7070f70e160ab20b807627ba953663ba07928cdd3dc58/python_json_logger-4.0.0.tar.gz", hash = "sha256:f58e68eb46e1faed27e0f574a55a0455eecd7b8a5b88b85a784519ba3cff047f", size = 17683, upload-time = "2025-10-06T04:15:18.984Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/e5/fecf13f06e5e5f67e8837d777d1bc43fac0ed2b77a676804df5c34744727/python_json_logger-4.0.0-py3-none-any.whl", hash = "sha256:af09c9daf6a813aa4cc7180395f50f2a9e5fa056034c9953aec92e381c5ba1e2", size = 15548, upload-time = "2025-10-06T04:15:17.553Z" },
+]
+
+[[package]]
+name = "python-multipart"
+version = "0.0.22"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/01/979e98d542a70714b0cb2b6728ed0b7c46792b695e3eaec3e20711271ca3/python_multipart-0.0.22.tar.gz", hash = "sha256:7340bef99a7e0032613f56dc36027b959fd3b30a787ed62d310e951f7c3a3a58", size = 37612, upload-time = "2026-01-25T10:15:56.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1b/d0/397f9626e711ff749a95d96b7af99b9c566a9bb5129b8e4c10fc4d100304/python_multipart-0.0.22-py3-none-any.whl", hash = "sha256:2b2cd894c83d21bf49d702499531c7bafd057d730c201782048f7945d82de155", size = 24579, upload-time = "2026-01-25T10:15:54.811Z" },
+]
+
+[[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.1.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/43/c8/983d5c6579a411d8a99bc5823cc5712768859b5ce2c8afe1a65b37832c81/redis-7.1.0.tar.gz", hash = "sha256:b1cc3cfa5a2cb9c2ab3ba700864fb0ad75617b41f01352ce5779dabf6d5f9c3c", size = 4796669, upload-time = "2025-11-19T15:54:39.961Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/89/f0/8956f8a86b20d7bb9d6ac0187cf4cd54d8065bc9a1a09eb8011d4d326596/redis-7.1.0-py3-none-any.whl", hash = "sha256:23c52b208f92b56103e17c5d06bdc1a6c2c0b3106583985a76a18f83b265de2b", size = 354159, upload-time = "2025-11-19T15:54:38.064Z" },
+]
+
+[[package]]
+name = "referencing"
+version = "0.36.2"
+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/2f/db/98b5c277be99dd18bfd91dd04e1b759cad18d1a338188c936e92f921c7e2/referencing-0.36.2.tar.gz", hash = "sha256:df2e89862cd09deabbdba16944cc3f10feb6b3e6f18e902f7cc25609a34775aa", size = 74744, upload-time = "2025-01-25T08:48:16.138Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/b1/3baf80dc6d2b7bc27a95a67752d0208e410351e3feb4eb78de5f77454d8d/referencing-0.36.2-py3-none-any.whl", hash = "sha256:e8699adbbf8b5c7de96d8ffa0eb5c158b3beafce084968e2ea8bb08c6794dcd0", size = 26775, upload-time = "2025-01-25T08:48:14.241Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.32.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
+]
+
+[[package]]
+name = "rich"
+version = "14.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fb/d2/8920e102050a0de7bfabeb4c4614a49248cf8d5d7a8d01885fbb24dc767a/rich-14.2.0.tar.gz", hash = "sha256:73ff50c7c0c1c77c8243079283f4edb376f0f6442433aecb8ce7e6d0b92d1fe4", size = 219990, upload-time = "2025-10-09T14:16:53.064Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393, upload-time = "2025-10-09T14:16:51.245Z" },
+]
+
+[[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.28.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/48/dc/95f074d43452b3ef5d06276696ece4b3b5d696e7c9ad7173c54b1390cd70/rpds_py-0.28.0.tar.gz", hash = "sha256:abd4df20485a0983e2ca334a216249b6186d6e3c1627e106651943dbdb791aea", size = 27419, upload-time = "2025-10-22T22:24:29.327Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/f8/13bb772dc7cbf2c3c5b816febc34fa0cb2c64a08e0569869585684ce6631/rpds_py-0.28.0-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:7b6013db815417eeb56b2d9d7324e64fcd4fa289caeee6e7a78b2e11fc9b438a", size = 362820, upload-time = "2025-10-22T22:21:15.074Z" },
+    { url = "https://files.pythonhosted.org/packages/84/91/6acce964aab32469c3dbe792cb041a752d64739c534e9c493c701ef0c032/rpds_py-0.28.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:1a4c6b05c685c0c03f80dabaeb73e74218c49deea965ca63f76a752807397207", size = 348499, upload-time = "2025-10-22T22:21:17.658Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/93/c05bb1f4f5e0234db7c4917cb8dd5e2e0a9a7b26dc74b1b7bee3c9cfd477/rpds_py-0.28.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f4794c6c3fbe8f9ac87699b131a1f26e7b4abcf6d828da46a3a52648c7930eba", size = 379356, upload-time = "2025-10-22T22:21:19.847Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/37/e292da436f0773e319753c567263427cdf6c645d30b44f09463ff8216cda/rpds_py-0.28.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:2e8456b6ee5527112ff2354dd9087b030e3429e43a74f480d4a5ca79d269fd85", size = 390151, upload-time = "2025-10-22T22:21:21.569Z" },
+    { url = "https://files.pythonhosted.org/packages/76/87/a4e3267131616e8faf10486dc00eaedf09bd61c87f01e5ef98e782ee06c9/rpds_py-0.28.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:beb880a9ca0a117415f241f66d56025c02037f7c4efc6fe59b5b8454f1eaa50d", size = 524831, upload-time = "2025-10-22T22:21:23.394Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/c8/4a4ca76f0befae9515da3fad11038f0fce44f6bb60b21fe9d9364dd51fb0/rpds_py-0.28.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6897bebb118c44b38c9cb62a178e09f1593c949391b9a1a6fe777ccab5934ee7", size = 404687, upload-time = "2025-10-22T22:21:25.201Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/65/118afe854424456beafbbebc6b34dcf6d72eae3a08b4632bc4220f8240d9/rpds_py-0.28.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b1b553dd06e875249fd43efd727785efb57a53180e0fde321468222eabbeaafa", size = 382683, upload-time = "2025-10-22T22:21:26.536Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/bc/0625064041fb3a0c77ecc8878c0e8341b0ae27ad0f00cf8f2b57337a1e63/rpds_py-0.28.0-cp310-cp310-manylinux_2_31_riscv64.whl", hash = "sha256:f0b2044fdddeea5b05df832e50d2a06fe61023acb44d76978e1b060206a8a476", size = 398927, upload-time = "2025-10-22T22:21:27.864Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/1a/fed7cf2f1ee8a5e4778f2054153f2cfcf517748875e2f5b21cf8907cd77d/rpds_py-0.28.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:05cf1e74900e8da73fa08cc76c74a03345e5a3e37691d07cfe2092d7d8e27b04", size = 411590, upload-time = "2025-10-22T22:21:29.474Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/64/a8e0f67fa374a6c472dbb0afdaf1ef744724f165abb6899f20e2f1563137/rpds_py-0.28.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:efd489fec7c311dae25e94fe7eeda4b3d06be71c68f2cf2e8ef990ffcd2cd7e8", size = 559843, upload-time = "2025-10-22T22:21:30.917Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/ea/e10353f6d7c105be09b8135b72787a65919971ae0330ad97d87e4e199880/rpds_py-0.28.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:ada7754a10faacd4f26067e62de52d6af93b6d9542f0df73c57b9771eb3ba9c4", size = 584188, upload-time = "2025-10-22T22:21:32.827Z" },
+    { url = "https://files.pythonhosted.org/packages/18/b0/a19743e0763caf0c89f6fc6ba6fbd9a353b24ffb4256a492420c5517da5a/rpds_py-0.28.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:c2a34fd26588949e1e7977cfcbb17a9a42c948c100cab890c6d8d823f0586457", size = 550052, upload-time = "2025-10-22T22:21:34.702Z" },
+    { url = "https://files.pythonhosted.org/packages/de/bc/ec2c004f6c7d6ab1e25dae875cdb1aee087c3ebed5b73712ed3000e3851a/rpds_py-0.28.0-cp310-cp310-win32.whl", hash = "sha256:f9174471d6920cbc5e82a7822de8dfd4dcea86eb828b04fc8c6519a77b0ee51e", size = 215110, upload-time = "2025-10-22T22:21:36.645Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/de/4ce8abf59674e17187023933547d2018363e8fc76ada4f1d4d22871ccb6e/rpds_py-0.28.0-cp310-cp310-win_amd64.whl", hash = "sha256:6e32dd207e2c4f8475257a3540ab8a93eff997abfa0a3fdb287cae0d6cd874b8", size = 223850, upload-time = "2025-10-22T22:21:38.006Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/34/058d0db5471c6be7bef82487ad5021ff8d1d1d27794be8730aad938649cf/rpds_py-0.28.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:03065002fd2e287725d95fbc69688e0c6daf6c6314ba38bdbaa3895418e09296", size = 362344, upload-time = "2025-10-22T22:21:39.713Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/67/9503f0ec8c055a0782880f300c50a2b8e5e72eb1f94dfc2053da527444dd/rpds_py-0.28.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:28ea02215f262b6d078daec0b45344c89e161eab9526b0d898221d96fdda5f27", size = 348440, upload-time = "2025-10-22T22:21:41.056Z" },
+    { url = "https://files.pythonhosted.org/packages/68/2e/94223ee9b32332a41d75b6f94b37b4ce3e93878a556fc5f152cbd856a81f/rpds_py-0.28.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25dbade8fbf30bcc551cb352376c0ad64b067e4fc56f90e22ba70c3ce205988c", size = 379068, upload-time = "2025-10-22T22:21:42.593Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/25/54fd48f9f680cfc44e6a7f39a5fadf1d4a4a1fd0848076af4a43e79f998c/rpds_py-0.28.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3c03002f54cc855860bfdc3442928ffdca9081e73b5b382ed0b9e8efe6e5e205", size = 390518, upload-time = "2025-10-22T22:21:43.998Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/85/ac258c9c27f2ccb1bd5d0697e53a82ebcf8088e3186d5d2bf8498ee7ed44/rpds_py-0.28.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b9699fa7990368b22032baf2b2dce1f634388e4ffc03dfefaaac79f4695edc95", size = 525319, upload-time = "2025-10-22T22:21:45.645Z" },
+    { url = "https://files.pythonhosted.org/packages/40/cb/c6734774789566d46775f193964b76627cd5f42ecf246d257ce84d1912ed/rpds_py-0.28.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b9b06fe1a75e05e0713f06ea0c89ecb6452210fd60e2f1b6ddc1067b990e08d9", size = 404896, upload-time = "2025-10-22T22:21:47.544Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/53/14e37ce83202c632c89b0691185dca9532288ff9d390eacae3d2ff771bae/rpds_py-0.28.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac9f83e7b326a3f9ec3ef84cda98fb0a74c7159f33e692032233046e7fd15da2", size = 382862, upload-time = "2025-10-22T22:21:49.176Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/83/f3642483ca971a54d60caa4449f9d6d4dbb56a53e0072d0deff51b38af74/rpds_py-0.28.0-cp311-cp311-manylinux_2_31_riscv64.whl", hash = "sha256:0d3259ea9ad8743a75a43eb7819324cdab393263c91be86e2d1901ee65c314e0", size = 398848, upload-time = "2025-10-22T22:21:51.024Z" },
+    { url = "https://files.pythonhosted.org/packages/44/09/2d9c8b2f88e399b4cfe86efdf2935feaf0394e4f14ab30c6c5945d60af7d/rpds_py-0.28.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:9a7548b345f66f6695943b4ef6afe33ccd3f1b638bd9afd0f730dd255c249c9e", size = 412030, upload-time = "2025-10-22T22:21:52.665Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/f5/e1cec473d4bde6df1fd3738be8e82d64dd0600868e76e92dfeaebbc2d18f/rpds_py-0.28.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:c9a40040aa388b037eb39416710fbcce9443498d2eaab0b9b45ae988b53f5c67", size = 559700, upload-time = "2025-10-22T22:21:54.123Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/be/73bb241c1649edbf14e98e9e78899c2c5e52bbe47cb64811f44d2cc11808/rpds_py-0.28.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8f60c7ea34e78c199acd0d3cda37a99be2c861dd2b8cf67399784f70c9f8e57d", size = 584581, upload-time = "2025-10-22T22:21:56.102Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/9c/ffc6e9218cd1eb5c2c7dbd276c87cd10e8c2232c456b554169eb363381df/rpds_py-0.28.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1571ae4292649100d743b26d5f9c63503bb1fedf538a8f29a98dce2d5ba6b4e6", size = 549981, upload-time = "2025-10-22T22:21:58.253Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/50/da8b6d33803a94df0149345ee33e5d91ed4d25fc6517de6a25587eae4133/rpds_py-0.28.0-cp311-cp311-win32.whl", hash = "sha256:5cfa9af45e7c1140af7321fa0bef25b386ee9faa8928c80dc3a5360971a29e8c", size = 214729, upload-time = "2025-10-22T22:21:59.625Z" },
+    { url = "https://files.pythonhosted.org/packages/12/fd/b0f48c4c320ee24c8c20df8b44acffb7353991ddf688af01eef5f93d7018/rpds_py-0.28.0-cp311-cp311-win_amd64.whl", hash = "sha256:dd8d86b5d29d1b74100982424ba53e56033dc47720a6de9ba0259cf81d7cecaa", size = 223977, upload-time = "2025-10-22T22:22:01.092Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/21/c8e77a2ac66e2ec4e21f18a04b4e9a0417ecf8e61b5eaeaa9360a91713b4/rpds_py-0.28.0-cp311-cp311-win_arm64.whl", hash = "sha256:4e27d3a5709cc2b3e013bf93679a849213c79ae0573f9b894b284b55e729e120", size = 217326, upload-time = "2025-10-22T22:22:02.944Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/5c/6c3936495003875fe7b14f90ea812841a08fca50ab26bd840e924097d9c8/rpds_py-0.28.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:6b4f28583a4f247ff60cd7bdda83db8c3f5b05a7a82ff20dd4b078571747708f", size = 366439, upload-time = "2025-10-22T22:22:04.525Z" },
+    { url = "https://files.pythonhosted.org/packages/56/f9/a0f1ca194c50aa29895b442771f036a25b6c41a35e4f35b1a0ea713bedae/rpds_py-0.28.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d678e91b610c29c4b3d52a2c148b641df2b4676ffe47c59f6388d58b99cdc424", size = 348170, upload-time = "2025-10-22T22:22:06.397Z" },
+    { url = "https://files.pythonhosted.org/packages/18/ea/42d243d3a586beb72c77fa5def0487daf827210069a95f36328e869599ea/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e819e0e37a44a78e1383bf1970076e2ccc4dc8c2bbaa2f9bd1dc987e9afff628", size = 378838, upload-time = "2025-10-22T22:22:07.932Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/78/3de32e18a94791af8f33601402d9d4f39613136398658412a4e0b3047327/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5ee514e0f0523db5d3fb171f397c54875dbbd69760a414dccf9d4d7ad628b5bd", size = 393299, upload-time = "2025-10-22T22:22:09.435Z" },
+    { url = "https://files.pythonhosted.org/packages/13/7e/4bdb435afb18acea2eb8a25ad56b956f28de7c59f8a1d32827effa0d4514/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f3fa06d27fdcee47f07a39e02862da0100cb4982508f5ead53ec533cd5fe55e", size = 518000, upload-time = "2025-10-22T22:22:11.326Z" },
+    { url = "https://files.pythonhosted.org/packages/31/d0/5f52a656875cdc60498ab035a7a0ac8f399890cc1ee73ebd567bac4e39ae/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:46959ef2e64f9e4a41fc89aa20dbca2b85531f9a72c21099a3360f35d10b0d5a", size = 408746, upload-time = "2025-10-22T22:22:13.143Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/cd/49ce51767b879cde77e7ad9fae164ea15dce3616fe591d9ea1df51152706/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8455933b4bcd6e83fde3fefc987a023389c4b13f9a58c8d23e4b3f6d13f78c84", size = 386379, upload-time = "2025-10-22T22:22:14.602Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/99/e4e1e1ee93a98f72fc450e36c0e4d99c35370220e815288e3ecd2ec36a2a/rpds_py-0.28.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:ad50614a02c8c2962feebe6012b52f9802deec4263946cddea37aaf28dd25a66", size = 401280, upload-time = "2025-10-22T22:22:16.063Z" },
+    { url = "https://files.pythonhosted.org/packages/61/35/e0c6a57488392a8b319d2200d03dad2b29c0db9996f5662c3b02d0b86c02/rpds_py-0.28.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e5deca01b271492553fdb6c7fd974659dce736a15bae5dad7ab8b93555bceb28", size = 412365, upload-time = "2025-10-22T22:22:17.504Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6a/841337980ea253ec797eb084665436007a1aad0faac1ba097fb906c5f69c/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:735f8495a13159ce6a0d533f01e8674cec0c57038c920495f87dcb20b3ddb48a", size = 559573, upload-time = "2025-10-22T22:22:19.108Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/5e/64826ec58afd4c489731f8b00729c5f6afdb86f1df1df60bfede55d650bb/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:961ca621ff10d198bbe6ba4957decca61aa2a0c56695384c1d6b79bf61436df5", size = 583973, upload-time = "2025-10-22T22:22:20.768Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ee/44d024b4843f8386a4eeaa4c171b3d31d55f7177c415545fd1a24c249b5d/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2374e16cc9131022e7d9a8f8d65d261d9ba55048c78f3b6e017971a4f5e6353c", size = 553800, upload-time = "2025-10-22T22:22:22.25Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/89/33e675dccff11a06d4d85dbb4d1865f878d5020cbb69b2c1e7b2d3f82562/rpds_py-0.28.0-cp312-cp312-win32.whl", hash = "sha256:d15431e334fba488b081d47f30f091e5d03c18527c325386091f31718952fe08", size = 216954, upload-time = "2025-10-22T22:22:24.105Z" },
+    { url = "https://files.pythonhosted.org/packages/af/36/45f6ebb3210887e8ee6dbf1bc710ae8400bb417ce165aaf3024b8360d999/rpds_py-0.28.0-cp312-cp312-win_amd64.whl", hash = "sha256:a410542d61fc54710f750d3764380b53bf09e8c4edbf2f9141a82aa774a04f7c", size = 227844, upload-time = "2025-10-22T22:22:25.551Z" },
+    { url = "https://files.pythonhosted.org/packages/57/91/f3fb250d7e73de71080f9a221d19bd6a1c1eb0d12a1ea26513f6c1052ad6/rpds_py-0.28.0-cp312-cp312-win_arm64.whl", hash = "sha256:1f0cfd1c69e2d14f8c892b893997fa9a60d890a0c8a603e88dca4955f26d1edd", size = 217624, upload-time = "2025-10-22T22:22:26.914Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/03/ce566d92611dfac0085c2f4b048cd53ed7c274a5c05974b882a908d540a2/rpds_py-0.28.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:e9e184408a0297086f880556b6168fa927d677716f83d3472ea333b42171ee3b", size = 366235, upload-time = "2025-10-22T22:22:28.397Z" },
+    { url = "https://files.pythonhosted.org/packages/00/34/1c61da1b25592b86fd285bd7bd8422f4c9d748a7373b46126f9ae792a004/rpds_py-0.28.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:edd267266a9b0448f33dc465a97cfc5d467594b600fe28e7fa2f36450e03053a", size = 348241, upload-time = "2025-10-22T22:22:30.171Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/00/ed1e28616848c61c493a067779633ebf4b569eccaacf9ccbdc0e7cba2b9d/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:85beb8b3f45e4e32f6802fb6cd6b17f615ef6c6a52f265371fb916fae02814aa", size = 378079, upload-time = "2025-10-22T22:22:31.644Z" },
+    { url = "https://files.pythonhosted.org/packages/11/b2/ccb30333a16a470091b6e50289adb4d3ec656fd9951ba8c5e3aaa0746a67/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d2412be8d00a1b895f8ad827cc2116455196e20ed994bb704bf138fe91a42724", size = 393151, upload-time = "2025-10-22T22:22:33.453Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/d0/73e2217c3ee486d555cb84920597480627d8c0240ff3062005c6cc47773e/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:cf128350d384b777da0e68796afdcebc2e9f63f0e9f242217754e647f6d32491", size = 517520, upload-time = "2025-10-22T22:22:34.949Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/91/23efe81c700427d0841a4ae7ea23e305654381831e6029499fe80be8a071/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a2036d09b363aa36695d1cc1a97b36865597f4478470b0697b5ee9403f4fe399", size = 408699, upload-time = "2025-10-22T22:22:36.584Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/ee/a324d3198da151820a326c1f988caaa4f37fc27955148a76fff7a2d787a9/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b8e1e9be4fa6305a16be628959188e4fd5cd6f1b0e724d63c6d8b2a8adf74ea6", size = 385720, upload-time = "2025-10-22T22:22:38.014Z" },
+    { url = "https://files.pythonhosted.org/packages/19/ad/e68120dc05af8b7cab4a789fccd8cdcf0fe7e6581461038cc5c164cd97d2/rpds_py-0.28.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:0a403460c9dd91a7f23fc3188de6d8977f1d9603a351d5db6cf20aaea95b538d", size = 401096, upload-time = "2025-10-22T22:22:39.869Z" },
+    { url = "https://files.pythonhosted.org/packages/99/90/c1e070620042459d60df6356b666bb1f62198a89d68881816a7ed121595a/rpds_py-0.28.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d7366b6553cdc805abcc512b849a519167db8f5e5c3472010cd1228b224265cb", size = 411465, upload-time = "2025-10-22T22:22:41.395Z" },
+    { url = "https://files.pythonhosted.org/packages/68/61/7c195b30d57f1b8d5970f600efee72a4fad79ec829057972e13a0370fd24/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5b43c6a3726efd50f18d8120ec0551241c38785b68952d240c45ea553912ac41", size = 558832, upload-time = "2025-10-22T22:22:42.871Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/3d/06f3a718864773f69941d4deccdf18e5e47dd298b4628062f004c10f3b34/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:0cb7203c7bc69d7c1585ebb33a2e6074492d2fc21ad28a7b9d40457ac2a51ab7", size = 583230, upload-time = "2025-10-22T22:22:44.877Z" },
+    { url = "https://files.pythonhosted.org/packages/66/df/62fc783781a121e77fee9a21ead0a926f1b652280a33f5956a5e7833ed30/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:7a52a5169c664dfb495882adc75c304ae1d50df552fbd68e100fdc719dee4ff9", size = 553268, upload-time = "2025-10-22T22:22:46.441Z" },
+    { url = "https://files.pythonhosted.org/packages/84/85/d34366e335140a4837902d3dea89b51f087bd6a63c993ebdff59e93ee61d/rpds_py-0.28.0-cp313-cp313-win32.whl", hash = "sha256:2e42456917b6687215b3e606ab46aa6bca040c77af7df9a08a6dcfe8a4d10ca5", size = 217100, upload-time = "2025-10-22T22:22:48.342Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/1c/f25a3f3752ad7601476e3eff395fe075e0f7813fbb9862bd67c82440e880/rpds_py-0.28.0-cp313-cp313-win_amd64.whl", hash = "sha256:e0a0311caedc8069d68fc2bf4c9019b58a2d5ce3cd7cb656c845f1615b577e1e", size = 227759, upload-time = "2025-10-22T22:22:50.219Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/d6/5f39b42b99615b5bc2f36ab90423ea404830bdfee1c706820943e9a645eb/rpds_py-0.28.0-cp313-cp313-win_arm64.whl", hash = "sha256:04c1b207ab8b581108801528d59ad80aa83bb170b35b0ddffb29c20e411acdc1", size = 217326, upload-time = "2025-10-22T22:22:51.647Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/8b/0c69b72d1cee20a63db534be0df271effe715ef6c744fdf1ff23bb2b0b1c/rpds_py-0.28.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:f296ea3054e11fc58ad42e850e8b75c62d9a93a9f981ad04b2e5ae7d2186ff9c", size = 355736, upload-time = "2025-10-22T22:22:53.211Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/6d/0c2ee773cfb55c31a8514d2cece856dd299170a49babd50dcffb15ddc749/rpds_py-0.28.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:5a7306c19b19005ad98468fcefeb7100b19c79fc23a5f24a12e06d91181193fa", size = 342677, upload-time = "2025-10-22T22:22:54.723Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/1c/22513ab25a27ea205144414724743e305e8153e6abe81833b5e678650f5a/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e5d9b86aa501fed9862a443c5c3116f6ead8bc9296185f369277c42542bd646b", size = 371847, upload-time = "2025-10-22T22:22:56.295Z" },
+    { url = "https://files.pythonhosted.org/packages/60/07/68e6ccdb4b05115ffe61d31afc94adef1833d3a72f76c9632d4d90d67954/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e5bbc701eff140ba0e872691d573b3d5d30059ea26e5785acba9132d10c8c31d", size = 381800, upload-time = "2025-10-22T22:22:57.808Z" },
+    { url = "https://files.pythonhosted.org/packages/73/bf/6d6d15df80781d7f9f368e7c1a00caf764436518c4877fb28b029c4624af/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9a5690671cd672a45aa8616d7374fdf334a1b9c04a0cac3c854b1136e92374fe", size = 518827, upload-time = "2025-10-22T22:22:59.826Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/d3/2decbb2976cc452cbf12a2b0aaac5f1b9dc5dd9d1f7e2509a3ee00421249/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9f1d92ecea4fa12f978a367c32a5375a1982834649cdb96539dcdc12e609ab1a", size = 399471, upload-time = "2025-10-22T22:23:01.968Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/2c/f30892f9e54bd02e5faca3f6a26d6933c51055e67d54818af90abed9748e/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8d252db6b1a78d0a3928b6190156042d54c93660ce4d98290d7b16b5296fb7cc", size = 377578, upload-time = "2025-10-22T22:23:03.52Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/5d/3bce97e5534157318f29ac06bf2d279dae2674ec12f7cb9c12739cee64d8/rpds_py-0.28.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:d61b355c3275acb825f8777d6c4505f42b5007e357af500939d4a35b19177259", size = 390482, upload-time = "2025-10-22T22:23:05.391Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/f0/886bd515ed457b5bd93b166175edb80a0b21a210c10e993392127f1e3931/rpds_py-0.28.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:acbe5e8b1026c0c580d0321c8aae4b0a1e1676861d48d6e8c6586625055b606a", size = 402447, upload-time = "2025-10-22T22:23:06.93Z" },
+    { url = "https://files.pythonhosted.org/packages/42/b5/71e8777ac55e6af1f4f1c05b47542a1eaa6c33c1cf0d300dca6a1c6e159a/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:8aa23b6f0fc59b85b4c7d89ba2965af274346f738e8d9fc2455763602e62fd5f", size = 552385, upload-time = "2025-10-22T22:23:08.557Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/cb/6ca2d70cbda5a8e36605e7788c4aa3bea7c17d71d213465a5a675079b98d/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:7b14b0c680286958817c22d76fcbca4800ddacef6f678f3a7c79a1fe7067fe37", size = 575642, upload-time = "2025-10-22T22:23:10.348Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d4/407ad9960ca7856d7b25c96dcbe019270b5ffdd83a561787bc682c797086/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:bcf1d210dfee61a6c86551d67ee1031899c0fdbae88b2d44a569995d43797712", size = 544507, upload-time = "2025-10-22T22:23:12.434Z" },
+    { url = "https://files.pythonhosted.org/packages/51/31/2f46fe0efcac23fbf5797c6b6b7e1c76f7d60773e525cb65fcbc582ee0f2/rpds_py-0.28.0-cp313-cp313t-win32.whl", hash = "sha256:3aa4dc0fdab4a7029ac63959a3ccf4ed605fee048ba67ce89ca3168da34a1342", size = 205376, upload-time = "2025-10-22T22:23:13.979Z" },
+    { url = "https://files.pythonhosted.org/packages/92/e4/15947bda33cbedfc134490a41841ab8870a72a867a03d4969d886f6594a2/rpds_py-0.28.0-cp313-cp313t-win_amd64.whl", hash = "sha256:7b7d9d83c942855e4fdcfa75d4f96f6b9e272d42fffcb72cd4bb2577db2e2907", size = 215907, upload-time = "2025-10-22T22:23:15.5Z" },
+    { url = "https://files.pythonhosted.org/packages/08/47/ffe8cd7a6a02833b10623bf765fbb57ce977e9a4318ca0e8cf97e9c3d2b3/rpds_py-0.28.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:dcdcb890b3ada98a03f9f2bb108489cdc7580176cb73b4f2d789e9a1dac1d472", size = 353830, upload-time = "2025-10-22T22:23:17.03Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/9f/890f36cbd83a58491d0d91ae0db1702639edb33fb48eeb356f80ecc6b000/rpds_py-0.28.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f274f56a926ba2dc02976ca5b11c32855cbd5925534e57cfe1fda64e04d1add2", size = 341819, upload-time = "2025-10-22T22:23:18.57Z" },
+    { url = "https://files.pythonhosted.org/packages/09/e3/921eb109f682aa24fb76207698fbbcf9418738f35a40c21652c29053f23d/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4fe0438ac4a29a520ea94c8c7f1754cdd8feb1bc490dfda1bfd990072363d527", size = 373127, upload-time = "2025-10-22T22:23:20.216Z" },
+    { url = "https://files.pythonhosted.org/packages/23/13/bce4384d9f8f4989f1a9599c71b7a2d877462e5fd7175e1f69b398f729f4/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8a358a32dd3ae50e933347889b6af9a1bdf207ba5d1a3f34e1a38cd3540e6733", size = 382767, upload-time = "2025-10-22T22:23:21.787Z" },
+    { url = "https://files.pythonhosted.org/packages/23/e1/579512b2d89a77c64ccef5a0bc46a6ef7f72ae0cf03d4b26dcd52e57ee0a/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e80848a71c78aa328fefaba9c244d588a342c8e03bda518447b624ea64d1ff56", size = 517585, upload-time = "2025-10-22T22:23:23.699Z" },
+    { url = "https://files.pythonhosted.org/packages/62/3c/ca704b8d324a2591b0b0adcfcaadf9c862375b11f2f667ac03c61b4fd0a6/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f586db2e209d54fe177e58e0bc4946bea5fb0102f150b1b2f13de03e1f0976f8", size = 399828, upload-time = "2025-10-22T22:23:25.713Z" },
+    { url = "https://files.pythonhosted.org/packages/da/37/e84283b9e897e3adc46b4c88bb3f6ec92a43bd4d2f7ef5b13459963b2e9c/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5ae8ee156d6b586e4292491e885d41483136ab994e719a13458055bec14cf370", size = 375509, upload-time = "2025-10-22T22:23:27.32Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/c2/a980beab869d86258bf76ec42dec778ba98151f253a952b02fe36d72b29c/rpds_py-0.28.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:a805e9b3973f7e27f7cab63a6b4f61d90f2e5557cff73b6e97cd5b8540276d3d", size = 392014, upload-time = "2025-10-22T22:23:29.332Z" },
+    { url = "https://files.pythonhosted.org/packages/da/b5/b1d3c5f9d3fa5aeef74265f9c64de3c34a0d6d5cd3c81c8b17d5c8f10ed4/rpds_py-0.28.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5d3fd16b6dc89c73a4da0b4ac8b12a7ecc75b2864b95c9e5afed8003cb50a728", size = 402410, upload-time = "2025-10-22T22:23:31.14Z" },
+    { url = "https://files.pythonhosted.org/packages/74/ae/cab05ff08dfcc052afc73dcb38cbc765ffc86f94e966f3924cd17492293c/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:6796079e5d24fdaba6d49bda28e2c47347e89834678f2bc2c1b4fc1489c0fb01", size = 553593, upload-time = "2025-10-22T22:23:32.834Z" },
+    { url = "https://files.pythonhosted.org/packages/70/80/50d5706ea2a9bfc9e9c5f401d91879e7c790c619969369800cde202da214/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:76500820c2af232435cbe215e3324c75b950a027134e044423f59f5b9a1ba515", size = 576925, upload-time = "2025-10-22T22:23:34.47Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/12/85a57d7a5855a3b188d024b099fd09c90db55d32a03626d0ed16352413ff/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:bbdc5640900a7dbf9dd707fe6388972f5bbd883633eb68b76591044cfe346f7e", size = 542444, upload-time = "2025-10-22T22:23:36.093Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/65/10643fb50179509150eb94d558e8837c57ca8b9adc04bd07b98e57b48f8c/rpds_py-0.28.0-cp314-cp314-win32.whl", hash = "sha256:adc8aa88486857d2b35d75f0640b949759f79dc105f50aa2c27816b2e0dd749f", size = 207968, upload-time = "2025-10-22T22:23:37.638Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/84/0c11fe4d9aaea784ff4652499e365963222481ac647bcd0251c88af646eb/rpds_py-0.28.0-cp314-cp314-win_amd64.whl", hash = "sha256:66e6fa8e075b58946e76a78e69e1a124a21d9a48a5b4766d15ba5b06869d1fa1", size = 218876, upload-time = "2025-10-22T22:23:39.179Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/e0/3ab3b86ded7bb18478392dc3e835f7b754cd446f62f3fc96f4fe2aca78f6/rpds_py-0.28.0-cp314-cp314-win_arm64.whl", hash = "sha256:a6fe887c2c5c59413353b7c0caff25d0e566623501ccfff88957fa438a69377d", size = 212506, upload-time = "2025-10-22T22:23:40.755Z" },
+    { url = "https://files.pythonhosted.org/packages/51/ec/d5681bb425226c3501eab50fc30e9d275de20c131869322c8a1729c7b61c/rpds_py-0.28.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:7a69df082db13c7070f7b8b1f155fa9e687f1d6aefb7b0e3f7231653b79a067b", size = 355433, upload-time = "2025-10-22T22:23:42.259Z" },
+    { url = "https://files.pythonhosted.org/packages/be/ec/568c5e689e1cfb1ea8b875cffea3649260955f677fdd7ddc6176902d04cd/rpds_py-0.28.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b1cde22f2c30ebb049a9e74c5374994157b9b70a16147d332f89c99c5960737a", size = 342601, upload-time = "2025-10-22T22:23:44.372Z" },
+    { url = "https://files.pythonhosted.org/packages/32/fe/51ada84d1d2a1d9d8f2c902cfddd0133b4a5eb543196ab5161d1c07ed2ad/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5338742f6ba7a51012ea470bd4dc600a8c713c0c72adaa0977a1b1f4327d6592", size = 372039, upload-time = "2025-10-22T22:23:46.025Z" },
+    { url = "https://files.pythonhosted.org/packages/07/c1/60144a2f2620abade1a78e0d91b298ac2d9b91bc08864493fa00451ef06e/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e1460ebde1bcf6d496d80b191d854adedcc619f84ff17dc1c6d550f58c9efbba", size = 382407, upload-time = "2025-10-22T22:23:48.098Z" },
+    { url = "https://files.pythonhosted.org/packages/45/ed/091a7bbdcf4038a60a461df50bc4c82a7ed6d5d5e27649aab61771c17585/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e3eb248f2feba84c692579257a043a7699e28a77d86c77b032c1d9fbb3f0219c", size = 518172, upload-time = "2025-10-22T22:23:50.16Z" },
+    { url = "https://files.pythonhosted.org/packages/54/dd/02cc90c2fd9c2ef8016fd7813bfacd1c3a1325633ec8f244c47b449fc868/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3bbba5def70b16cd1c1d7255666aad3b290fbf8d0fe7f9f91abafb73611a91", size = 399020, upload-time = "2025-10-22T22:23:51.81Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/81/5d98cc0329bbb911ccecd0b9e19fbf7f3a5de8094b4cda5e71013b2dd77e/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3114f4db69ac5a1f32e7e4d1cbbe7c8f9cf8217f78e6e002cedf2d54c2a548ed", size = 377451, upload-time = "2025-10-22T22:23:53.711Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/07/4d5bcd49e3dfed2d38e2dcb49ab6615f2ceb9f89f5a372c46dbdebb4e028/rpds_py-0.28.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:4b0cb8a906b1a0196b863d460c0222fb8ad0f34041568da5620f9799b83ccf0b", size = 390355, upload-time = "2025-10-22T22:23:55.299Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/79/9f14ba9010fee74e4f40bf578735cfcbb91d2e642ffd1abe429bb0b96364/rpds_py-0.28.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:cf681ac76a60b667106141e11a92a3330890257e6f559ca995fbb5265160b56e", size = 403146, upload-time = "2025-10-22T22:23:56.929Z" },
+    { url = "https://files.pythonhosted.org/packages/39/4c/f08283a82ac141331a83a40652830edd3a4a92c34e07e2bbe00baaea2f5f/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:1e8ee6413cfc677ce8898d9cde18cc3a60fc2ba756b0dec5b71eb6eb21c49fa1", size = 552656, upload-time = "2025-10-22T22:23:58.62Z" },
+    { url = "https://files.pythonhosted.org/packages/61/47/d922fc0666f0dd8e40c33990d055f4cc6ecff6f502c2d01569dbed830f9b/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:b3072b16904d0b5572a15eb9d31c1954e0d3227a585fc1351aa9878729099d6c", size = 576782, upload-time = "2025-10-22T22:24:00.312Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/0c/5bafdd8ccf6aa9d3bfc630cfece457ff5b581af24f46a9f3590f790e3df2/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:b670c30fd87a6aec281c3c9896d3bae4b205fd75d79d06dc87c2503717e46092", size = 544671, upload-time = "2025-10-22T22:24:02.297Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/37/dcc5d8397caa924988693519069d0beea077a866128719351a4ad95e82fc/rpds_py-0.28.0-cp314-cp314t-win32.whl", hash = "sha256:8014045a15b4d2b3476f0a287fcc93d4f823472d7d1308d47884ecac9e612be3", size = 205749, upload-time = "2025-10-22T22:24:03.848Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/69/64d43b21a10d72b45939a28961216baeb721cc2a430f5f7c3bfa21659a53/rpds_py-0.28.0-cp314-cp314t-win_amd64.whl", hash = "sha256:7a4e59c90d9c27c561eb3160323634a9ff50b04e4f7820600a2beb0ac90db578", size = 216233, upload-time = "2025-10-22T22:24:05.471Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/bc/b43f2ea505f28119bd551ae75f70be0c803d2dbcd37c1b3734909e40620b/rpds_py-0.28.0-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:f5e7101145427087e493b9c9b959da68d357c28c562792300dd21a095118ed16", size = 363913, upload-time = "2025-10-22T22:24:07.129Z" },
+    { url = "https://files.pythonhosted.org/packages/28/f2/db318195d324c89a2c57dc5195058cbadd71b20d220685c5bd1da79ee7fe/rpds_py-0.28.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:31eb671150b9c62409a888850aaa8e6533635704fe2b78335f9aaf7ff81eec4d", size = 350452, upload-time = "2025-10-22T22:24:08.754Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/f2/1391c819b8573a4898cedd6b6c5ec5bc370ce59e5d6bdcebe3c9c1db4588/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:48b55c1f64482f7d8bd39942f376bfdf2f6aec637ee8c805b5041e14eeb771db", size = 380957, upload-time = "2025-10-22T22:24:10.826Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/5c/e5de68ee7eb7248fce93269833d1b329a196d736aefb1a7481d1e99d1222/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:24743a7b372e9a76171f6b69c01aedf927e8ac3e16c474d9fe20d552a8cb45c7", size = 391919, upload-time = "2025-10-22T22:24:12.559Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/4f/2376336112cbfeb122fd435d608ad8d5041b3aed176f85a3cb32c262eb80/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:389c29045ee8bbb1627ea190b4976a310a295559eaf9f1464a1a6f2bf84dde78", size = 528541, upload-time = "2025-10-22T22:24:14.197Z" },
+    { url = "https://files.pythonhosted.org/packages/68/53/5ae232e795853dd20da7225c5dd13a09c0a905b1a655e92bdf8d78a99fd9/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:23690b5827e643150cf7b49569679ec13fe9a610a15949ed48b85eb7f98f34ec", size = 405629, upload-time = "2025-10-22T22:24:16.001Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/2d/351a3b852b683ca9b6b8b38ed9efb2347596973849ba6c3a0e99877c10aa/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6f0c9266c26580e7243ad0d72fc3e01d6b33866cfab5084a6da7576bcf1c4f72", size = 384123, upload-time = "2025-10-22T22:24:17.585Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/15/870804daa00202728cc91cb8e2385fa9f1f4eb49857c49cfce89e304eae6/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_31_riscv64.whl", hash = "sha256:4c6c4db5d73d179746951486df97fd25e92396be07fc29ee8ff9a8f5afbdfb27", size = 400923, upload-time = "2025-10-22T22:24:19.512Z" },
+    { url = "https://files.pythonhosted.org/packages/53/25/3706b83c125fa2a0bccceac951de3f76631f6bd0ee4d02a0ed780712ef1b/rpds_py-0.28.0-pp311-pypy311_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a3b695a8fa799dd2cfdb4804b37096c5f6dba1ac7f48a7fbf6d0485bcd060316", size = 413767, upload-time = "2025-10-22T22:24:21.316Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/f9/ce43dbe62767432273ed2584cef71fef8411bddfb64125d4c19128015018/rpds_py-0.28.0-pp311-pypy311_pp73-musllinux_1_2_aarch64.whl", hash = "sha256:6aa1bfce3f83baf00d9c5fcdbba93a3ab79958b4c7d7d1f55e7fe68c20e63912", size = 561530, upload-time = "2025-10-22T22:24:22.958Z" },
+    { url = "https://files.pythonhosted.org/packages/46/c9/ffe77999ed8f81e30713dd38fd9ecaa161f28ec48bb80fa1cd9118399c27/rpds_py-0.28.0-pp311-pypy311_pp73-musllinux_1_2_i686.whl", hash = "sha256:7b0f9dceb221792b3ee6acb5438eb1f02b0cb2c247796a72b016dcc92c6de829", size = 585453, upload-time = "2025-10-22T22:24:24.779Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/d2/4a73b18821fd4669762c855fd1f4e80ceb66fb72d71162d14da58444a763/rpds_py-0.28.0-pp311-pypy311_pp73-musllinux_1_2_x86_64.whl", hash = "sha256:5d0145edba8abd3db0ab22b5300c99dc152f5c9021fab861be0f0544dc3cbc5f", size = 552199, upload-time = "2025-10-22T22:24:26.54Z" },
+]
+
+[[package]]
+name = "secretstorage"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "jeepney" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/31/9f/11ef35cf1027c1339552ea7bfe6aaa74a8516d8b5caf6e7d338daf54fd80/secretstorage-3.4.0.tar.gz", hash = "sha256:c46e216d6815aff8a8a18706a2fbfd8d53fcbb0dce99301881687a1b0289ef7c", size = 19748, upload-time = "2025-09-09T16:42:13.859Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/91/ff/2e2eed29e02c14a5cb6c57f09b2d5b40e65d6cc71f45b52e0be295ccbc2f/secretstorage-3.4.0-py3-none-any.whl", hash = "sha256:0e3b6265c2c63509fb7415717607e4b2c9ab767b7f344a57473b779ca13bd02e", size = 15272, upload-time = "2025-09-09T16:42:12.744Z" },
+]
+
+[[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 = "sortedcontainers"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/c4/ba2f8066cceb6f23394729afe52f3bf7adec04bf9ed2c820b39e19299111/sortedcontainers-2.4.0.tar.gz", hash = "sha256:25caa5a06cc30b6b83d11423433f65d1f9d76c4c6a0c90e3379eaa43b9bfdb88", size = 30594, upload-time = "2021-05-16T22:03:42.897Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" },
+]
+
+[[package]]
+name = "sse-starlette"
+version = "3.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/db/3c/fa6517610dc641262b77cc7bf994ecd17465812c1b0585fe33e11be758ab/sse_starlette-3.0.3.tar.gz", hash = "sha256:88cfb08747e16200ea990c8ca876b03910a23b547ab3bd764c0d8eb81019b971", size = 21943, upload-time = "2025-10-30T18:44:20.117Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/23/a0/984525d19ca5c8a6c33911a0c164b11490dd0f90ff7fd689f704f84e9a11/sse_starlette-3.0.3-py3-none-any.whl", hash = "sha256:af5bf5a6f3933df1d9c7f8539633dc8444ca6a97ab2e2a7cd3b6e431ac03a431", size = 11765, upload-time = "2025-10-30T18:44:18.834Z" },
+]
+
+[[package]]
+name = "starlette"
+version = "0.50.0"
+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/ba/b8/73a0e6a6e079a9d9cfa64113d771e421640b6f679a52eeb9b32f72d871a1/starlette-0.50.0.tar.gz", hash = "sha256:a2a17b22203254bcbc2e1f926d2d55f3f9497f769416b3190768befe598fa3ca", size = 2646985, upload-time = "2025-11-01T15:25:27.516Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d9/52/1064f510b141bd54025f9b55105e26d1fa970b9be67ad766380a3c9b74b0/starlette-0.50.0-py3-none-any.whl", hash = "sha256:9e5391843ec9b6e472eed1365a78c8098cfceb7a74bfd4d6b1c0c0095efb3bca", size = 74033, upload-time = "2025-11-01T15:25:25.461Z" },
+]
+
+[[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 = ">=8.3.3" },
+    { name = "pytest-asyncio", specifier = ">=1.2.0" },
+]
+
+[[package]]
+name = "tomli"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/52/ed/3f73f72945444548f33eba9a87fc7a6e969915e7b1acc8260b30e1f76a2f/tomli-2.3.0.tar.gz", hash = "sha256:64be704a875d2a59753d80ee8a533c3fe183e3f06807ff7dc2232938ccb01549", size = 17392, upload-time = "2025-10-08T22:01:47.119Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/2e/299f62b401438d5fe1624119c723f5d877acc86a4c2492da405626665f12/tomli-2.3.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:88bd15eb972f3664f5ed4b57c1634a97153b4bac4479dcb6a495f41921eb7f45", size = 153236, upload-time = "2025-10-08T22:01:00.137Z" },
+    { url = "https://files.pythonhosted.org/packages/86/7f/d8fffe6a7aefdb61bced88fcb5e280cfd71e08939da5894161bd71bea022/tomli-2.3.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:883b1c0d6398a6a9d29b508c331fa56adbcdff647f6ace4dfca0f50e90dfd0ba", size = 148084, upload-time = "2025-10-08T22:01:01.63Z" },
+    { url = "https://files.pythonhosted.org/packages/47/5c/24935fb6a2ee63e86d80e4d3b58b222dafaf438c416752c8b58537c8b89a/tomli-2.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d1381caf13ab9f300e30dd8feadb3de072aeb86f1d34a8569453ff32a7dea4bf", size = 234832, upload-time = "2025-10-08T22:01:02.543Z" },
+    { url = "https://files.pythonhosted.org/packages/89/da/75dfd804fc11e6612846758a23f13271b76d577e299592b4371a4ca4cd09/tomli-2.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a0e285d2649b78c0d9027570d4da3425bdb49830a6156121360b3f8511ea3441", size = 242052, upload-time = "2025-10-08T22:01:03.836Z" },
+    { url = "https://files.pythonhosted.org/packages/70/8c/f48ac899f7b3ca7eb13af73bacbc93aec37f9c954df3c08ad96991c8c373/tomli-2.3.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:0a154a9ae14bfcf5d8917a59b51ffd5a3ac1fd149b71b47a3a104ca4edcfa845", size = 239555, upload-time = "2025-10-08T22:01:04.834Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/28/72f8afd73f1d0e7829bfc093f4cb98ce0a40ffc0cc997009ee1ed94ba705/tomli-2.3.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:74bf8464ff93e413514fefd2be591c3b0b23231a77f901db1eb30d6f712fc42c", size = 245128, upload-time = "2025-10-08T22:01:05.84Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/eb/a7679c8ac85208706d27436e8d421dfa39d4c914dcf5fa8083a9305f58d9/tomli-2.3.0-cp311-cp311-win32.whl", hash = "sha256:00b5f5d95bbfc7d12f91ad8c593a1659b6387b43f054104cda404be6bda62456", size = 96445, upload-time = "2025-10-08T22:01:06.896Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/fe/3d3420c4cb1ad9cb462fb52967080575f15898da97e21cb6f1361d505383/tomli-2.3.0-cp311-cp311-win_amd64.whl", hash = "sha256:4dc4ce8483a5d429ab602f111a93a6ab1ed425eae3122032db7e9acf449451be", size = 107165, upload-time = "2025-10-08T22:01:08.107Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/b7/40f36368fcabc518bb11c8f06379a0fd631985046c038aca08c6d6a43c6e/tomli-2.3.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d7d86942e56ded512a594786a5ba0a5e521d02529b3826e7761a05138341a2ac", size = 154891, upload-time = "2025-10-08T22:01:09.082Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/3f/d9dd692199e3b3aab2e4e4dd948abd0f790d9ded8cd10cbaae276a898434/tomli-2.3.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:73ee0b47d4dad1c5e996e3cd33b8a76a50167ae5f96a2607cbe8cc773506ab22", size = 148796, upload-time = "2025-10-08T22:01:10.266Z" },
+    { url = "https://files.pythonhosted.org/packages/60/83/59bff4996c2cf9f9387a0f5a3394629c7efa5ef16142076a23a90f1955fa/tomli-2.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:792262b94d5d0a466afb5bc63c7daa9d75520110971ee269152083270998316f", size = 242121, upload-time = "2025-10-08T22:01:11.332Z" },
+    { url = "https://files.pythonhosted.org/packages/45/e5/7c5119ff39de8693d6baab6c0b6dcb556d192c165596e9fc231ea1052041/tomli-2.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4f195fe57ecceac95a66a75ac24d9d5fbc98ef0962e09b2eddec5d39375aae52", size = 250070, upload-time = "2025-10-08T22:01:12.498Z" },
+    { url = "https://files.pythonhosted.org/packages/45/12/ad5126d3a278f27e6701abde51d342aa78d06e27ce2bb596a01f7709a5a2/tomli-2.3.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e31d432427dcbf4d86958c184b9bfd1e96b5b71f8eb17e6d02531f434fd335b8", size = 245859, upload-time = "2025-10-08T22:01:13.551Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/a1/4d6865da6a71c603cfe6ad0e6556c73c76548557a8d658f9e3b142df245f/tomli-2.3.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7b0882799624980785240ab732537fcfc372601015c00f7fc367c55308c186f6", size = 250296, upload-time = "2025-10-08T22:01:14.614Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/b7/a7a7042715d55c9ba6e8b196d65d2cb662578b4d8cd17d882d45322b0d78/tomli-2.3.0-cp312-cp312-win32.whl", hash = "sha256:ff72b71b5d10d22ecb084d345fc26f42b5143c5533db5e2eaba7d2d335358876", size = 97124, upload-time = "2025-10-08T22:01:15.629Z" },
+    { url = "https://files.pythonhosted.org/packages/06/1e/f22f100db15a68b520664eb3328fb0ae4e90530887928558112c8d1f4515/tomli-2.3.0-cp312-cp312-win_amd64.whl", hash = "sha256:1cb4ed918939151a03f33d4242ccd0aa5f11b3547d0cf30f7c74a408a5b99878", size = 107698, upload-time = "2025-10-08T22:01:16.51Z" },
+    { url = "https://files.pythonhosted.org/packages/89/48/06ee6eabe4fdd9ecd48bf488f4ac783844fd777f547b8d1b61c11939974e/tomli-2.3.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5192f562738228945d7b13d4930baffda67b69425a7f0da96d360b0a3888136b", size = 154819, upload-time = "2025-10-08T22:01:17.964Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/01/88793757d54d8937015c75dcdfb673c65471945f6be98e6a0410fba167ed/tomli-2.3.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:be71c93a63d738597996be9528f4abe628d1adf5e6eb11607bc8fe1a510b5dae", size = 148766, upload-time = "2025-10-08T22:01:18.959Z" },
+    { url = "https://files.pythonhosted.org/packages/42/17/5e2c956f0144b812e7e107f94f1cc54af734eb17b5191c0bbfb72de5e93e/tomli-2.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c4665508bcbac83a31ff8ab08f424b665200c0e1e645d2bd9ab3d3e557b6185b", size = 240771, upload-time = "2025-10-08T22:01:20.106Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/f4/0fbd014909748706c01d16824eadb0307115f9562a15cbb012cd9b3512c5/tomli-2.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4021923f97266babc6ccab9f5068642a0095faa0a51a246a6a02fccbb3514eaf", size = 248586, upload-time = "2025-10-08T22:01:21.164Z" },
+    { url = "https://files.pythonhosted.org/packages/30/77/fed85e114bde5e81ecf9bc5da0cc69f2914b38f4708c80ae67d0c10180c5/tomli-2.3.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4ea38c40145a357d513bffad0ed869f13c1773716cf71ccaa83b0fa0cc4e42f", size = 244792, upload-time = "2025-10-08T22:01:22.417Z" },
+    { url = "https://files.pythonhosted.org/packages/55/92/afed3d497f7c186dc71e6ee6d4fcb0acfa5f7d0a1a2878f8beae379ae0cc/tomli-2.3.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ad805ea85eda330dbad64c7ea7a4556259665bdf9d2672f5dccc740eb9d3ca05", size = 248909, upload-time = "2025-10-08T22:01:23.859Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/84/ef50c51b5a9472e7265ce1ffc7f24cd4023d289e109f669bdb1553f6a7c2/tomli-2.3.0-cp313-cp313-win32.whl", hash = "sha256:97d5eec30149fd3294270e889b4234023f2c69747e555a27bd708828353ab606", size = 96946, upload-time = "2025-10-08T22:01:24.893Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/b7/718cd1da0884f281f95ccfa3a6cc572d30053cba64603f79d431d3c9b61b/tomli-2.3.0-cp313-cp313-win_amd64.whl", hash = "sha256:0c95ca56fbe89e065c6ead5b593ee64b84a26fca063b5d71a1122bf26e533999", size = 107705, upload-time = "2025-10-08T22:01:26.153Z" },
+    { url = "https://files.pythonhosted.org/packages/19/94/aeafa14a52e16163008060506fcb6aa1949d13548d13752171a755c65611/tomli-2.3.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:cebc6fe843e0733ee827a282aca4999b596241195f43b4cc371d64fc6639da9e", size = 154244, upload-time = "2025-10-08T22:01:27.06Z" },
+    { url = "https://files.pythonhosted.org/packages/db/e4/1e58409aa78eefa47ccd19779fc6f36787edbe7d4cd330eeeedb33a4515b/tomli-2.3.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4c2ef0244c75aba9355561272009d934953817c49f47d768070c3c94355c2aa3", size = 148637, upload-time = "2025-10-08T22:01:28.059Z" },
+    { url = "https://files.pythonhosted.org/packages/26/b6/d1eccb62f665e44359226811064596dd6a366ea1f985839c566cd61525ae/tomli-2.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c22a8bf253bacc0cf11f35ad9808b6cb75ada2631c2d97c971122583b129afbc", size = 241925, upload-time = "2025-10-08T22:01:29.066Z" },
+    { url = "https://files.pythonhosted.org/packages/70/91/7cdab9a03e6d3d2bb11beae108da5bdc1c34bdeb06e21163482544ddcc90/tomli-2.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0eea8cc5c5e9f89c9b90c4896a8deefc74f518db5927d0e0e8d4a80953d774d0", size = 249045, upload-time = "2025-10-08T22:01:31.98Z" },
+    { url = "https://files.pythonhosted.org/packages/15/1b/8c26874ed1f6e4f1fcfeb868db8a794cbe9f227299402db58cfcc858766c/tomli-2.3.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:b74a0e59ec5d15127acdabd75ea17726ac4c5178ae51b85bfe39c4f8a278e879", size = 245835, upload-time = "2025-10-08T22:01:32.989Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/42/8e3c6a9a4b1a1360c1a2a39f0b972cef2cc9ebd56025168c4137192a9321/tomli-2.3.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:b5870b50c9db823c595983571d1296a6ff3e1b88f734a4c8f6fc6188397de005", size = 253109, upload-time = "2025-10-08T22:01:34.052Z" },
+    { url = "https://files.pythonhosted.org/packages/22/0c/b4da635000a71b5f80130937eeac12e686eefb376b8dee113b4a582bba42/tomli-2.3.0-cp314-cp314-win32.whl", hash = "sha256:feb0dacc61170ed7ab602d3d972a58f14ee3ee60494292d384649a3dc38ef463", size = 97930, upload-time = "2025-10-08T22:01:35.082Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/74/cb1abc870a418ae99cd5c9547d6bce30701a954e0e721821df483ef7223c/tomli-2.3.0-cp314-cp314-win_amd64.whl", hash = "sha256:b273fcbd7fc64dc3600c098e39136522650c49bca95df2d11cf3b626422392c8", size = 107964, upload-time = "2025-10-08T22:01:36.057Z" },
+    { url = "https://files.pythonhosted.org/packages/54/78/5c46fff6432a712af9f792944f4fcd7067d8823157949f4e40c56b8b3c83/tomli-2.3.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:940d56ee0410fa17ee1f12b817b37a4d4e4dc4d27340863cc67236c74f582e77", size = 163065, upload-time = "2025-10-08T22:01:37.27Z" },
+    { url = "https://files.pythonhosted.org/packages/39/67/f85d9bd23182f45eca8939cd2bc7050e1f90c41f4a2ecbbd5963a1d1c486/tomli-2.3.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:f85209946d1fe94416debbb88d00eb92ce9cd5266775424ff81bc959e001acaf", size = 159088, upload-time = "2025-10-08T22:01:38.235Z" },
+    { url = "https://files.pythonhosted.org/packages/26/5a/4b546a0405b9cc0659b399f12b6adb750757baf04250b148d3c5059fc4eb/tomli-2.3.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a56212bdcce682e56b0aaf79e869ba5d15a6163f88d5451cbde388d48b13f530", size = 268193, upload-time = "2025-10-08T22:01:39.712Z" },
+    { url = "https://files.pythonhosted.org/packages/42/4f/2c12a72ae22cf7b59a7fe75b3465b7aba40ea9145d026ba41cb382075b0e/tomli-2.3.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c5f3ffd1e098dfc032d4d3af5c0ac64f6d286d98bc148698356847b80fa4de1b", size = 275488, upload-time = "2025-10-08T22:01:40.773Z" },
+    { url = "https://files.pythonhosted.org/packages/92/04/a038d65dbe160c3aa5a624e93ad98111090f6804027d474ba9c37c8ae186/tomli-2.3.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5e01decd096b1530d97d5d85cb4dff4af2d8347bd35686654a004f8dea20fc67", size = 272669, upload-time = "2025-10-08T22:01:41.824Z" },
+    { url = "https://files.pythonhosted.org/packages/be/2f/8b7c60a9d1612a7cbc39ffcca4f21a73bf368a80fc25bccf8253e2563267/tomli-2.3.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:8a35dd0e643bb2610f156cca8db95d213a90015c11fee76c946aa62b7ae7e02f", size = 279709, upload-time = "2025-10-08T22:01:43.177Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/46/cc36c679f09f27ded940281c38607716c86cf8ba4a518d524e349c8b4874/tomli-2.3.0-cp314-cp314t-win32.whl", hash = "sha256:a1f7f282fe248311650081faafa5f4732bdbfef5d45fe3f2e702fbc6f2d496e0", size = 107563, upload-time = "2025-10-08T22:01:44.233Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ff/426ca8683cf7b753614480484f6437f568fd2fda2edbdf57a2d3d8b27a0b/tomli-2.3.0-cp314-cp314t-win_amd64.whl", hash = "sha256:70a251f8d4ba2d9ac2542eecf008b3c8a9fc5c3f9f02c56a9d7952612be2fdba", size = 119756, upload-time = "2025-10-08T22:01:45.234Z" },
+    { url = "https://files.pythonhosted.org/packages/77/b8/0135fadc89e73be292b473cb820b4f5a08197779206b33191e801feeae40/tomli-2.3.0-py3-none-any.whl", hash = "sha256:e95b1af3c5b07d9e643909b5abbec77cd9f1217e6d0bca72b0234736b9fb1f1b", size = 14408, upload-time = "2025-10-08T22:01:46.04Z" },
+]
+
+[[package]]
+name = "typer"
+version = "0.21.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "rich" },
+    { name = "shellingham" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/36/bf/8825b5929afd84d0dabd606c67cd57b8388cb3ec385f7ef19c5cc2202069/typer-0.21.1.tar.gz", hash = "sha256:ea835607cd752343b6b2b7ce676893e5a0324082268b48f27aa058bdb7d2145d", size = 110371, upload-time = "2026-01-06T11:21:10.989Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/1d/d9257dd49ff2ca23ea5f132edf1281a0c4f9de8a762b9ae399b670a59235/typer-0.21.1-py3-none-any.whl", hash = "sha256:7985e89081c636b88d172c2ee0cfe33c253160994d47bdfdc302defd7d1f1d01", size = 47381, upload-time = "2026-01-06T11:21:09.824Z" },
+]
+
+[[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 = "urllib3"
+version = "2.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+]
+
+[[package]]
+name = "uvicorn"
+version = "0.38.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/cb/ce/f06b84e2697fef4688ca63bdb2fdf113ca0a3be33f94488f2cadb690b0cf/uvicorn-0.38.0.tar.gz", hash = "sha256:fd97093bdd120a2609fc0d3afe931d4d4ad688b6e75f0f929fde1bc36fe0e91d", size = 80605, upload-time = "2025-10-18T13:46:44.63Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ee/d9/d88e73ca598f4f6ff671fb5fde8a32925c2e08a637303a1d12883c7305fa/uvicorn-0.38.0-py3-none-any.whl", hash = "sha256:48c0afd214ceb59340075b4a052ea1ee91c16fbc2a9b1469cca0e54566977b02", size = 68109, upload-time = "2025-10-18T13:46:42.958Z" },
+]
+
+[[package]]
+name = "websockets"
+version = "15.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/e6/26d09fab466b7ca9c7737474c52be4f76a40301b08362eb2dbc19dcc16c1/websockets-15.0.1.tar.gz", hash = "sha256:82544de02076bafba038ce055ee6412d68da13ab47f0c60cab827346de828dee", size = 177016, upload-time = "2025-03-05T20:03:41.606Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/da/6462a9f510c0c49837bbc9345aca92d767a56c1fb2939e1579df1e1cdcf7/websockets-15.0.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:d63efaa0cd96cf0c5fe4d581521d9fa87744540d4bc999ae6e08595a1014b45b", size = 175423, upload-time = "2025-03-05T20:01:35.363Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/9f/9d11c1a4eb046a9e106483b9ff69bce7ac880443f00e5ce64261b47b07e7/websockets-15.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:ac60e3b188ec7574cb761b08d50fcedf9d77f1530352db4eef1707fe9dee7205", size = 173080, upload-time = "2025-03-05T20:01:37.304Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/4f/b462242432d93ea45f297b6179c7333dd0402b855a912a04e7fc61c0d71f/websockets-15.0.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5756779642579d902eed757b21b0164cd6fe338506a8083eb58af5c372e39d9a", size = 173329, upload-time = "2025-03-05T20:01:39.668Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/0c/6afa1f4644d7ed50284ac59cc70ef8abd44ccf7d45850d989ea7310538d0/websockets-15.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0fdfe3e2a29e4db3659dbd5bbf04560cea53dd9610273917799f1cde46aa725e", size = 182312, upload-time = "2025-03-05T20:01:41.815Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/d4/ffc8bd1350b229ca7a4db2a3e1c482cf87cea1baccd0ef3e72bc720caeec/websockets-15.0.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4c2529b320eb9e35af0fa3016c187dffb84a3ecc572bcee7c3ce302bfeba52bf", size = 181319, upload-time = "2025-03-05T20:01:43.967Z" },
+    { url = "https://files.pythonhosted.org/packages/97/3a/5323a6bb94917af13bbb34009fac01e55c51dfde354f63692bf2533ffbc2/websockets-15.0.1-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac1e5c9054fe23226fb11e05a6e630837f074174c4c2f0fe442996112a6de4fb", size = 181631, upload-time = "2025-03-05T20:01:46.104Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/cc/1aeb0f7cee59ef065724041bb7ed667b6ab1eeffe5141696cccec2687b66/websockets-15.0.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:5df592cd503496351d6dc14f7cdad49f268d8e618f80dce0cd5a36b93c3fc08d", size = 182016, upload-time = "2025-03-05T20:01:47.603Z" },
+    { url = "https://files.pythonhosted.org/packages/79/f9/c86f8f7af208e4161a7f7e02774e9d0a81c632ae76db2ff22549e1718a51/websockets-15.0.1-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:0a34631031a8f05657e8e90903e656959234f3a04552259458aac0b0f9ae6fd9", size = 181426, upload-time = "2025-03-05T20:01:48.949Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/b9/828b0bc6753db905b91df6ae477c0b14a141090df64fb17f8a9d7e3516cf/websockets-15.0.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:3d00075aa65772e7ce9e990cab3ff1de702aa09be3940d1dc88d5abf1ab8a09c", size = 181360, upload-time = "2025-03-05T20:01:50.938Z" },
+    { url = "https://files.pythonhosted.org/packages/89/fb/250f5533ec468ba6327055b7d98b9df056fb1ce623b8b6aaafb30b55d02e/websockets-15.0.1-cp310-cp310-win32.whl", hash = "sha256:1234d4ef35db82f5446dca8e35a7da7964d02c127b095e172e54397fb6a6c256", size = 176388, upload-time = "2025-03-05T20:01:52.213Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/46/aca7082012768bb98e5608f01658ff3ac8437e563eca41cf068bd5849a5e/websockets-15.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:39c1fec2c11dc8d89bba6b2bf1556af381611a173ac2b511cf7231622058af41", size = 176830, upload-time = "2025-03-05T20:01:53.922Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/32/18fcd5919c293a398db67443acd33fde142f283853076049824fc58e6f75/websockets-15.0.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:823c248b690b2fd9303ba00c4f66cd5e2d8c3ba4aa968b2779be9532a4dad431", size = 175423, upload-time = "2025-03-05T20:01:56.276Z" },
+    { url = "https://files.pythonhosted.org/packages/76/70/ba1ad96b07869275ef42e2ce21f07a5b0148936688c2baf7e4a1f60d5058/websockets-15.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:678999709e68425ae2593acf2e3ebcbcf2e69885a5ee78f9eb80e6e371f1bf57", size = 173082, upload-time = "2025-03-05T20:01:57.563Z" },
+    { url = "https://files.pythonhosted.org/packages/86/f2/10b55821dd40eb696ce4704a87d57774696f9451108cff0d2824c97e0f97/websockets-15.0.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d50fd1ee42388dcfb2b3676132c78116490976f1300da28eb629272d5d93e905", size = 173330, upload-time = "2025-03-05T20:01:59.063Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/90/1c37ae8b8a113d3daf1065222b6af61cc44102da95388ac0018fcb7d93d9/websockets-15.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d99e5546bf73dbad5bf3547174cd6cb8ba7273062a23808ffea025ecb1cf8562", size = 182878, upload-time = "2025-03-05T20:02:00.305Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/8d/96e8e288b2a41dffafb78e8904ea7367ee4f891dafc2ab8d87e2124cb3d3/websockets-15.0.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:66dd88c918e3287efc22409d426c8f729688d89a0c587c88971a0faa2c2f3792", size = 181883, upload-time = "2025-03-05T20:02:03.148Z" },
+    { url = "https://files.pythonhosted.org/packages/93/1f/5d6dbf551766308f6f50f8baf8e9860be6182911e8106da7a7f73785f4c4/websockets-15.0.1-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8dd8327c795b3e3f219760fa603dcae1dcc148172290a8ab15158cf85a953413", size = 182252, upload-time = "2025-03-05T20:02:05.29Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/78/2d4fed9123e6620cbf1706c0de8a1632e1a28e7774d94346d7de1bba2ca3/websockets-15.0.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:8fdc51055e6ff4adeb88d58a11042ec9a5eae317a0a53d12c062c8a8865909e8", size = 182521, upload-time = "2025-03-05T20:02:07.458Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/3b/66d4c1b444dd1a9823c4a81f50231b921bab54eee2f69e70319b4e21f1ca/websockets-15.0.1-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:693f0192126df6c2327cce3baa7c06f2a117575e32ab2308f7f8216c29d9e2e3", size = 181958, upload-time = "2025-03-05T20:02:09.842Z" },
+    { url = "https://files.pythonhosted.org/packages/08/ff/e9eed2ee5fed6f76fdd6032ca5cd38c57ca9661430bb3d5fb2872dc8703c/websockets-15.0.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:54479983bd5fb469c38f2f5c7e3a24f9a4e70594cd68cd1fa6b9340dadaff7cf", size = 181918, upload-time = "2025-03-05T20:02:11.968Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/75/994634a49b7e12532be6a42103597b71098fd25900f7437d6055ed39930a/websockets-15.0.1-cp311-cp311-win32.whl", hash = "sha256:16b6c1b3e57799b9d38427dda63edcbe4926352c47cf88588c0be4ace18dac85", size = 176388, upload-time = "2025-03-05T20:02:13.32Z" },
+    { url = "https://files.pythonhosted.org/packages/98/93/e36c73f78400a65f5e236cd376713c34182e6663f6889cd45a4a04d8f203/websockets-15.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:27ccee0071a0e75d22cb35849b1db43f2ecd3e161041ac1ee9d2352ddf72f065", size = 176828, upload-time = "2025-03-05T20:02:14.585Z" },
+    { url = "https://files.pythonhosted.org/packages/51/6b/4545a0d843594f5d0771e86463606a3988b5a09ca5123136f8a76580dd63/websockets-15.0.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:3e90baa811a5d73f3ca0bcbf32064d663ed81318ab225ee4f427ad4e26e5aff3", size = 175437, upload-time = "2025-03-05T20:02:16.706Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/71/809a0f5f6a06522af902e0f2ea2757f71ead94610010cf570ab5c98e99ed/websockets-15.0.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:592f1a9fe869c778694f0aa806ba0374e97648ab57936f092fd9d87f8bc03665", size = 173096, upload-time = "2025-03-05T20:02:18.832Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/69/1a681dd6f02180916f116894181eab8b2e25b31e484c5d0eae637ec01f7c/websockets-15.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0701bc3cfcb9164d04a14b149fd74be7347a530ad3bbf15ab2c678a2cd3dd9a2", size = 173332, upload-time = "2025-03-05T20:02:20.187Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/02/0073b3952f5bce97eafbb35757f8d0d54812b6174ed8dd952aa08429bcc3/websockets-15.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e8b56bdcdb4505c8078cb6c7157d9811a85790f2f2b3632c7d1462ab5783d215", size = 183152, upload-time = "2025-03-05T20:02:22.286Z" },
+    { url = "https://files.pythonhosted.org/packages/74/45/c205c8480eafd114b428284840da0b1be9ffd0e4f87338dc95dc6ff961a1/websockets-15.0.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0af68c55afbd5f07986df82831c7bff04846928ea8d1fd7f30052638788bc9b5", size = 182096, upload-time = "2025-03-05T20:02:24.368Z" },
+    { url = "https://files.pythonhosted.org/packages/14/8f/aa61f528fba38578ec553c145857a181384c72b98156f858ca5c8e82d9d3/websockets-15.0.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:64dee438fed052b52e4f98f76c5790513235efaa1ef7f3f2192c392cd7c91b65", size = 182523, upload-time = "2025-03-05T20:02:25.669Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/6d/0267396610add5bc0d0d3e77f546d4cd287200804fe02323797de77dbce9/websockets-15.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:d5f6b181bb38171a8ad1d6aa58a67a6aa9d4b38d0f8c5f496b9e42561dfc62fe", size = 182790, upload-time = "2025-03-05T20:02:26.99Z" },
+    { url = "https://files.pythonhosted.org/packages/02/05/c68c5adbf679cf610ae2f74a9b871ae84564462955d991178f95a1ddb7dd/websockets-15.0.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:5d54b09eba2bada6011aea5375542a157637b91029687eb4fdb2dab11059c1b4", size = 182165, upload-time = "2025-03-05T20:02:30.291Z" },
+    { url = "https://files.pythonhosted.org/packages/29/93/bb672df7b2f5faac89761cb5fa34f5cec45a4026c383a4b5761c6cea5c16/websockets-15.0.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3be571a8b5afed347da347bfcf27ba12b069d9d7f42cb8c7028b5e98bbb12597", size = 182160, upload-time = "2025-03-05T20:02:31.634Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/83/de1f7709376dc3ca9b7eeb4b9a07b4526b14876b6d372a4dc62312bebee0/websockets-15.0.1-cp312-cp312-win32.whl", hash = "sha256:c338ffa0520bdb12fbc527265235639fb76e7bc7faafbb93f6ba80d9c06578a9", size = 176395, upload-time = "2025-03-05T20:02:33.017Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/71/abf2ebc3bbfa40f391ce1428c7168fb20582d0ff57019b69ea20fa698043/websockets-15.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:fcd5cf9e305d7b8338754470cf69cf81f420459dbae8a3b40cee57417f4614a7", size = 176841, upload-time = "2025-03-05T20:02:34.498Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/9f/51f0cf64471a9d2b4d0fc6c534f323b664e7095640c34562f5182e5a7195/websockets-15.0.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:ee443ef070bb3b6ed74514f5efaa37a252af57c90eb33b956d35c8e9c10a1931", size = 175440, upload-time = "2025-03-05T20:02:36.695Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/05/aa116ec9943c718905997412c5989f7ed671bc0188ee2ba89520e8765d7b/websockets-15.0.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5a939de6b7b4e18ca683218320fc67ea886038265fd1ed30173f5ce3f8e85675", size = 173098, upload-time = "2025-03-05T20:02:37.985Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/0b/33cef55ff24f2d92924923c99926dcce78e7bd922d649467f0eda8368923/websockets-15.0.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:746ee8dba912cd6fc889a8147168991d50ed70447bf18bcda7039f7d2e3d9151", size = 173329, upload-time = "2025-03-05T20:02:39.298Z" },
+    { url = "https://files.pythonhosted.org/packages/31/1d/063b25dcc01faa8fada1469bdf769de3768b7044eac9d41f734fd7b6ad6d/websockets-15.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:595b6c3969023ecf9041b2936ac3827e4623bfa3ccf007575f04c5a6aa318c22", size = 183111, upload-time = "2025-03-05T20:02:40.595Z" },
+    { url = "https://files.pythonhosted.org/packages/93/53/9a87ee494a51bf63e4ec9241c1ccc4f7c2f45fff85d5bde2ff74fcb68b9e/websockets-15.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3c714d2fc58b5ca3e285461a4cc0c9a66bd0e24c5da9911e30158286c9b5be7f", size = 182054, upload-time = "2025-03-05T20:02:41.926Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/b2/83a6ddf56cdcbad4e3d841fcc55d6ba7d19aeb89c50f24dd7e859ec0805f/websockets-15.0.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f3c1e2ab208db911594ae5b4f79addeb3501604a165019dd221c0bdcabe4db8", size = 182496, upload-time = "2025-03-05T20:02:43.304Z" },
+    { url = "https://files.pythonhosted.org/packages/98/41/e7038944ed0abf34c45aa4635ba28136f06052e08fc2168520bb8b25149f/websockets-15.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:229cf1d3ca6c1804400b0a9790dc66528e08a6a1feec0d5040e8b9eb14422375", size = 182829, upload-time = "2025-03-05T20:02:48.812Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/17/de15b6158680c7623c6ef0db361da965ab25d813ae54fcfeae2e5b9ef910/websockets-15.0.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:756c56e867a90fb00177d530dca4b097dd753cde348448a1012ed6c5131f8b7d", size = 182217, upload-time = "2025-03-05T20:02:50.14Z" },
+    { url = "https://files.pythonhosted.org/packages/33/2b/1f168cb6041853eef0362fb9554c3824367c5560cbdaad89ac40f8c2edfc/websockets-15.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:558d023b3df0bffe50a04e710bc87742de35060580a293c2a984299ed83bc4e4", size = 182195, upload-time = "2025-03-05T20:02:51.561Z" },
+    { url = "https://files.pythonhosted.org/packages/86/eb/20b6cdf273913d0ad05a6a14aed4b9a85591c18a987a3d47f20fa13dcc47/websockets-15.0.1-cp313-cp313-win32.whl", hash = "sha256:ba9e56e8ceeeedb2e080147ba85ffcd5cd0711b89576b83784d8605a7df455fa", size = 176393, upload-time = "2025-03-05T20:02:53.814Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/6c/c65773d6cab416a64d191d6ee8a8b1c68a09970ea6909d16965d26bfed1e/websockets-15.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:e09473f095a819042ecb2ab9465aee615bd9c2028e4ef7d933600a8401c79561", size = 176837, upload-time = "2025-03-05T20:02:55.237Z" },
+    { url = "https://files.pythonhosted.org/packages/02/9e/d40f779fa16f74d3468357197af8d6ad07e7c5a27ea1ca74ceb38986f77a/websockets-15.0.1-pp310-pypy310_pp73-macosx_10_15_x86_64.whl", hash = "sha256:0c9e74d766f2818bb95f84c25be4dea09841ac0f734d1966f415e4edfc4ef1c3", size = 173109, upload-time = "2025-03-05T20:03:17.769Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/cd/5b887b8585a593073fd92f7c23ecd3985cd2c3175025a91b0d69b0551372/websockets-15.0.1-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:1009ee0c7739c08a0cd59de430d6de452a55e42d6b522de7aa15e6f67db0b8e1", size = 173343, upload-time = "2025-03-05T20:03:19.094Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/ae/d34f7556890341e900a95acf4886833646306269f899d58ad62f588bf410/websockets-15.0.1-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:76d1f20b1c7a2fa82367e04982e708723ba0e7b8d43aa643d3dcd404d74f1475", size = 174599, upload-time = "2025-03-05T20:03:21.1Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e6/5fd43993a87db364ec60fc1d608273a1a465c0caba69176dd160e197ce42/websockets-15.0.1-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f29d80eb9a9263b8d109135351caf568cc3f80b9928bccde535c235de55c22d9", size = 174207, upload-time = "2025-03-05T20:03:23.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/fb/c492d6daa5ec067c2988ac80c61359ace5c4c674c532985ac5a123436cec/websockets-15.0.1-pp310-pypy310_pp73-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b359ed09954d7c18bbc1680f380c7301f92c60bf924171629c5db97febb12f04", size = 174155, upload-time = "2025-03-05T20:03:25.321Z" },
+    { url = "https://files.pythonhosted.org/packages/68/a1/dcb68430b1d00b698ae7a7e0194433bce4f07ded185f0ee5fb21e2a2e91e/websockets-15.0.1-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:cad21560da69f4ce7658ca2cb83138fb4cf695a2ba3e475e0559e05991aa8122", size = 176884, upload-time = "2025-03-05T20:03:27.934Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/a8/5b41e0da817d64113292ab1f8247140aac61cbf6cfd085d6a0fa77f4984f/websockets-15.0.1-py3-none-any.whl", hash = "sha256:f7a866fbc1e97b5c617ee4116daaa09b722101d4a3c170c787450ba409f9736f", size = 169743, upload-time = "2025-03-05T20:03:39.41Z" },
+]
+
+[[package]]
+name = "wrapt"
+version = "1.17.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/8f/aeb76c5b46e273670962298c23e7ddde79916cb74db802131d49a85e4b7d/wrapt-1.17.3.tar.gz", hash = "sha256:f66eb08feaa410fe4eebd17f2a2c8e2e46d3476e9f8c783daa8e09e0faa666d0", size = 55547, upload-time = "2025-08-12T05:53:21.714Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3f/23/bb82321b86411eb51e5a5db3fb8f8032fd30bd7c2d74bfe936136b2fa1d6/wrapt-1.17.3-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:88bbae4d40d5a46142e70d58bf664a89b6b4befaea7b2ecc14e03cedb8e06c04", size = 53482, upload-time = "2025-08-12T05:51:44.467Z" },
+    { url = "https://files.pythonhosted.org/packages/45/69/f3c47642b79485a30a59c63f6d739ed779fb4cc8323205d047d741d55220/wrapt-1.17.3-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e6b13af258d6a9ad602d57d889f83b9d5543acd471eee12eb51f5b01f8eb1bc2", size = 38676, upload-time = "2025-08-12T05:51:32.636Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/71/e7e7f5670c1eafd9e990438e69d8fb46fa91a50785332e06b560c869454f/wrapt-1.17.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:fd341868a4b6714a5962c1af0bd44f7c404ef78720c7de4892901e540417111c", size = 38957, upload-time = "2025-08-12T05:51:54.655Z" },
+    { url = "https://files.pythonhosted.org/packages/de/17/9f8f86755c191d6779d7ddead1a53c7a8aa18bccb7cea8e7e72dfa6a8a09/wrapt-1.17.3-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:f9b2601381be482f70e5d1051a5965c25fb3625455a2bf520b5a077b22afb775", size = 81975, upload-time = "2025-08-12T05:52:30.109Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/15/dd576273491f9f43dd09fce517f6c2ce6eb4fe21681726068db0d0467096/wrapt-1.17.3-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:343e44b2a8e60e06a7e0d29c1671a0d9951f59174f3709962b5143f60a2a98bd", size = 83149, upload-time = "2025-08-12T05:52:09.316Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/c4/5eb4ce0d4814521fee7aa806264bf7a114e748ad05110441cd5b8a5c744b/wrapt-1.17.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:33486899acd2d7d3066156b03465b949da3fd41a5da6e394ec49d271baefcf05", size = 82209, upload-time = "2025-08-12T05:52:10.331Z" },
+    { url = "https://files.pythonhosted.org/packages/31/4b/819e9e0eb5c8dc86f60dfc42aa4e2c0d6c3db8732bce93cc752e604bb5f5/wrapt-1.17.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:e6f40a8aa5a92f150bdb3e1c44b7e98fb7113955b2e5394122fa5532fec4b418", size = 81551, upload-time = "2025-08-12T05:52:31.137Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/83/ed6baf89ba3a56694700139698cf703aac9f0f9eb03dab92f57551bd5385/wrapt-1.17.3-cp310-cp310-win32.whl", hash = "sha256:a36692b8491d30a8c75f1dfee65bef119d6f39ea84ee04d9f9311f83c5ad9390", size = 36464, upload-time = "2025-08-12T05:53:01.204Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/90/ee61d36862340ad7e9d15a02529df6b948676b9a5829fd5e16640156627d/wrapt-1.17.3-cp310-cp310-win_amd64.whl", hash = "sha256:afd964fd43b10c12213574db492cb8f73b2f0826c8df07a68288f8f19af2ebe6", size = 38748, upload-time = "2025-08-12T05:53:00.209Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/c3/cefe0bd330d389c9983ced15d326f45373f4073c9f4a8c2f99b50bfea329/wrapt-1.17.3-cp310-cp310-win_arm64.whl", hash = "sha256:af338aa93554be859173c39c85243970dc6a289fa907402289eeae7543e1ae18", size = 36810, upload-time = "2025-08-12T05:52:51.906Z" },
+    { url = "https://files.pythonhosted.org/packages/52/db/00e2a219213856074a213503fdac0511203dceefff26e1daa15250cc01a0/wrapt-1.17.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:273a736c4645e63ac582c60a56b0acb529ef07f78e08dc6bfadf6a46b19c0da7", size = 53482, upload-time = "2025-08-12T05:51:45.79Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/30/ca3c4a5eba478408572096fe9ce36e6e915994dd26a4e9e98b4f729c06d9/wrapt-1.17.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5531d911795e3f935a9c23eb1c8c03c211661a5060aab167065896bbf62a5f85", size = 38674, upload-time = "2025-08-12T05:51:34.629Z" },
+    { url = "https://files.pythonhosted.org/packages/31/25/3e8cc2c46b5329c5957cec959cb76a10718e1a513309c31399a4dad07eb3/wrapt-1.17.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:0610b46293c59a3adbae3dee552b648b984176f8562ee0dba099a56cfbe4df1f", size = 38959, upload-time = "2025-08-12T05:51:56.074Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/8f/a32a99fc03e4b37e31b57cb9cefc65050ea08147a8ce12f288616b05ef54/wrapt-1.17.3-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b32888aad8b6e68f83a8fdccbf3165f5469702a7544472bdf41f582970ed3311", size = 82376, upload-time = "2025-08-12T05:52:32.134Z" },
+    { url = "https://files.pythonhosted.org/packages/31/57/4930cb8d9d70d59c27ee1332a318c20291749b4fba31f113c2f8ac49a72e/wrapt-1.17.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cccf4f81371f257440c88faed6b74f1053eef90807b77e31ca057b2db74edb1", size = 83604, upload-time = "2025-08-12T05:52:11.663Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/f3/1afd48de81d63dd66e01b263a6fbb86e1b5053b419b9b33d13e1f6d0f7d0/wrapt-1.17.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d8a210b158a34164de8bb68b0e7780041a903d7b00c87e906fb69928bf7890d5", size = 82782, upload-time = "2025-08-12T05:52:12.626Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/d7/4ad5327612173b144998232f98a85bb24b60c352afb73bc48e3e0d2bdc4e/wrapt-1.17.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:79573c24a46ce11aab457b472efd8d125e5a51da2d1d24387666cd85f54c05b2", size = 82076, upload-time = "2025-08-12T05:52:33.168Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/59/e0adfc831674a65694f18ea6dc821f9fcb9ec82c2ce7e3d73a88ba2e8718/wrapt-1.17.3-cp311-cp311-win32.whl", hash = "sha256:c31eebe420a9a5d2887b13000b043ff6ca27c452a9a22fa71f35f118e8d4bf89", size = 36457, upload-time = "2025-08-12T05:53:03.936Z" },
+    { url = "https://files.pythonhosted.org/packages/83/88/16b7231ba49861b6f75fc309b11012ede4d6b0a9c90969d9e0db8d991aeb/wrapt-1.17.3-cp311-cp311-win_amd64.whl", hash = "sha256:0b1831115c97f0663cb77aa27d381237e73ad4f721391a9bfb2fe8bc25fa6e77", size = 38745, upload-time = "2025-08-12T05:53:02.885Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/1e/c4d4f3398ec073012c51d1c8d87f715f56765444e1a4b11e5180577b7e6e/wrapt-1.17.3-cp311-cp311-win_arm64.whl", hash = "sha256:5a7b3c1ee8265eb4c8f1b7d29943f195c00673f5ab60c192eba2d4a7eae5f46a", size = 36806, upload-time = "2025-08-12T05:52:53.368Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/41/cad1aba93e752f1f9268c77270da3c469883d56e2798e7df6240dcb2287b/wrapt-1.17.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab232e7fdb44cdfbf55fc3afa31bcdb0d8980b9b95c38b6405df2acb672af0e0", size = 53998, upload-time = "2025-08-12T05:51:47.138Z" },
+    { url = "https://files.pythonhosted.org/packages/60/f8/096a7cc13097a1869fe44efe68dace40d2a16ecb853141394047f0780b96/wrapt-1.17.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:9baa544e6acc91130e926e8c802a17f3b16fbea0fd441b5a60f5cf2cc5c3deba", size = 39020, upload-time = "2025-08-12T05:51:35.906Z" },
+    { url = "https://files.pythonhosted.org/packages/33/df/bdf864b8997aab4febb96a9ae5c124f700a5abd9b5e13d2a3214ec4be705/wrapt-1.17.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6b538e31eca1a7ea4605e44f81a48aa24c4632a277431a6ed3f328835901f4fd", size = 39098, upload-time = "2025-08-12T05:51:57.474Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/81/5d931d78d0eb732b95dc3ddaeeb71c8bb572fb01356e9133916cd729ecdd/wrapt-1.17.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:042ec3bb8f319c147b1301f2393bc19dba6e176b7da446853406d041c36c7828", size = 88036, upload-time = "2025-08-12T05:52:34.784Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/38/2e1785df03b3d72d34fc6252d91d9d12dc27a5c89caef3335a1bbb8908ca/wrapt-1.17.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3af60380ba0b7b5aeb329bc4e402acd25bd877e98b3727b0135cb5c2efdaefe9", size = 88156, upload-time = "2025-08-12T05:52:13.599Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/8b/48cdb60fe0603e34e05cffda0b2a4adab81fd43718e11111a4b0100fd7c1/wrapt-1.17.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0b02e424deef65c9f7326d8c19220a2c9040c51dc165cddb732f16198c168396", size = 87102, upload-time = "2025-08-12T05:52:14.56Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/51/d81abca783b58f40a154f1b2c56db1d2d9e0d04fa2d4224e357529f57a57/wrapt-1.17.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:74afa28374a3c3a11b3b5e5fca0ae03bef8450d6aa3ab3a1e2c30e3a75d023dc", size = 87732, upload-time = "2025-08-12T05:52:36.165Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/b1/43b286ca1392a006d5336412d41663eeef1ad57485f3e52c767376ba7e5a/wrapt-1.17.3-cp312-cp312-win32.whl", hash = "sha256:4da9f45279fff3543c371d5ababc57a0384f70be244de7759c85a7f989cb4ebe", size = 36705, upload-time = "2025-08-12T05:53:07.123Z" },
+    { url = "https://files.pythonhosted.org/packages/28/de/49493f962bd3c586ab4b88066e967aa2e0703d6ef2c43aa28cb83bf7b507/wrapt-1.17.3-cp312-cp312-win_amd64.whl", hash = "sha256:e71d5c6ebac14875668a1e90baf2ea0ef5b7ac7918355850c0908ae82bcb297c", size = 38877, upload-time = "2025-08-12T05:53:05.436Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/48/0f7102fe9cb1e8a5a77f80d4f0956d62d97034bbe88d33e94699f99d181d/wrapt-1.17.3-cp312-cp312-win_arm64.whl", hash = "sha256:604d076c55e2fdd4c1c03d06dc1a31b95130010517b5019db15365ec4a405fc6", size = 36885, upload-time = "2025-08-12T05:52:54.367Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/f6/759ece88472157acb55fc195e5b116e06730f1b651b5b314c66291729193/wrapt-1.17.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a47681378a0439215912ef542c45a783484d4dd82bac412b71e59cf9c0e1cea0", size = 54003, upload-time = "2025-08-12T05:51:48.627Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/a9/49940b9dc6d47027dc850c116d79b4155f15c08547d04db0f07121499347/wrapt-1.17.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:54a30837587c6ee3cd1a4d1c2ec5d24e77984d44e2f34547e2323ddb4e22eb77", size = 39025, upload-time = "2025-08-12T05:51:37.156Z" },
+    { url = "https://files.pythonhosted.org/packages/45/35/6a08de0f2c96dcdd7fe464d7420ddb9a7655a6561150e5fc4da9356aeaab/wrapt-1.17.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:16ecf15d6af39246fe33e507105d67e4b81d8f8d2c6598ff7e3ca1b8a37213f7", size = 39108, upload-time = "2025-08-12T05:51:58.425Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/37/6faf15cfa41bf1f3dba80cd3f5ccc6622dfccb660ab26ed79f0178c7497f/wrapt-1.17.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6fd1ad24dc235e4ab88cda009e19bf347aabb975e44fd5c2fb22a3f6e4141277", size = 88072, upload-time = "2025-08-12T05:52:37.53Z" },
+    { url = "https://files.pythonhosted.org/packages/78/f2/efe19ada4a38e4e15b6dff39c3e3f3f73f5decf901f66e6f72fe79623a06/wrapt-1.17.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ed61b7c2d49cee3c027372df5809a59d60cf1b6c2f81ee980a091f3afed6a2d", size = 88214, upload-time = "2025-08-12T05:52:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/40/90/ca86701e9de1622b16e09689fc24b76f69b06bb0150990f6f4e8b0eeb576/wrapt-1.17.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:423ed5420ad5f5529db9ce89eac09c8a2f97da18eb1c870237e84c5a5c2d60aa", size = 87105, upload-time = "2025-08-12T05:52:17.914Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/e0/d10bd257c9a3e15cbf5523025252cc14d77468e8ed644aafb2d6f54cb95d/wrapt-1.17.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e01375f275f010fcbf7f643b4279896d04e571889b8a5b3f848423d91bf07050", size = 87766, upload-time = "2025-08-12T05:52:39.243Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/cf/7d848740203c7b4b27eb55dbfede11aca974a51c3d894f6cc4b865f42f58/wrapt-1.17.3-cp313-cp313-win32.whl", hash = "sha256:53e5e39ff71b3fc484df8a522c933ea2b7cdd0d5d15ae82e5b23fde87d44cbd8", size = 36711, upload-time = "2025-08-12T05:53:10.074Z" },
+    { url = "https://files.pythonhosted.org/packages/57/54/35a84d0a4d23ea675994104e667ceff49227ce473ba6a59ba2c84f250b74/wrapt-1.17.3-cp313-cp313-win_amd64.whl", hash = "sha256:1f0b2f40cf341ee8cc1a97d51ff50dddb9fcc73241b9143ec74b30fc4f44f6cb", size = 38885, upload-time = "2025-08-12T05:53:08.695Z" },
+    { url = "https://files.pythonhosted.org/packages/01/77/66e54407c59d7b02a3c4e0af3783168fff8e5d61def52cda8728439d86bc/wrapt-1.17.3-cp313-cp313-win_arm64.whl", hash = "sha256:7425ac3c54430f5fc5e7b6f41d41e704db073309acfc09305816bc6a0b26bb16", size = 36896, upload-time = "2025-08-12T05:52:55.34Z" },
+    { url = "https://files.pythonhosted.org/packages/02/a2/cd864b2a14f20d14f4c496fab97802001560f9f41554eef6df201cd7f76c/wrapt-1.17.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cf30f6e3c077c8e6a9a7809c94551203c8843e74ba0c960f4a98cd80d4665d39", size = 54132, upload-time = "2025-08-12T05:51:49.864Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/46/d011725b0c89e853dc44cceb738a307cde5d240d023d6d40a82d1b4e1182/wrapt-1.17.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e228514a06843cae89621384cfe3a80418f3c04aadf8a3b14e46a7be704e4235", size = 39091, upload-time = "2025-08-12T05:51:38.935Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/9e/3ad852d77c35aae7ddebdbc3b6d35ec8013af7d7dddad0ad911f3d891dae/wrapt-1.17.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:5ea5eb3c0c071862997d6f3e02af1d055f381b1d25b286b9d6644b79db77657c", size = 39172, upload-time = "2025-08-12T05:51:59.365Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f7/c983d2762bcce2326c317c26a6a1e7016f7eb039c27cdf5c4e30f4160f31/wrapt-1.17.3-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:281262213373b6d5e4bb4353bc36d1ba4084e6d6b5d242863721ef2bf2c2930b", size = 87163, upload-time = "2025-08-12T05:52:40.965Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/0f/f673f75d489c7f22d17fe0193e84b41540d962f75fce579cf6873167c29b/wrapt-1.17.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc4a8d2b25efb6681ecacad42fca8859f88092d8732b170de6a5dddd80a1c8fa", size = 87963, upload-time = "2025-08-12T05:52:20.326Z" },
+    { url = "https://files.pythonhosted.org/packages/df/61/515ad6caca68995da2fac7a6af97faab8f78ebe3bf4f761e1b77efbc47b5/wrapt-1.17.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:373342dd05b1d07d752cecbec0c41817231f29f3a89aa8b8843f7b95992ed0c7", size = 86945, upload-time = "2025-08-12T05:52:21.581Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/bd/4e70162ce398462a467bc09e768bee112f1412e563620adc353de9055d33/wrapt-1.17.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d40770d7c0fd5cbed9d84b2c3f2e156431a12c9a37dc6284060fb4bec0b7ffd4", size = 86857, upload-time = "2025-08-12T05:52:43.043Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/b8/da8560695e9284810b8d3df8a19396a6e40e7518059584a1a394a2b35e0a/wrapt-1.17.3-cp314-cp314-win32.whl", hash = "sha256:fbd3c8319de8e1dc79d346929cd71d523622da527cca14e0c1d257e31c2b8b10", size = 37178, upload-time = "2025-08-12T05:53:12.605Z" },
+    { url = "https://files.pythonhosted.org/packages/db/c8/b71eeb192c440d67a5a0449aaee2310a1a1e8eca41676046f99ed2487e9f/wrapt-1.17.3-cp314-cp314-win_amd64.whl", hash = "sha256:e1a4120ae5705f673727d3253de3ed0e016f7cd78dc463db1b31e2463e1f3cf6", size = 39310, upload-time = "2025-08-12T05:53:11.106Z" },
+    { url = "https://files.pythonhosted.org/packages/45/20/2cda20fd4865fa40f86f6c46ed37a2a8356a7a2fde0773269311f2af56c7/wrapt-1.17.3-cp314-cp314-win_arm64.whl", hash = "sha256:507553480670cab08a800b9463bdb881b2edeed77dc677b0a5915e6106e91a58", size = 37266, upload-time = "2025-08-12T05:52:56.531Z" },
+    { url = "https://files.pythonhosted.org/packages/77/ed/dd5cf21aec36c80443c6f900449260b80e2a65cf963668eaef3b9accce36/wrapt-1.17.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:ed7c635ae45cfbc1a7371f708727bf74690daedc49b4dba310590ca0bd28aa8a", size = 56544, upload-time = "2025-08-12T05:51:51.109Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/96/450c651cc753877ad100c7949ab4d2e2ecc4d97157e00fa8f45df682456a/wrapt-1.17.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:249f88ed15503f6492a71f01442abddd73856a0032ae860de6d75ca62eed8067", size = 40283, upload-time = "2025-08-12T05:51:39.912Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/86/2fcad95994d9b572db57632acb6f900695a648c3e063f2cd344b3f5c5a37/wrapt-1.17.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5a03a38adec8066d5a37bea22f2ba6bbf39fcdefbe2d91419ab864c3fb515454", size = 40366, upload-time = "2025-08-12T05:52:00.693Z" },
+    { url = "https://files.pythonhosted.org/packages/64/0e/f4472f2fdde2d4617975144311f8800ef73677a159be7fe61fa50997d6c0/wrapt-1.17.3-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:5d4478d72eb61c36e5b446e375bbc49ed002430d17cdec3cecb36993398e1a9e", size = 108571, upload-time = "2025-08-12T05:52:44.521Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/01/9b85a99996b0a97c8a17484684f206cbb6ba73c1ce6890ac668bcf3838fb/wrapt-1.17.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:223db574bb38637e8230eb14b185565023ab624474df94d2af18f1cdb625216f", size = 113094, upload-time = "2025-08-12T05:52:22.618Z" },
+    { url = "https://files.pythonhosted.org/packages/25/02/78926c1efddcc7b3aa0bc3d6b33a822f7d898059f7cd9ace8c8318e559ef/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e405adefb53a435f01efa7ccdec012c016b5a1d3f35459990afc39b6be4d5056", size = 110659, upload-time = "2025-08-12T05:52:24.057Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/ee/c414501ad518ac3e6fe184753632fe5e5ecacdcf0effc23f31c1e4f7bfcf/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:88547535b787a6c9ce4086917b6e1d291aa8ed914fdd3a838b3539dc95c12804", size = 106946, upload-time = "2025-08-12T05:52:45.976Z" },
+    { url = "https://files.pythonhosted.org/packages/be/44/a1bd64b723d13bb151d6cc91b986146a1952385e0392a78567e12149c7b4/wrapt-1.17.3-cp314-cp314t-win32.whl", hash = "sha256:41b1d2bc74c2cac6f9074df52b2efbef2b30bdfe5f40cb78f8ca22963bc62977", size = 38717, upload-time = "2025-08-12T05:53:15.214Z" },
+    { url = "https://files.pythonhosted.org/packages/79/d9/7cfd5a312760ac4dd8bf0184a6ee9e43c33e47f3dadc303032ce012b8fa3/wrapt-1.17.3-cp314-cp314t-win_amd64.whl", hash = "sha256:73d496de46cd2cdbdbcce4ae4bcdb4afb6a11234a1df9c085249d55166b95116", size = 41334, upload-time = "2025-08-12T05:53:14.178Z" },
+    { url = "https://files.pythonhosted.org/packages/46/78/10ad9781128ed2f99dbc474f43283b13fea8ba58723e98844367531c18e9/wrapt-1.17.3-cp314-cp314t-win_arm64.whl", hash = "sha256:f38e60678850c42461d4202739f9bf1e3a737c7ad283638251e79cc49effb6b6", size = 38471, upload-time = "2025-08-12T05:52:57.784Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f6/a933bd70f98e9cf3e08167fc5cd7aaaca49147e48411c0bd5ae701bb2194/wrapt-1.17.3-py3-none-any.whl", hash = "sha256:7171ae35d2c33d326ac19dd8facb1e82e5fd04ef8c6c0e394d7af55a55051c22", size = 23591, upload-time = "2025-08-12T05:53:20.674Z" },
+]
+
+[[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 000000000..f45cca688
--- /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 000000000..bd1185f29
--- /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 000000000..0d5519aa3
--- /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 000000000..896164daa
--- /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 000000000..5f53e3c7f
--- /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/justfile b/justfile
new file mode 100644
index 000000000..28f56c2e0
--- /dev/null
+++ b/justfile
@@ -0,0 +1,33 @@
+# 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 . --refresh-package mdxify mdxify@latest --all --root-module fastmcp --anchor-name "Python SDK" --exclude fastmcp.contrib
+# Generate API reference for specific modules (e.g., just api-ref prefect.flows prefect.tasks)
+api-ref *MODULES:
+    uvx --with-editable . --refresh-package mdxify mdxify@latest {{MODULES}} --root-module fastmcp --anchor-name "Python SDK"
+
+# Clean up API reference documentation
+api-ref-clean:
+    rm -rf docs/python-sdk
+
+copy-context:
+    uvx --with-editable . --refresh-package copychat copychat@latest src/ docs/ -x changelog.mdx -x python-sdk/ -v
\ No newline at end of file
diff --git a/logo.py b/logo.py
new file mode 100644
index 000000000..4a887d8e4
--- /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 000000000..0fffe3d5c
--- /dev/null
+++ b/loq.toml
@@ -0,0 +1,31 @@
+# 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/**", "docs/**"]
+
+[[rules]]
+path = "tests/**"
+max_lines = 1000
+
+[[rules]]
+path = "src/fastmcp/server/context.py"
+max_lines = 1272
+
+[[rules]]
+path = "src/fastmcp/server/server.py"
+max_lines = 3250
+
+[[rules]]
+path = "src/fastmcp/client/client.py"
+max_lines = 1885
+
+[[rules]]
+path = "src/fastmcp/server/auth/oauth_proxy/proxy.py"
+max_lines = 1796
+
+[[rules]]
+path = "src/fastmcp/server/providers/local_provider.py"
+max_lines = 1187
diff --git a/pyproject.toml b/pyproject.toml
index ca524787b..320938b2e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,38 +1,200 @@
 [project]
 name = "fastmcp"
 dynamic = ["version"]
-description = "A more ergonomic interface for MCP servers"
+description = "The fast, Pythonic way to build MCP servers and clients."
 authors = [{ name = "Jeremiah Lowin" }]
 dependencies = [
-    "httpx>=0.26.0",
-    "mcp>=1.0.0",
-    "pydantic-settings>=2.6.1",
-    "pydantic>=2.5.3",
-    "typer>=0.9.0",
+    "python-dotenv>=1.1.0",
+    "exceptiongroup>=1.2.2",
+    "httpx>=0.28.1,<1.0",
+    "mcp>=1.24.0,<2.0",
+    "openapi-pydantic>=0.5.1",
+    "opentelemetry-api>=1.20.0",
+    "packaging>=24.0",
+    "platformdirs>=4.0.0",
+    "rich>=13.9.4",
+    "cyclopts>=4.0.0",
+    "authlib>=1.6.5",
+    "pydantic[email]>=2.11.7",
+    "pyyaml>=6.0,<7.0",
+    "pyperclip>=1.9.0",
+    "py-key-value-aio[filetree,keyring,memory]>=0.4.4,<0.5.0",
+    "uvicorn>=0.35",
+    "websockets>=15.0.1",
+    "jsonschema-path>=0.3.4",
+    "jsonref>=1.1.0",
+    "uncalled-for>=0.2.0",
+    "watchfiles>=1.0.0",
 ]
+
 requires-python = ">=3.10"
 readme = "README.md"
-license = { text = "Apache-2.0" }
+license = "Apache-2.0"
 
-[project.scripts]
-fastmcp = "fastmcp.cli:app"
-
-[build-system]
-requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
-build-backend = "setuptools.build_meta"
+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",
+]
 
-[tool.setuptools_scm]
-write_to = "src/fastmcp/_version.py"
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40.0"]
+apps = ["prefab-ui>=0.6.0"]
+azure = ["azure-identity>=1.16.0"]
+code-mode = ["pydantic-monty>=0.0.7"]
+gemini = ["google-genai>=1.18.0"]
+openai = ["openai>=1.102.0"]
+tasks = ["pydocket>=0.18.0"]
 
 [dependency-groups]
 dev = [
-    "copychat>=0.5.2",
+    "dirty-equals>=0.9.0",
+    "fastmcp[anthropic,apps,azure,code-mode,gemini,openai,tasks]",
+    # add optional dependencies for fastmcp dev
+    "fastapi>=0.115.12",
+    "opentelemetry-sdk>=1.20.0",
+    "inline-snapshot[dirty-equals]>=0.27.2",
     "ipython>=8.12.3",
-    "pdbpp>=0.10.3",
-    "pytest-xdist>=3.6.1",
+    "pdbpp>=0.11.7",
+    "psutil>=7.0.0",
+    "pyinstrument>=5.0.2",
+    "pyperclip>=1.9.0",
     "pytest>=8.3.3",
-    "pytest-asyncio>=0.23.5",
+    "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.20",
+    "prek>=0.2.12",
+    "loq>=0.1.0a3",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.39.0",
 ]
 
+[project.scripts]
+fastmcp = "fastmcp.cli:app"
+
+[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.metadata]
+allow-direct-references = true
+
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# filterwarnings = ["error::DeprecationWarning"]
+filterwarnings = [
+    # Suppress OAuth in-memory token storage warnings in tests
+    # Tests intentionally use ephemeral storage; this warning is for end users
+    "ignore:Using in-memory token storage:UserWarning",
+    # Treat unawaited coroutine warnings as errors - these are almost always bugs
+    "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.",
+]
+# Automatically mark all tests in integration_tests folder
+pythonpath = ["."]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["--inline-snapshot=disable"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+exclude = ["**/node_modules", "**/__pycache__", ".venv", ".git", "dist"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.rules]
+# NOTE: ty currently doesn't support type narrowing with isinstance() on unions
+# See: https://github.com/astral-sh/ty/issues/122 and https://github.com/astral-sh/ty/issues/1113
+# Some code uses `# ty: ignore[invalid-argument-type]` for this limitation.
+# TODO: Remove these ignores once ty supports union narrowing
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+ignore = [
+    "COM812",
+    "PLR0913", # Too many arguments, MCP Servers have a lot of arguments, OKAY?!
+    "SIM102",  # Dont require combining if statements
+]
+extend-select = [
+    "B",   # flake8-bugbear: Catches actual bugs like mutable default arguments
+    "C4",  # flake8-comprehensions: More efficient/readable comprehensions
+    "I",   # flake8-builtins: Catches builtins that are not explicitly imported
+    "PIE", # flake8-pie: More idiomatic Python code
+    "RUF", # Ruff-specific: Modern best practices unique to Ruff
+    "SIM", # flake8-simplify: Simplifies verbose code patterns
+    "UP",  # flake8-unused-imports: Catches unused imports
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fastmcp"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001", "RUF013"]
+# allow imports not at the top of the file
+"src/fastmcp/__init__.py" = ["E402"]
+"!src/**.py" = [ # Only enforce extended ruff rules for code in src/
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "PIE", # flake8-pie
+    "RUF", # Ruff-specific
+    "SIM", # flake8-simplify
+]
+
+
+[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 000000000..87965fb13
--- /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 000000000..a9185f584
--- /dev/null
+++ b/scripts/auto_close_needs_mre.py
@@ -0,0 +1,407 @@
+#!/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
+
+
+@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
+
+
+@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"),
+                    )
+                )
+
+        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."""
+    # 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 000000000..6ad1dfe57
--- /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/scripts/sync_upstream.py b/scripts/sync_upstream.py
new file mode 100644
index 000000000..7b7f032fa
--- /dev/null
+++ b/scripts/sync_upstream.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+"""
+Sync this repo with upstream fastmcp (github.com/jlowin/fastmcp).
+
+Use this to keep xsecuremcp2.0 abreast of upstream changes, then make your
+own changes and commit.
+
+Usage:
+  # From repo root (xsecuremcp2.0/):
+  uv run scripts/sync_upstream.py              # fetch + merge upstream/main
+  uv run scripts/sync_upstream.py --fetch-only # only fetch, no merge
+  uv run scripts/sync_upstream.py --rebase    # rebase on upstream/main instead of merge
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+
+def find_repo_root() -> str:
+    """Find git repo root from script location or cwd."""
+    start = os.path.dirname(os.path.abspath(__file__))
+    path = os.path.abspath(start)
+    while path != os.path.dirname(path):
+        if os.path.isdir(os.path.join(path, ".git")):
+            return path
+        path = os.path.dirname(path)
+    return os.getcwd()
+
+
+def run(cmd: list[str], cwd: str | None = None, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a git command; raise on failure if check=True."""
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        cwd=cwd or find_repo_root(),
+    )
+    if check and result.returncode != 0:
+        print(result.stderr or result.stdout, file=sys.stderr)
+        raise SystemExit(result.returncode)
+    return result
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Sync with upstream fastmcp")
+    ap.add_argument(
+        "--fetch-only",
+        action="store_true",
+        help="Only fetch from upstream, do not merge or rebase",
+    )
+    ap.add_argument(
+        "--rebase",
+        action="store_true",
+        help="Rebase current branch on upstream/main (default: merge)",
+    )
+    ap.add_argument(
+        "--branch",
+        default="main",
+        help="Upstream branch to sync from (default: main)",
+    )
+    args = ap.parse_args()
+
+    repo_root = find_repo_root()
+    print("Fetching upstream (fastmcp)...")
+    run(["git", "fetch", "upstream"], cwd=repo_root)
+
+    if args.fetch_only:
+        print("Done (fetch-only). Update with: git merge upstream/main or git rebase upstream/main")
+        return
+
+    # Ensure we're not in the middle of a rebase/merge
+    rebase_dir = os.path.join(repo_root, ".git", "rebase-merge")
+    if os.path.isdir(rebase_dir):
+        status = run(["git", "status", "--porcelain", "-b"], cwd=repo_root, check=False)
+        if "rebase" in status.stdout or "REBASE" in status.stdout:
+            print(
+                "Repository is in the middle of a rebase. Finish with:\n"
+                "  git rebase --continue   # or  git rebase --abort",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    upstream_ref = f"upstream/{args.branch}"
+    run(["git", "rev-parse", upstream_ref], cwd=repo_root)  # ensure it exists
+
+    if args.rebase:
+        print(f"Rebasing current branch on {upstream_ref}...")
+        run(["git", "rebase", upstream_ref], cwd=repo_root)
+        print("Rebase done.")
+    else:
+        print(f"Merging {upstream_ref} into current branch...")
+        run(["git", "merge", upstream_ref, "--no-edit"], cwd=repo_root)
+        print("Merge done.")
+
+    print("Sync complete. Make your changes and commit as usual.")
+
+
+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 000000000..ae66a5e31
--- /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/src/fastmcp/__init__.py b/src/fastmcp/__init__.py
index 3946cf590..a524b402c 100644
--- a/src/fastmcp/__init__.py
+++ b/src/fastmcp/__init__.py
@@ -1,2 +1,53 @@
-from .server import FastMCP
-from .tools import Image
+"""FastMCP - An ergonomic MCP interface."""
+
+import importlib
+import warnings
+from importlib.metadata import version as _version
+from typing import TYPE_CHECKING
+
+from fastmcp.settings import Settings
+from fastmcp.utilities.logging import configure_logging as _configure_logging
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client as Client
+
+settings = Settings()
+if settings.log_enabled:
+    _configure_logging(
+        level=settings.log_level,
+        enable_rich_tracebacks=settings.enable_rich_tracebacks,
+    )
+
+from fastmcp.server.server import FastMCP
+from fastmcp.server.context import Context
+import fastmcp.server
+
+__version__ = _version("fastmcp")
+
+
+# ensure deprecation warnings are displayed by default
+if settings.deprecation_warnings:
+    warnings.simplefilter("default", DeprecationWarning)
+
+
+# --- 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":
+        from fastmcp.client import Client
+
+        return Client
+    if name == "client":
+        return importlib.import_module("fastmcp.client")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "Client",
+    "Context",
+    "FastMCP",
+    "settings",
+]
diff --git a/src/fastmcp/app.py b/src/fastmcp/app.py
deleted file mode 100644
index f721416df..000000000
--- a/src/fastmcp/app.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""FastMCP CLI tools."""
-
-from .cli.cli import app
-
-if __name__ == "__main__":
-    app()
diff --git a/src/fastmcp/cli/__init__.py b/src/fastmcp/cli/__init__.py
index ea6f6f338..091667730 100644
--- a/src/fastmcp/cli/__init__.py
+++ b/src/fastmcp/cli/__init__.py
@@ -1,5 +1,3 @@
 """FastMCP CLI package."""
 
 from .cli import app
-
-__all__ = ["app"]
diff --git a/src/fastmcp/cli/__main__.py b/src/fastmcp/cli/__main__.py
new file mode 100644
index 000000000..aca24b145
--- /dev/null
+++ b/src/fastmcp/cli/__main__.py
@@ -0,0 +1,5 @@
+"""FastMCP CLI as a runnable package"""
+
+from .cli import app
+
+app()
diff --git a/src/fastmcp/cli/auth.py b/src/fastmcp/cli/auth.py
new file mode 100644
index 000000000..4ea401b04
--- /dev/null
+++ b/src/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/src/fastmcp/cli/cimd.py b/src/fastmcp/cli/cimd.py
new file mode 100644
index 000000000..d2def490c
--- /dev/null
+++ b/src/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/src/fastmcp/cli/claude.py b/src/fastmcp/cli/claude.py
deleted file mode 100644
index 998733b60..000000000
--- a/src/fastmcp/cli/claude.py
+++ /dev/null
@@ -1,109 +0,0 @@
-"""Claude app integration utilities."""
-
-import json
-import sys
-from pathlib import Path
-from typing import Optional
-
-from ..utilities.logging import get_logger
-
-logger = get_logger(__name__)
-
-
-def get_claude_config_path() -> Path | None:
-    """Get the Claude config directory based on platform."""
-    if sys.platform == "win32":
-        path = Path(Path.home(), "AppData", "Roaming", "Claude")
-    elif sys.platform == "darwin":
-        path = Path(Path.home(), "Library", "Application Support", "Claude")
-    else:
-        return None
-
-    if path.exists():
-        return path
-    return None
-
-
-def update_claude_config(
-    file: Path,
-    server_name: Optional[str] = None,
-    *,
-    with_editable: Optional[Path] = None,
-    with_packages: Optional[list[str]] = None,
-    force: bool = False,
-) -> bool:
-    """Add the MCP server to Claude's configuration.
-
-    Args:
-        file: Path to the server file
-        server_name: Optional custom name for the server. If not provided,
-                    defaults to the file stem
-        with_editable: Optional directory to install in editable mode
-        with_packages: Optional list of additional packages to install
-        force: If True, replace existing server with same name
-    """
-    config_dir = get_claude_config_path()
-    if not config_dir:
-        return False
-
-    config_file = config_dir / "claude_desktop_config.json"
-    if not config_file.exists():
-        return False
-
-    try:
-        config = json.loads(config_file.read_text())
-        if "mcpServers" not in config:
-            config["mcpServers"] = {}
-
-        # Use provided server_name or fall back to file stem
-        name = server_name or file.stem
-        if name in config["mcpServers"]:
-            if not force:
-                logger.warning(
-                    f"Server '{name}' already exists in Claude config. "
-                    "Use `--force` to replace.",
-                    extra={"config_file": str(config_file)},
-                )
-                return False
-            logger.info(
-                f"Replacing existing server '{name}' in Claude config",
-                extra={"config_file": str(config_file)},
-            )
-
-        # Build uv run command
-        args = ["run"]
-
-        if with_editable:
-            args.extend(["--with-editable", str(with_editable)])
-
-        # Always include fastmcp
-        args.extend(["--with", "fastmcp"])
-
-        # Add additional packages
-        if with_packages:
-            for pkg in with_packages:
-                if pkg:
-                    args.extend(["--with", pkg])
-
-        args.append(str(file))
-
-        config["mcpServers"][name] = {
-            "command": "uv",
-            "args": args,
-        }
-
-        config_file.write_text(json.dumps(config, indent=2))
-        logger.info(
-            f"Added server '{name}' to Claude config",
-            extra={"config_file": str(config_file)},
-        )
-        return True
-    except Exception as e:
-        logger.error(
-            "Failed to update Claude config",
-            extra={
-                "error": str(e),
-                "config_file": str(config_file),
-            },
-        )
-        return False
diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.py
index 42e63251b..68a4a4da0 100644
--- a/src/fastmcp/cli/cli.py
+++ b/src/fastmcp/cli/cli.py
@@ -1,195 +1,323 @@
-"""FastMCP CLI tools."""
+"""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 Optional, Tuple
+from typing import Annotated, Literal
 
-import typer
-from typing_extensions import Annotated
+import cyclopts
+import pyperclip
+from cyclopts import Parameter
+from rich.console import Console
+from rich.table import Table
 
-from ..utilities.logging import get_logger
-from . import claude
+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(__name__)
+logger = get_logger("cli")
+console = Console()
 
-app = typer.Typer(
+app = cyclopts.App(
     name="fastmcp",
-    help="FastMCP development tools",
-    add_completion=False,
-    no_args_is_help=True,  # Show help if no args provided
+    help="FastMCP 2.0 - The fast, Pythonic way to build MCP servers and clients.",
+    version=fastmcp.__version__,
+    # Disable automatic negative parameters by default
+    default_parameter=Parameter(negative=()),
 )
 
 
-def _build_uv_command(
-    file: Path,
-    with_editable: Optional[Path] = None,
-    with_packages: Optional[list[str]] = None,
-) -> list[str]:
-    """Build the uv run command."""
-    cmd = ["uv"]
-
-    cmd.extend(["run", "--with", "fastmcp"])
-
-    if with_editable:
-        cmd.extend(["--with-editable", str(with_editable)])
-
-    if with_packages:
-        for pkg in with_packages:
-            if pkg:
-                cmd.extend(["--with", pkg])
-
-    cmd.append(str(file))
-    return cmd
+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_file_path(file_spec: str) -> Tuple[Path, Optional[str]]:
-    """Parse a file path that may include a server object specification.
-
-    Args:
-        file_spec: Path to file, optionally with :object suffix
-
-    Returns:
-        Tuple of (file_path, server_object)
-    """
-    if ":" in file_spec:
-        file_str, server_object = file_spec.rsplit(":", 1)
-    else:
-        file_str, server_object = file_spec, None
-
-    file_path = Path(file_str).expanduser().resolve()
-    if not file_path.exists():
-        logger.error(f"File not found: {file_path}")
+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)
-    if not file_path.is_file():
-        logger.error(f"Not a file: {file_path}")
-        sys.exit(1)
-
-    return file_path, server_object
+    key, value = env_var.split("=", 1)
+    return key.strip(), value.strip()
 
 
-def _import_server(file: Path, server_object: Optional[str] = None):
-    """Import a FastMCP server from a file.
+@contextmanager
+def with_argv(args: list[str] | None):
+    """Temporarily replace sys.argv if args provided.
 
-    Args:
-        file: Path to the file
-        server_object: Optional object name in format "module:object" or just "object"
+    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.
 
-    Returns:
-        The server object
+    Args are provided without the script name, so we preserve sys.argv[0]
+    and replace the rest.
     """
-    # Import the module
-    spec = importlib.util.spec_from_file_location("server_module", file)
-    if not spec or not spec.loader:
-        logger.error("Could not load module", extra={"file": str(file)})
-        sys.exit(1)
+    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
 
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
 
-    # If no object specified, try __main__ block
-    if not server_object:
-        # Look for the most common server object names
-        for name in ["mcp", "server", "app"]:
-            if hasattr(module, name):
-                return getattr(module, name)
+@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],
+    }
 
-        logger.error(
-            f"No server object found in {file}. Please specify the object name with file:object syntax.",
-            extra={"file": str(file)},
-        )
-        sys.exit(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", " "))
 
-    # Handle module:object syntax
-    if ":" in server_object:
-        module_name, object_name = server_object.split(":", 1)
-        try:
-            server_module = importlib.import_module(module_name)
-            server = getattr(server_module, object_name, None)
-        except ImportError:
-            logger.error(
-                f"Could not import module '{module_name}'",
-                extra={"file": str(file)},
-            )
-            sys.exit(1)
+    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:
-        # Just object name
-        server = getattr(module, server_object, None)
-
-    if server is None:
-        logger.error(
-            f"Server object '{server_object}' not found",
-            extra={"file": str(file)},
-        )
-        sys.exit(1)
+        console.print(g)
 
-    return server
+        # 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]")
 
 
-@app.command()
-def version() -> None:
-    """Show the FastMCP version."""
-    try:
-        version = importlib.metadata.version("fastmcp")
-        print(f"FastMCP version {version}")
-    except importlib.metadata.PackageNotFoundError:
-        print("FastMCP version unknown (package not installed)")
-        sys.exit(1)
+# Create dev subcommand group
+dev_app = cyclopts.App(name="dev", help="Development tools for MCP servers")
 
 
-@app.command()
-def dev(
-    file_spec: str = typer.Argument(
-        ...,
-        help="Python file to run, optionally with :object suffix",
-    ),
+@dev_app.command
+async def inspector(
+    server_spec: str | None = None,
+    *,
     with_editable: Annotated[
-        Optional[Path],
-        typer.Option(
+        list[Path] | None,
+        cyclopts.Parameter(
             "--with-editable",
-            "-e",
-            help="Directory containing pyproject.toml to install in editable mode",
-            exists=True,
-            file_okay=False,
-            resolve_path=True,
+            help="Directory containing pyproject.toml to install in editable mode (can be used multiple times)",
         ),
     ] = None,
     with_packages: Annotated[
-        list[str],
-        typer.Option(
-            "--with",
-            help="Additional packages to install",
+        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 a FastMCP server with the MCP Inspector."""
-    file, server_object = _parse_file_path(file_spec)
+    """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={
-            "file": str(file),
-            "server_object": server_object,
-            "with_editable": str(with_editable) if with_editable else None,
-            "with_packages": with_packages,
+            "server_spec": server_spec,
+            "with_editable": config.environment.editable,
+            "with_packages": config.environment.dependencies,
+            "ui_port": ui_port,
+            "server_port": server_port,
         },
     )
 
     try:
-        uv_cmd = _build_uv_command(file, with_editable, with_packages)
+        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", "@modelcontextprotocol/inspector"] + uv_cmd,
+            [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(file),
+                "file": str(server_spec),
                 "error": str(e),
                 "returncode": e.returncode,
             },
@@ -197,158 +325,740 @@ def dev(
         sys.exit(e.returncode)
     except FileNotFoundError:
         logger.error(
-            "npx not found. Please install Node.js and npm.",
-            extra={"file": str(file)},
+            "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)
 
 
-@app.command()
-def run(
-    file_spec: str = typer.Argument(
-        ...,
-        help="Python file to run, optionally with :object suffix",
-    ),
+@app.command
+async def run(
+    server_spec: str | None = None,
+    *server_args: str,
     transport: Annotated[
-        Optional[str],
-        typer.Option(
-            "--transport",
-            "-t",
-            help="Transport protocol to use (stdio or sse)",
+        run_module.TransportType | None,
+        cyclopts.Parameter(
+            name=["--transport", "-t"],
+            help="Transport protocol to use",
         ),
     ] = None,
-    with_editable: Annotated[
-        Optional[Path],
-        typer.Option(
-            "--with-editable",
-            "-e",
-            help="Directory containing pyproject.toml to install in editable mode",
-            exists=True,
-            file_okay=False,
-            resolve_path=True,
+    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 a FastMCP server."""
-    file, server_object = _parse_file_path(file_spec)
+    """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:
+            ignored_options.append("--transport")
+        if host:
+            ignored_options.append("--host")
+        if port:
+            ignored_options.append("--port")
+        if path:
+            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 or config.deployment.transport
+    final_host = host or config.deployment.host
+    final_port = port or config.deployment.port
+    final_path = path or config.deployment.path
+    final_log_level = log_level or 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",
+        "Running server or client",
         extra={
-            "file": str(file),
-            "server_object": server_object,
-            "transport": transport,
-            "with_editable": str(with_editable) if with_editable else None,
+            "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 [],
         },
     )
 
-    try:
-        # Import and get server object
-        server = _import_server(file, server_object)
+    # 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:
+                    reload_cmd.extend(["--host", final_host])
+                if final_port:
+                    reload_cmd.extend(["--port", str(final_port)])
+                if final_path:
+                    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
 
-        # Run the server
-        kwargs = {}
-        if transport:
-            kwargs["transport"] = transport
+            # 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")
 
-        server.run(**kwargs)
+            if final_server_args:
+                reload_cmd.append("--")
+                reload_cmd.extend(final_server_args)
 
-    except Exception as e:
-        logger.error(
-            "Failed to run server",
-            extra={
-                "file": str(file),
-                "error": str(e),
-            },
-        )
-        sys.exit(1)
+            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:
+                inner_cmd.extend(["--host", final_host])
+            if final_port:
+                inner_cmd.extend(["--port", str(final_port)])
+            if final_path:
+                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")
+        # 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()
-def install(
-    file_spec: str = typer.Argument(
-        ...,
-        help="Python file to run, optionally with :object suffix",
-    ),
-    server_name: Annotated[
-        Optional[str],
-        typer.Option(
-            "--name",
-            "-n",
-            help="Custom name for the server (defaults to server's name attribute or file name)",
+@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,
-    with_editable: Annotated[
-        Optional[Path],
-        typer.Option(
-            "--with-editable",
-            "-e",
-            help="Directory containing pyproject.toml to install in editable mode",
-            exists=True,
-            file_okay=False,
-            resolve_path=True,
+    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],
-        typer.Option(
-            "--with",
-            help="Additional packages to install",
+        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",
         ),
-    ] = [],
-    force: Annotated[
+    ] = None,
+    with_requirements: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--with-requirements",
+            help="Requirements file to install dependencies from",
+        ),
+    ] = None,
+    skip_env: Annotated[
         bool,
-        typer.Option(
-            "--force",
-            "-f",
-            help="Replace existing server if one exists with the same name",
+        cyclopts.Parameter(
+            "--skip-env",
+            help="Skip environment configuration (for internal use when already in a uv environment)",
         ),
     ] = False,
 ) -> None:
-    """Install a FastMCP server in the Claude desktop app."""
-    file, server_object = _parse_file_path(file_spec)
+    """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(
-        "Installing server",
+        "Inspecting server",
         extra={
-            "file": str(file),
-            "server_name": server_name,
-            "server_object": server_object,
-            "with_editable": str(with_editable) if with_editable else None,
-            "with_packages": with_packages,
-            "force": force,
+            "server_spec": server_spec,
+            "format": format,
+            "output": str(output) if output else None,
         },
     )
 
-    if not claude.get_claude_config_path():
-        logger.error("Claude app not found")
+    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)
 
-    # Try to import server to get its name, but fall back to file name if dependencies missing
-    name = server_name
-    if not name:
-        try:
-            server = _import_server(file, server_object)
-            name = server.name
-        except (ImportError, ModuleNotFoundError) as e:
-            logger.debug(
-                "Could not import server (likely missing dependencies), using file name",
-                extra={"error": str(e)},
+
+# 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."
             )
-            name = file.stem
-
-    if claude.update_claude_config(
-        file,
-        name,
-        with_editable=with_editable,
-        with_packages=with_packages,
-        force=force,
-    ):
-        print(f"Successfully installed {name} in Claude app")
-    else:
-        print(f"Failed to install {name} in Claude app")
+            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/src/fastmcp/cli/client.py b/src/fastmcp/cli/client.py
new file mode 100644
index 000000000..cc43b3aff
--- /dev/null
+++ b/src/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.requestedSchema
+    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.inputSchema
+    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.outputSchema:
+        ret = _json_schema_type_to_str(tool.outputSchema)
+        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.mimeType}, ~{size} bytes][/dim]")
+        elif isinstance(block, mcp.types.AudioContent):
+            size = len(block.data) * 3 // 4
+            console.print(f"[dim][Audio: {block.mimeType}, ~{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.mimeType, "data": block.data}
+    if isinstance(block, mcp.types.AudioContent):
+        return {"type": "audio", "mimeType": block.mimeType, "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.inputSchema,
+            **({"outputSchema": t.outputSchema} if t.outputSchema 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.inputSchema)
+
+    required = set(tool.inputSchema.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.mimeType,
+                        "text": block.text,
+                    }
+                )
+            elif isinstance(block, mcp.types.BlobResourceContents):
+                data.append(
+                    {
+                        "uri": str(block.uri),
+                        "mimeType": block.mimeType,
+                        "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.mimeType}, ~{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.mimeType}, ~{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.mimeType,
+                        }
+                        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.inputSchema)
+                    if output_schema and tool.outputSchema:
+                        _print_schema("Output", tool.outputSchema)
+                    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/src/fastmcp/cli/discovery.py b/src/fastmcp/cli/discovery.py
new file mode 100644
index 000000000..5acd42d61
--- /dev/null
+++ b/src/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/src/fastmcp/cli/generate.py b/src/fastmcp/cli/generate.py
new file mode 100644
index 000000000..b5e652909
--- /dev/null
+++ b/src/fastmcp/cli/generate.py
@@ -0,0 +1,808 @@
+"""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.inputSchema
+    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.items():
+        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")
+    for imp in sorted(extra_imports):
+        lines.append(imp)
+    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.mimeType}, ~{size} bytes][/dim]")
+                elif isinstance(block, mcp.types.AudioContent):
+                    size = len(block.data) * 3 // 4
+                    console.print(f"[dim][Audio: {block.mimeType}, ~{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.inputSchema.get("properties", {})
+                    required = set(tool.inputSchema.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.mimeType}, ~{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.mimeType}, ~{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(
+            "# ---------------------------------------------------------------------------"
+        )
+
+        for tool in tools:
+            lines.append(_tool_function_source(tool))
+
+    # --- 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.inputSchema
+    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/src/fastmcp/cli/install/__init__.py b/src/fastmcp/cli/install/__init__.py
new file mode 100644
index 000000000..35b8d832d
--- /dev/null
+++ b/src/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/src/fastmcp/cli/install/claude_code.py b/src/fastmcp/cli/install/claude_code.py
new file mode 100644
index 000000000..a88413a32
--- /dev/null
+++ b/src/fastmcp/cli/install/claude_code.py
@@ -0,0 +1,240 @@
+"""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
+
+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])
+
+    # 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/src/fastmcp/cli/install/claude_desktop.py b/src/fastmcp/cli/install/claude_desktop.py
new file mode 100644
index 000000000..780b97c36
--- /dev/null
+++ b/src/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/src/fastmcp/cli/install/cursor.py b/src/fastmcp/cli/install/cursor.py
new file mode 100644
index 000000000..560d17e5d
--- /dev/null
+++ b/src/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/src/fastmcp/cli/install/gemini_cli.py b/src/fastmcp/cli/install/gemini_cli.py
new file mode 100644
index 000000000..42b6ec778
--- /dev/null
+++ b/src/fastmcp/cli/install/gemini_cli.py
@@ -0,0 +1,237 @@
+"""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
+
+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}"])
+
+    # 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/src/fastmcp/cli/install/goose.py b/src/fastmcp/cli/install/goose.py
new file mode 100644
index 000000000..16161dcf1
--- /dev/null
+++ b/src/fastmcp/cli/install/goose.py
@@ -0,0 +1,209 @@
+"""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='')}"]
+    for arg in args:
+        params.append(f"arg={quote(arg, safe='')}")
+    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/src/fastmcp/cli/install/mcp_json.py b/src/fastmcp/cli/install/mcp_json.py
new file mode 100644
index 000000000..130237344
--- /dev/null
+++ b/src/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 = {
+            "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/src/fastmcp/cli/install/shared.py b/src/fastmcp/cli/install/shared.py
new file mode 100644
index 000000000..fe980dce6
--- /dev/null
+++ b/src/fastmcp/cli/install/shared.py
@@ -0,0 +1,174 @@
+"""Shared utilities for install commands."""
+
+import json
+import os
+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__)
+
+
+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)
+    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/src/fastmcp/cli/install/stdio.py b/src/fastmcp/cli/install/stdio.py
new file mode 100644
index 000000000..31c89c1dc
--- /dev/null
+++ b/src/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/src/fastmcp/cli/run.py b/src/fastmcp/cli/run.py
new file mode 100644
index 000000000..36b029c38
--- /dev/null
+++ b/src/fastmcp/cli/run.py
@@ -0,0 +1,485 @@
+"""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.fastmcp import FastMCP as FastMCP1x
+from watchfiles import Change, awatch
+
+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 or config.deployment.transport
+            host = host or config.deployment.host
+            port = port or config.deployment.port
+            path = path or config.deployment.path
+            log_level = log_level or 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 v1 servers
+    if isinstance(server, FastMCP1x):
+        await run_v1_server_async(server, host=host, port=port, transport=transport)
+        return
+
+    kwargs = {}
+    if transport:
+        kwargs["transport"] = transport
+    if host:
+        kwargs["host"] = host
+    if port:
+        kwargs["port"] = port
+    if path:
+        kwargs["path"] = path
+    if log_level:
+        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: FastMCP1x,
+    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
+    """
+    if host:
+        server.settings.host = host
+    if port:
+        server.settings.port = port
+
+    match transport:
+        case "stdio":
+            await server.run_stdio_async()
+        case "http" | "streamable-http" | None:
+            await server.run_streamable_http_async()
+        case "sse":
+            await server.run_sse_async()
+
+
+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
+    first_run = True
+
+    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():
+            # Build command - add --no-banner on restarts to reduce noise
+            if first_run or "--no-banner" in cmd:
+                run_cmd = cmd
+            else:
+                run_cmd = [*cmd, "--no-banner"]
+            first_run = False
+
+            process = await asyncio.create_subprocess_exec(
+                *run_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/src/fastmcp/cli/tasks.py b/src/fastmcp/cli/tasks.py
new file mode 100644
index 000000000..23ddc6e58
--- /dev/null
+++ b/src/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/src/fastmcp/client/__init__.py b/src/fastmcp/client/__init__.py
new file mode 100644
index 000000000..e7e638176
--- /dev/null
+++ b/src/fastmcp/client/__init__.py
@@ -0,0 +1,30 @@
+from .auth import OAuth, BearerAuth
+from .client import Client
+from .transports import (
+    ClientTransport,
+    FastMCPTransport,
+    NodeStdioTransport,
+    NpxStdioTransport,
+    PythonStdioTransport,
+    SSETransport,
+    StdioTransport,
+    StreamableHttpTransport,
+    UvStdioTransport,
+    UvxStdioTransport,
+)
+
+__all__ = [
+    "BearerAuth",
+    "Client",
+    "ClientTransport",
+    "FastMCPTransport",
+    "NodeStdioTransport",
+    "NpxStdioTransport",
+    "OAuth",
+    "PythonStdioTransport",
+    "SSETransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "UvStdioTransport",
+    "UvxStdioTransport",
+]
diff --git a/src/fastmcp/client/auth/__init__.py b/src/fastmcp/client/auth/__init__.py
new file mode 100644
index 000000000..6ec3ecf4b
--- /dev/null
+++ b/src/fastmcp/client/auth/__init__.py
@@ -0,0 +1,4 @@
+from .bearer import BearerAuth
+from .oauth import OAuth
+
+__all__ = ["BearerAuth", "OAuth"]
diff --git a/src/fastmcp/client/auth/bearer.py b/src/fastmcp/client/auth/bearer.py
new file mode 100644
index 000000000..0c38a11b0
--- /dev/null
+++ b/src/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/src/fastmcp/client/auth/oauth.py b/src/fastmcp/client/auth/oauth.py
new file mode 100644
index 000000000..a4d1e9c77
--- /dev/null
+++ b/src/fastmcp/client/auth/oauth.py
@@ -0,0 +1,400 @@
+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 (
+    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__)
+
+
+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"
+
+    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())
+
+    @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
+        )
+
+    @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,
+        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)
+            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._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()
+        redirect_uri = f"http://localhost:{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,
+            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:
+            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) -> tuple[str, str | None]:
+        """Handle OAuth callback and return (auth_code, state)."""
+        # 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,
+            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://localhost:{self.redirect_port}"
+            )
+
+            TIMEOUT = 300.0  # 5 minute timeout
+            try:
+                with anyio.fail_after(TIMEOUT):
+                    await result_ready.wait()
+                    if result.error:
+                        raise result.error
+                    return result.code, result.state  # type: ignore
+            except TimeoutError as e:
+                raise TimeoutError(
+                    f"OAuth callback timed out after {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/src/fastmcp/client/client.py b/src/fastmcp/client/client.py
new file mode 100644
index 000000000..efacf671e
--- /dev/null
+++ b/src/fastmcp/client/client.py
@@ -0,0 +1,844 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import datetime
+import secrets
+import weakref
+from collections.abc import Coroutine
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Generic, Literal, TypeVar, cast, overload
+
+import anyio
+import httpx
+import mcp.types
+from exceptiongroup import catch
+from mcp import ClientSession, McpError
+from mcp.types import GetTaskResult, TaskStatusNotification
+from pydantic import AnyUrl
+
+import fastmcp
+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.server import FastMCP
+from fastmcp.utilities.exceptions import get_catch_handlers
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.timeout import (
+    normalize_timeout_to_seconds,
+    normalize_timeout_to_timedelta,
+)
+
+from .transports import (
+    ClientTransport,
+    ClientTransportT,
+    FastMCP1Server,
+    FastMCPTransport,
+    MCPConfigTransport,
+    NodeStdioTransport,
+    PythonStdioTransport,
+    SessionKwargs,
+    SSETransport,
+    StdioTransport,
+    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")
+
+
+@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.
+
+    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 | FastMCP1Server,
+        *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
+            | FastMCP1Server
+            | 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,
+    ) -> None:
+        self.name = name or self.generate_name()
+
+        self.transport = cast(ClientTransportT, infer_transport(transport))
+        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 timeout to timedelta if needed
+        timeout = normalize_timeout_to_timedelta(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
+
+        self._session_kwargs: SessionKwargs = {
+            "sampling_callback": None,
+            "list_roots_callback": None,
+            "logging_callback": create_log_callback(log_handler),
+            "message_handler": message_handler or TaskNotificationHandler(self),
+            "read_timeout_seconds": timeout,
+            "client_info": client_info,
+        }
+
+        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
+            )
+
+        # 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 _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."""
+        return self._session_state.initialize_result
+
+    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)
+
+        if not isinstance(self.transport, StdioTransport):
+            # Reset session state to fresh state
+            new_client._session_state = ClientSessionState()
+
+        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.initialize()
+                    yield
+                except anyio.ClosedResourceError as e:
+                    raise RuntimeError("Server session was closed unexpectedly") from e
+                finally:
+                    self._reset_session_state()
+
+    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.
+
+        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 or initialization times out.
+
+        Example:
+            ```python
+            # With auto-initialization disabled
+            client = Client(server, auto_initialize=False)
+            async with client:
+                result = await client.initialize()
+                print(f"Server: {result.serverInfo.name}")
+                print(f"Instructions: {result.instructions}")
+            ```
+        """
+
+        if self.initialize_result is not None:
+            return self.initialize_result
+
+        if timeout is None:
+            timeout = self._init_timeout
+        else:
+            timeout = normalize_timeout_to_seconds(timeout)
+
+        try:
+            with anyio.fail_after(timeout):
+                self._session_state.initialize_result = await self.session.initialize()
+                return self._session_state.initialize_result
+        except TimeoutError as e:
+            raise RuntimeError("Failed to initialize server session") from e
+
+    async def __aenter__(self):
+        return await self._connect()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # Use a timeout to prevent hanging during cleanup if the connection is in a bad
+        # state (e.g., rate-limited). The MCP SDK's transport may try to terminate the
+        # session which can hang if the server is unresponsive.
+        with anyio.move_on_after(5):
+            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
+            self._session_state.stop_event.set()
+            # wait for session to finish to ensure state has been reset
+            await self._session_state.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
+
+    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.
+        """
+        # Extract task ID from notification params
+        task_id = notification.params.taskId
+        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(notification.params.model_dump())
+                task._handle_status_notification(status)
+
+    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.ClientNotification(
+            root=mcp.types.CancelledNotification(
+                method="notifications/cancelled",
+                params=mcp.types.CancelledNotificationParams(
+                    requestId=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."""
+        await self.session.send_progress_notification(
+            progress_token, progress, total, message
+        )
+
+    async def set_logging_level(self, level: mcp.types.LoggingLevel) -> None:
+        """Send a logging/setLevel request."""
+        await self._await_with_session_monitoring(self.session.set_logging_level(level))
+
+    async def send_roots_list_changed(self) -> None:
+        """Send a roots/list_changed notification."""
+        await self.session.send_roots_list_changed()
+
+    # --- 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/src/fastmcp/client/elicitation.py b/src/fastmcp/client/elicitation.py
new file mode 100644
index 000000000..8df76c5b0
--- /dev/null
+++ b/src/fastmcp/client/elicitation.py
@@ -0,0 +1,80 @@
+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 ElicitationFnT
+from mcp.shared.context import LifespanContextT, RequestContext
+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.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: RequestContext[ClientSession, LifespanContextT],
+        params: ElicitRequestParams,
+    ) -> MCPElicitResult | mcp.types.ErrorData:
+        try:
+            # requestedSchema only exists on ElicitRequestFormParams, not ElicitRequestURLParams
+            if isinstance(params, ElicitRequestFormParams):
+                if params.requestedSchema == {"type": "object", "properties": {}}:
+                    response_type = None
+                else:
+                    response_type = json_schema_to_type(params.requestedSchema)
+            else:
+                # URL-based elicitation doesn't have a schema
+                response_type = None
+
+            result = await elicitation_handler(
+                params.message, response_type, params, context
+            )
+            # 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):
+                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/src/fastmcp/client/logging.py b/src/fastmcp/client/logging.py
new file mode 100644
index 000000000..2a8dd04e9
--- /dev/null
+++ b/src/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/src/fastmcp/client/messages.py b/src/fastmcp/client/messages.py
new file mode 100644
index 000000000..c50316cec
--- /dev/null
+++ b/src/fastmcp/client/messages.py
@@ -0,0 +1,128 @@
+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)
+
+        match message:
+            # requests
+            case RequestResponder():
+                # handle all requests
+                # TODO(ty): remove when ty supports match statement narrowing
+                await self.on_request(message)  # type: ignore[arg-type]
+
+                # handle specific requests
+                # TODO(ty): remove type ignores when ty supports match statement narrowing
+                match message.request.root:  # type: ignore[union-attr]
+                    case mcp.types.PingRequest():
+                        await self.on_ping(message.request.root)  # type: ignore[union-attr]
+                    case mcp.types.ListRootsRequest():
+                        await self.on_list_roots(message.request.root)  # type: ignore[union-attr]
+                    case mcp.types.CreateMessageRequest():
+                        await self.on_create_message(message.request.root)  # type: ignore[union-attr]
+
+            # notifications
+            case mcp.types.ServerNotification():
+                # handle all notifications
+                await self.on_notification(message)
+
+                # handle specific notifications
+                match message.root:
+                    case mcp.types.CancelledNotification():
+                        await self.on_cancelled(message.root)
+                    case mcp.types.ProgressNotification():
+                        await self.on_progress(message.root)
+                    case mcp.types.LoggingMessageNotification():
+                        await self.on_logging_message(message.root)
+                    case mcp.types.ToolListChangedNotification():
+                        await self.on_tool_list_changed(message.root)
+                    case mcp.types.ResourceListChangedNotification():
+                        await self.on_resource_list_changed(message.root)
+                    case mcp.types.PromptListChangedNotification():
+                        await self.on_prompt_list_changed(message.root)
+                    case mcp.types.ResourceUpdatedNotification():
+                        await self.on_resource_updated(message.root)
+
+            case Exception():
+                await self.on_exception(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/src/fastmcp/client/mixins/__init__.py b/src/fastmcp/client/mixins/__init__.py
new file mode 100644
index 000000000..323e20991
--- /dev/null
+++ b/src/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/src/fastmcp/client/mixins/prompts.py b/src/fastmcp/client/mixins/prompts.py
new file mode 100644
index 000000000..2844b2c6c
--- /dev/null
+++ b/src/fastmcp/client/mixins/prompts.py
@@ -0,0 +1,318 @@
+"""Prompt-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+import mcp.types
+import pydantic_core
+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
+    ) -> 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.
+
+        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
+        """
+        logger.debug(f"[{self.name}] called list_prompts")
+
+        result = await self._await_with_session_monitoring(
+            self.session.list_prompts(cursor=cursor)
+        )
+        return result
+
+    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.nextCursor:
+                break
+            if result.nextCursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.nextCursor!r} for list_prompts; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.nextCursor)
+            cursor = result.nextCursor
+        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(),
+        ):
+            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)
+
+            # If meta provided, use send_request for SEP-1686 task support
+            if propagated_meta:
+                task_dict = propagated_meta.get("modelcontextprotocol.io/task")
+                request = mcp.types.GetPromptRequest(
+                    params=mcp.types.GetPromptRequestParams(
+                        name=name,
+                        arguments=serialized_arguments,
+                        task=mcp.types.TaskMetadata(**task_dict) if task_dict else None,
+                        _meta=propagated_meta,  # type: ignore[unknown-argument]  # pydantic alias
+                    )
+                )
+                result = await self._await_with_session_monitoring(
+                    self.session.send_request(
+                        request=request,  # type: ignore[arg-type]
+                        result_type=mcp.types.GetPromptResult,
+                    )
+                )
+            else:
+                result = await self._await_with_session_monitoring(
+                    self.session.get_prompt(name=name, arguments=serialized_arguments)
+                )
+            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
+        propagated_meta = inject_trace_context(meta)
+
+        # 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"
+                    )
+
+        request = mcp.types.GetPromptRequest(
+            params=mcp.types.GetPromptRequestParams(
+                name=name,
+                arguments=serialized_arguments,
+                task=mcp.types.TaskMetadata(ttl=ttl),
+                _meta=propagated_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.taskId
+            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/src/fastmcp/client/mixins/resources.py b/src/fastmcp/client/mixins/resources.py
new file mode 100644
index 000000000..92889a2e6
--- /dev/null
+++ b/src/fastmcp/client/mixins/resources.py
@@ -0,0 +1,370 @@
+"""Resource-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+import mcp.types
+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
+    ) -> 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.
+
+        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
+        """
+        logger.debug(f"[{self.name}] called list_resources")
+
+        result = await self._await_with_session_monitoring(
+            self.session.list_resources(cursor=cursor)
+        )
+        return result
+
+    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.nextCursor:
+                break
+            if result.nextCursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.nextCursor!r} for list_resources; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.nextCursor)
+            cursor = result.nextCursor
+        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
+    ) -> 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.
+
+        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
+        """
+        logger.debug(f"[{self.name}] called list_resource_templates")
+
+        result = await self._await_with_session_monitoring(
+            self.session.list_resource_templates(cursor=cursor)
+        )
+        return result
+
+    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.resourceTemplates)
+            if not result.nextCursor:
+                break
+            if result.nextCursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.nextCursor!r} for list_resource_templates;"
+                    " stopping pagination"
+                )
+                break
+            seen_cursors.add(result.nextCursor)
+            cursor = result.nextCursor
+        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
+        """
+        uri_str = str(uri)
+        with client_span(
+            f"resources/read {uri_str}",
+            "resources/read",
+            uri_str,
+            session_id=self.transport.get_session_id(),
+            resource_uri=uri_str,
+        ):
+            logger.debug(f"[{self.name}] called read_resource: {uri}")
+
+            if isinstance(uri, str):
+                uri = AnyUrl(uri)  # Ensure AnyUrl
+
+            # Inject trace context into meta for propagation to server
+            propagated_meta = inject_trace_context(meta)
+
+            # If meta provided, use send_request for SEP-1686 task support
+            if propagated_meta:
+                task_dict = propagated_meta.get("modelcontextprotocol.io/task")
+                request = mcp.types.ReadResourceRequest(
+                    params=mcp.types.ReadResourceRequestParams(
+                        uri=uri,
+                        task=mcp.types.TaskMetadata(**task_dict) if task_dict else None,
+                        _meta=propagated_meta,  # type: ignore[unknown-argument]  # pydantic alias
+                    )
+                )
+                result = await self._await_with_session_monitoring(
+                    self.session.send_request(
+                        request=request,  # type: ignore[arg-type]
+                        result_type=mcp.types.ReadResourceResult,
+                    )
+                )
+            else:
+                result = await self._await_with_session_monitoring(
+                    self.session.read_resource(uri)
+                )
+            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
+        propagated_meta = inject_trace_context(meta)
+
+        if isinstance(uri, str):
+            uri = AnyUrl(uri)
+
+        request = mcp.types.ReadResourceRequest(
+            params=mcp.types.ReadResourceRequestParams(
+                uri=uri,
+                task=mcp.types.TaskMetadata(ttl=ttl),
+                _meta=propagated_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.taskId
+            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/src/fastmcp/client/mixins/task_management.py b/src/fastmcp/client/mixins/task_management.py
new file mode 100644
index 000000000..4c192e55e
--- /dev/null
+++ b/src/fastmcp/client/mixins/task_management.py
@@ -0,0 +1,157 @@
+"""Task management methods for FastMCP Client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import mcp.types
+from mcp import McpError
+
+if TYPE_CHECKING:
+    from fastmcp.client.client import Client
+from mcp.types import (
+    CancelTaskRequest,
+    CancelTaskRequestParams,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskPayloadResult,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
+    ListTasksRequest,
+    PaginatedRequestParams,
+)
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+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(taskId=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(taskId=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=GetTaskPayloadResult,
+            )
+        )
+        # Return as dict for compatibility with Task class parsing
+        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
+        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(taskId=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/src/fastmcp/client/mixins/tools.py b/src/fastmcp/client/mixins/tools.py
new file mode 100644
index 000000000..3c41cc376
--- /dev/null
+++ b/src/fastmcp/client/mixins/tools.py
@@ -0,0 +1,420 @@
+"""Tool-related methods for FastMCP Client."""
+
+from __future__ import annotations
+
+import uuid
+import weakref
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+import mcp.types
+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_timedelta
+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
+    ) -> 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.
+
+        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
+        """
+        logger.debug(f"[{self.name}] called list_tools")
+
+        result = await self._await_with_session_monitoring(
+            self.session.list_tools(cursor=cursor)
+        )
+        return result
+
+    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.nextCursor:
+                break
+            if result.nextCursor in seen_cursors:
+                logger.warning(
+                    f"[{self.name}] Server returned duplicate pagination cursor"
+                    f" {result.nextCursor!r} for list_tools; stopping pagination"
+                )
+                break
+            seen_cursors.add(result.nextCursor)
+            cursor = result.nextCursor
+        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(),
+        ):
+            logger.debug(f"[{self.name}] called call_tool: {name}")
+
+            # Inject trace context into meta for propagation to server
+            propagated_meta = inject_trace_context(meta)
+
+            result = await self._await_with_session_monitoring(
+                self.session.call_tool(
+                    name=name,
+                    arguments=arguments,
+                    read_timeout_seconds=normalize_timeout_to_timedelta(timeout),
+                    progress_callback=progress_handler or self._progress_handler,
+                    meta=propagated_meta if propagated_meta else None,
+                )
+            )
+            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, 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,
+        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)
+            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)
+
+        # 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=propagated_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.taskId
+            self._submitted_task_ids.add(server_task_id)
+
+            task_obj = ToolTask(
+                self, server_task_id, tool_name=name, immediate_result=None
+            )
+            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,
+            )
+
+
+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
+    """
+    from typing import cast
+
+    from fastmcp.client.client import CallToolResult
+
+    data = None
+    if result.isError and raise_on_error:
+        msg = cast(mcp.types.TextContent, result.content[0]).text
+        raise ToolError(msg)
+    elif result.structuredContent:
+        try:
+            if name not in tool_output_schemas:
+                await list_tools_fn()
+            if name in tool_output_schemas:
+                output_schema = tool_output_schemas.get(name)
+                if output_schema:
+                    if output_schema.get("x-fastmcp-wrap-result"):
+                        output_schema = output_schema.get("properties", {}).get(
+                            "result"
+                        )
+                        structured_content = result.structuredContent.get("result")
+                    else:
+                        structured_content = result.structuredContent
+                    output_type = json_schema_to_type(output_schema)
+                    type_adapter = get_cached_typeadapter(output_type)
+                    data = type_adapter.validate_python(structured_content)
+                else:
+                    data = result.structuredContent
+        except Exception as e:
+            logger.error(
+                f"[{client_name or 'client'}] Error parsing structured content: {e}"
+            )
+
+    return CallToolResult(
+        content=result.content,
+        structured_content=result.structuredContent,
+        meta=result.meta,
+        data=data,
+        is_error=result.isError,
+    )
diff --git a/src/fastmcp/client/oauth_callback.py b/src/fastmcp/client/oauth_callback.py
new file mode 100644
index 000000000..6bfba59cb
--- /dev/null
+++ b/src/fastmcp/client/oauth_callback.py
@@ -0,0 +1,251 @@
+"""
+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,
+    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="127.0.0.1",
+            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/src/fastmcp/client/progress.py b/src/fastmcp/client/progress.py
new file mode 100644
index 000000000..826d2cb99
--- /dev/null
+++ b/src/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/src/fastmcp/client/roots.py b/src/fastmcp/client/roots.py
new file mode 100644
index 000000000..1a55ac36a
--- /dev/null
+++ b/src/fastmcp/client/roots.py
@@ -0,0 +1,78 @@
+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 ListRootsFnT
+from mcp.shared.context 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]
+    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: RequestContext[ClientSession, LifespanContextT],
+    ) -> 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: RequestContext[ClientSession, LifespanContextT],
+    ) -> mcp.types.ListRootsResult | mcp.types.ErrorData:
+        try:
+            roots = fn(context)
+            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/src/fastmcp/client/sampling/__init__.py b/src/fastmcp/client/sampling/__init__.py
new file mode 100644
index 000000000..2987e9259
--- /dev/null
+++ b/src/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 mcp.shared.context 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-client",
+                    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/src/fastmcp/client/sampling/handlers/__init__.py b/src/fastmcp/client/sampling/handlers/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/client/sampling/handlers/anthropic.py b/src/fastmcp/client/sampling/handlers/anthropic.py
new file mode 100644
index 000000000..4bef921b3
--- /dev/null
+++ b/src/fastmcp/client/sampling/handlers/anthropic.py
@@ -0,0 +1,389 @@
+"""Anthropic sampling handler for FastMCP."""
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ModelPreferences,
+    SamplingMessage,
+    SamplingMessageContentBlock,
+    StopReason,
+    TextContent,
+    Tool,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+
+try:
+    from anthropic import AsyncAnthropic
+    from anthropic.types import (
+        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[anthropic]` or add `anthropic` to your dependencies."
+    ) from e
+
+__all__ = ["AnthropicSamplingHandler"]
+
+
+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.modelPreferences)
+
+        # 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.toolChoice:
+            converted = self._convert_tool_choice_to_anthropic(params.toolChoice)
+            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.maxTokens,
+        }
+        if params.systemPrompt is not None:
+            kwargs["system"] = params.systemPrompt
+        if params.temperature is not None:
+            kwargs["temperature"] = params.temperature
+        if params.stopSequences is not None:
+            kwargs["stop_sequences"] = params.stopSequences
+        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 | 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, ToolResultContent):
+                        # Extract text content from the result
+                        result_content: str | list[TextBlockParam] = ""
+                        if item.content:
+                            text_blocks: list[TextBlockParam] = []
+                            for sub_item in item.content:
+                                if isinstance(sub_item, TextContent):
+                                    text_blocks.append(
+                                        TextBlockParam(type="text", text=sub_item.text)
+                                    )
+                            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.toolUseId,
+                                content=result_content,
+                                is_error=item.isError if item.isError else False,
+                            )
+                        )
+
+                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] = []
+                    for item in content.content:
+                        if isinstance(item, TextContent):
+                            text_parts.append(
+                                TextBlockParam(type="text", text=item.text)
+                            )
+                    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.toolUseId,
+                                content=result_content_str,
+                                is_error=content.isError if content.isError else False,
+                            )
+                        ],
+                    )
+                )
+                continue
+
+            # Handle TextContent
+            if isinstance(content, TextContent):
+                anthropic_messages.append(
+                    MessageParam(
+                        role=message.role,
+                        content=content.text,
+                    )
+                )
+                continue
+
+            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.inputSchema)
+            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,
+            stopReason=stop_reason,
+        )
diff --git a/src/fastmcp/client/sampling/handlers/google_genai.py b/src/fastmcp/client/sampling/handlers/google_genai.py
new file mode 100644
index 000000000..c072d5131
--- /dev/null
+++ b/src/fastmcp/client/sampling/handlers/google_genai.py
@@ -0,0 +1,368 @@
+"""Google GenAI sampling handler with tool support for FastMCP 3.0."""
+
+from collections.abc import Sequence
+from uuid import uuid4
+
+try:
+    from google.genai import Client as GoogleGenaiClient
+    from google.genai.types import (
+        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[gemini]` or add `google-genai` "
+        "to your dependencies."
+    ) from e
+
+from mcp import ClientSession, ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+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
+
+__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.toolChoice)
+
+        # Select the model based on preferences
+        selected_model = self._get_model(model_preferences=params.modelPreferences)
+
+        # 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.systemPrompt,
+                    temperature=params.temperature,
+                    max_output_tokens=params.maxTokens,
+                    stop_sequences=params.stopSequences,
+                    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.
+
+    Google's parameters_json_schema accepts standard JSON Schema format,
+    so we pass tool.inputSchema directly without conversion.
+    """
+    return GoogleTool(
+        function_declarations=[
+            FunctionDeclaration(
+                name=tool.name,
+                description=tool.description or "",
+                parameters_json_schema=tool.inputSchema,
+            )
+        ]
+    )
+
+
+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, 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.toolUseId
+        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] = []
+            for item in content:
+                parts.append(_sampling_content_to_google_genai_part(item))
+
+            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)
+        msg = f"No content in response: {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:
+                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:
+        raise ValueError("No content in response from completion")
+
+    return CreateMessageResultWithTools(
+        content=content,
+        role="assistant",
+        model=model,
+        stopReason=stop_reason,
+    )
diff --git a/src/fastmcp/client/sampling/handlers/openai.py b/src/fastmcp/client/sampling/handlers/openai.py
new file mode 100644
index 000000000..38f5ff356
--- /dev/null
+++ b/src/fastmcp/client/sampling/handlers/openai.py
@@ -0,0 +1,406 @@
+"""OpenAI sampling handler for FastMCP."""
+
+import json
+from collections.abc import Iterator, Sequence
+from typing import Any, get_args
+
+from mcp import ClientSession, ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ModelPreferences,
+    SamplingMessage,
+    StopReason,
+    TextContent,
+    Tool,
+    ToolChoice,
+    ToolResultContent,
+    ToolUseContent,
+)
+
+try:
+    from openai import AsyncOpenAI
+    from openai.types.chat import (
+        ChatCompletion,
+        ChatCompletionAssistantMessageParam,
+        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[openai]` or add `openai` to your dependencies manually."
+    ) from e
+
+
+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.systemPrompt,
+                messages=messages,
+            )
+        )
+
+        model: ChatModel = self._select_model_from_preferences(params.modelPreferences)
+
+        # 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.toolChoice:
+            openai_tool_choice = self._convert_tool_choice_to_openai(params.toolChoice)
+
+        # 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.maxTokens is not None:
+            kwargs["max_completion_tokens"] = params.maxTokens
+        if params.temperature is not None:
+            kwargs["temperature"] = params.temperature
+        if params.stopSequences:
+            kwargs["stop"] = params.stopSequences
+        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 and text from the list
+                tool_calls: list[ChatCompletionMessageToolCallParam] = []
+                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)
+                    elif isinstance(item, ToolResultContent):
+                        # Collect tool results (added after assistant message)
+                        content_text = ""
+                        if item.content:
+                            result_texts = []
+                            for sub_item in item.content:
+                                if isinstance(sub_item, TextContent):
+                                    result_texts.append(sub_item.text)
+                            content_text = "\n".join(result_texts)
+                        tool_messages.append(
+                            ChatCompletionToolMessageParam(
+                                role="tool",
+                                tool_call_id=item.toolUseId,
+                                content=content_text,
+                            )
+                        )
+
+                # Add assistant message with tool calls if present
+                # OpenAI requires: assistant (with tool_calls) -> tool messages
+                if tool_calls or text_parts:
+                    msg_content = "\n".join(text_parts) if text_parts else None
+                    if tool_calls:
+                        openai_messages.append(
+                            ChatCompletionAssistantMessageParam(
+                                role="assistant",
+                                content=msg_content,
+                                tool_calls=tool_calls,
+                            )
+                        )
+                        # Add tool messages AFTER assistant message
+                        openai_messages.extend(tool_messages)
+                    elif msg_content:
+                        if message.role == "user":
+                            openai_messages.append(
+                                ChatCompletionUserMessageParam(
+                                    role="user",
+                                    content=msg_content,
+                                )
+                            )
+                        else:
+                            openai_messages.append(
+                                ChatCompletionAssistantMessageParam(
+                                    role="assistant",
+                                    content=msg_content,
+                                )
+                            )
+                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.toolUseId,
+                        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
+
+            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]
+                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.inputSchema)
+            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]
+                except json.JSONDecodeError as e:
+                    raise ValueError(
+                        f"Invalid JSON in tool arguments for "
+                        f"'{func.name}': {func.arguments}"  # type: ignore[union-attr]
+                    ) from e
+
+                content.append(
+                    ToolUseContent(
+                        type="tool_use",
+                        id=tool_call.id,
+                        name=func.name,  # type: ignore[union-attr]
+                        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]
+            role="assistant",
+            model=chat_completion.model,
+            stopReason=stop_reason,
+        )
diff --git a/src/fastmcp/client/tasks.py b/src/fastmcp/client/tasks.py
new file mode 100644
index 000000000..e3cfea518
--- /dev/null
+++ b/src/fastmcp/client/tasks.py
@@ -0,0 +1,551 @@
+"""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.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."""
+        if isinstance(message, mcp.types.ServerNotification):
+            if isinstance(message.root, TaskStatusNotification):
+                client = self._client_ref()
+                if client:
+                    client._handle_task_status_notification(message.root)
+
+        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
+            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.taskId} 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
+            now = datetime.now(timezone.utc)
+            return GetTaskResult(
+                taskId=self._task_id,
+                status="completed",
+                createdAt=now,
+                lastUpdatedAt=now,
+                ttl=None,
+                pollInterval=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 ('submitted', 'working', 'completed', 'failed').
+                   If None, waits for any terminal state (completed/failed)
+            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()
+        terminal_states = {"completed", "failed", "cancelled"}
+        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 in terminal_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 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,
+    ):
+        """
+        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
+        """
+        super().__init__(client, task_id, immediate_result)
+        self._tool_name = tool_name
+
+    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
+        else:
+            # Check client connected
+            self._check_client_connected()
+
+            # Wait for completion using event-based wait (respects notifications)
+            await self.wait()
+
+            # 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=True
+                )
+            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=True
+                )
+            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,
+                        structuredContent=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=True
+                    )
+                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()
+
+            # 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()
+
+            # 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/src/fastmcp/client/telemetry.py b/src/fastmcp/client/telemetry.py
new file mode 100644
index 000000000..10d6d825f
--- /dev/null
+++ b/src/fastmcp/client/telemetry.py
@@ -0,0 +1,47 @@
+"""Client-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+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,
+) -> 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:
+        attrs: dict[str, str] = {
+            # RPC semantic conventions
+            "rpc.system": "mcp",
+            "rpc.method": method,
+            # MCP semantic conventions
+            "mcp.method.name": method,
+            # FastMCP-specific attributes
+            "fastmcp.component.key": component_key,
+        }
+        if session_id:
+            attrs["mcp.session.id"] = session_id
+        if resource_uri:
+            attrs["mcp.resource.uri"] = resource_uri
+        span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+__all__ = ["client_span"]
diff --git a/src/fastmcp/client/transports/__init__.py b/src/fastmcp/client/transports/__init__.py
new file mode 100644
index 000000000..010a7cb7c
--- /dev/null
+++ b/src/fastmcp/client/transports/__init__.py
@@ -0,0 +1,38 @@
+# Re-export all public APIs for backward compatibility
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+
+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,
+)
+from fastmcp.server.server import FastMCP
+
+__all__ = [
+    "ClientTransport",
+    "FastMCPStdioTransport",
+    "FastMCPTransport",
+    "NodeStdioTransport",
+    "NpxStdioTransport",
+    "PythonStdioTransport",
+    "SSETransport",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "UvStdioTransport",
+    "UvxStdioTransport",
+    "infer_transport",
+]
diff --git a/src/fastmcp/client/transports/base.py b/src/fastmcp/client/transports/base.py
new file mode 100644
index 000000000..e9ebb1f3a
--- /dev/null
+++ b/src/fastmcp/client/transports/base.py
@@ -0,0 +1,82 @@
+import abc
+import contextlib
+import datetime
+from collections.abc import AsyncIterator
+from typing import Literal, TypeVar
+
+import httpx
+import mcp.types
+from mcp import ClientSession
+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: datetime.timedelta | 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
+
+
+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
+
+    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/src/fastmcp/client/transports/config.py b/src/fastmcp/client/transports/config.py
new file mode 100644
index 000000000..c8d5a8a40
--- /dev/null
+++ b/src/fastmcp/client/transports/config.py
@@ -0,0 +1,203 @@
+import contextlib
+import datetime
+from collections.abc import AsyncIterator
+from typing import Any
+
+from mcp import ClientSession
+from typing_extensions import Unpack
+
+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,
+)
+from fastmcp.server.server import FastMCP, create_proxy
+
+
+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).
+        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 = []
+
+            try:
+                for name, server_config in self.config.mcpServers.items():
+                    transport, _client, proxy = await self._create_proxy(
+                        name, server_config, timeout, stack
+                    )
+                    self._transports.append(transport)
+                    composite.mount(
+                        proxy, namespace=name if self.name_as_prefix else None
+                    )
+            except Exception:
+                # Clean up any transports created before the failure
+                for t in self._transports:
+                    await t.close()
+                self._transports = []
+                raise
+
+            async with FastMCPTransport(mcp=composite).connect_session(
+                **session_kwargs
+            ) as session:
+                yield session
+
+    async def _create_proxy(
+        self,
+        name: str,
+        config: MCPServerTypes,
+        timeout: datetime.timedelta | 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
+
+        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(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/src/fastmcp/client/transports/http.py b/src/fastmcp/client/transports/http.py
new file mode 100644
index 000000000..f7e74ca60
--- /dev/null
+++ b/src/fastmcp/client/transports/http.py
@@ -0,0 +1,151 @@
+"""Streamable HTTP transport for FastMCP Client."""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+from collections.abc import AsyncIterator, Callable
+from typing import 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
+
+import fastmcp
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
+
+
+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,
+        sse_read_timeout: datetime.timedelta | float | int | None = None,
+        httpx_client_factory: McpHttpClientFactory | 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.
+            sse_read_timeout: Deprecated. Use read_timeout_seconds in session_kwargs.
+            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.
+        """
+        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._set_auth(auth)
+
+        if sse_read_timeout is not None:
+            if fastmcp.settings.deprecation_warnings:
+                import warnings
+
+                warnings.warn(
+                    "The `sse_read_timeout` parameter is deprecated and no longer used. "
+                    "The new streamable_http_client API does not support this parameter. "
+                    "Use `read_timeout_seconds` in session_kwargs or configure timeout on "
+                    "the httpx client via `httpx_client_factory` instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+        self.sse_read_timeout = normalize_timeout_to_timedelta(sse_read_timeout)
+
+        self._get_session_id_cb: Callable[[], str | None] | None = None
+
+    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)
+        elif isinstance(auth, OAuth):
+            auth._bind(self.url)
+            resolved = auth
+        elif isinstance(auth, str):
+            resolved = BearerAuth(auth)
+        else:
+            resolved = auth
+        self.auth: httpx.Auth | None = resolved
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        # Load headers from an active HTTP request, if available. This will only be true
+        # if the client is used in a FastMCP Proxy, in which case the MCP client headers
+        # need to be forwarded to the remote server.
+        headers = get_http_headers(include={"authorization"}) | self.headers
+
+        # Configure timeout if provided, preserving MCP's 30s connect default
+        timeout: httpx.Timeout | None = None
+        if session_kwargs.get("read_timeout_seconds") is not None:
+            read_timeout_seconds = cast(
+                datetime.timedelta, session_kwargs.get("read_timeout_seconds")
+            )
+            timeout = httpx.Timeout(30.0, read=read_timeout_seconds.total_seconds())
+
+        # Create httpx client from factory or use default with MCP-appropriate timeouts
+        # create_mcp_http_client uses 30s connect/5min read timeout by default,
+        # and always enables follow_redirects
+        if self.httpx_client_factory is not None:
+            # Factory clients get the full kwargs for backwards compatibility
+            http_client = self.httpx_client_factory(
+                headers=headers,
+                auth=self.auth,
+                follow_redirects=True,  # type: ignore[call-arg]
+                **({"timeout": timeout} if timeout else {}),
+            )
+        else:
+            http_client = create_mcp_http_client(
+                headers=headers,
+                timeout=timeout,
+                auth=self.auth,
+            )
+
+        # Ensure httpx client is closed after use
+        async with (
+            http_client,
+            streamable_http_client(self.url, http_client=http_client) as transport,
+        ):
+            read_stream, write_stream, get_session_id = transport
+            self._get_session_id_cb = get_session_id
+            async with ClientSession(
+                read_stream, write_stream, **session_kwargs
+            ) as session:
+                yield session
+
+    def get_session_id(self) -> str | None:
+        if self._get_session_id_cb:
+            try:
+                return self._get_session_id_cb()
+            except Exception:
+                return None
+        return None
+
+    async def close(self):
+        # Reset the session id callback
+        self._get_session_id_cb = None
+
+    def __repr__(self) -> str:
+        return f"<StreamableHttpTransport(url='{self.url}')>"
diff --git a/src/fastmcp/client/transports/inference.py b/src/fastmcp/client/transports/inference.py
new file mode 100644
index 000000000..438995c23
--- /dev/null
+++ b/src/fastmcp/client/transports/inference.py
@@ -0,0 +1,154 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast, overload
+
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+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.server.server import FastMCP
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    pass
+
+logger = get_logger(__name__)
+
+
+@overload
+def infer_transport(transport: ClientTransportT) -> ClientTransportT: ...
+
+
+@overload
+def infer_transport(transport: FastMCP) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: FastMCP1Server) -> 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
+    | FastMCP1Server
+    | 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 FastMCP1Server: 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 isinstance(transport, FastMCP | FastMCP1Server):
+        inferred_transport = FastMCPTransport(
+            mcp=cast(FastMCP[Any] | FastMCP1Server, 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
diff --git a/src/fastmcp/client/transports/memory.py b/src/fastmcp/client/transports/memory.py
new file mode 100644
index 000000000..26b4e934a
--- /dev/null
+++ b/src/fastmcp/client/transports/memory.py
@@ -0,0 +1,90 @@
+import contextlib
+from collections.abc import AsyncIterator
+
+import anyio
+from mcp import ClientSession
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+from mcp.shared.memory import create_client_server_memory_streams
+from typing_extensions import Unpack
+
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.server.server import FastMCP
+
+
+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 2.x servers and FastMCP 1.0
+    servers 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 | FastMCP1Server, raise_exceptions: bool = False):
+        """Initialize a FastMCPTransport from a FastMCP server instance."""
+
+        # Accept both FastMCP 2.x and FastMCP 1.0 servers. Both expose a
+        # ``_mcp_server`` attribute pointing to the underlying MCP server
+        # implementation, so we can treat them identically.
+        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
+
+            async with (
+                anyio.create_task_group() as tg,
+                _enter_server_lifespan(server=self.server),
+            ):
+                tg.start_soon(
+                    lambda: self.server._mcp_server.run(
+                        server_read,
+                        server_write,
+                        self.server._mcp_server.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 | FastMCP1Server,
+) -> AsyncIterator[None]:
+    """Enters the server's lifespan context for FastMCP servers and does nothing for FastMCP 1 servers."""
+    if isinstance(server, FastMCP):
+        async with server._lifespan_manager():
+            yield
+    else:
+        yield
diff --git a/src/fastmcp/client/transports/sse.py b/src/fastmcp/client/transports/sse.py
new file mode 100644
index 000000000..36fa0ebc0
--- /dev/null
+++ b/src/fastmcp/client/transports/sse.py
@@ -0,0 +1,97 @@
+"""Server-Sent Events (SSE) transport for FastMCP Client."""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+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.transports.base import ClientTransport, SessionKwargs
+from fastmcp.server.dependencies import get_http_headers
+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,
+    ):
+        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._set_auth(auth)
+
+        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)
+        elif isinstance(auth, OAuth):
+            auth._bind(self.url)
+            resolved = auth
+        elif isinstance(auth, str):
+            resolved = BearerAuth(auth)
+        else:
+            resolved = auth
+        self.auth: httpx.Auth | None = resolved
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        client_kwargs: dict[str, Any] = {}
+
+        # load headers from an active HTTP request, if available. This will only be true
+        # if the client is used in a FastMCP Proxy, in which case the MCP client headers
+        # need to be forwarded to the remote server.
+        client_kwargs["headers"] = (
+            get_http_headers(include={"authorization"}) | 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()
+        if session_kwargs.get("read_timeout_seconds") is not None:
+            read_timeout_seconds = cast(
+                datetime.timedelta, session_kwargs.get("read_timeout_seconds")
+            )
+            client_kwargs["timeout"] = read_timeout_seconds.total_seconds()
+
+        if self.httpx_client_factory is not None:
+            client_kwargs["httpx_client_factory"] = self.httpx_client_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/src/fastmcp/client/transports/stdio.py b/src/fastmcp/client/transports/stdio.py
new file mode 100644
index 000000000..ca8d5377c
--- /dev/null
+++ b/src/fastmcp/client/transports/stdio.py
@@ -0,0 +1,543 @@
+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
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+
+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 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
+        await self._connect_task
+
+        # reset variables and events for potential future reconnects
+        self._connect_task = None
+        self._stop_event = anyio.Event()
+        self._ready_event = anyio.Event()
+
+    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}"
+            )
+
+        # Create Environment from provided parameters (internal use)
+        env_config = UVEnvironment(
+            python=python_version,
+            dependencies=with_packages,
+            requirements=with_requirements,
+            project=project_directory,
+            editable=None,  # Not exposed in this transport
+        )
+
+        # Build uv arguments using the config
+        uv_args: list[str] = []
+
+        # Check if we need any environment setup
+        if env_config._must_run_with_uv():
+            # 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/src/fastmcp/contrib/README.md b/src/fastmcp/contrib/README.md
new file mode 100644
index 000000000..7b1dbb550
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/bulk_tool_caller/README.md b/src/fastmcp/contrib/bulk_tool_caller/README.md
new file mode 100644
index 000000000..41daa7780
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/bulk_tool_caller/__init__.py b/src/fastmcp/contrib/bulk_tool_caller/__init__.py
new file mode 100644
index 000000000..b8f66ed8b
--- /dev/null
+++ b/src/fastmcp/contrib/bulk_tool_caller/__init__.py
@@ -0,0 +1,3 @@
+from .bulk_tool_caller import BulkToolCaller
+
+__all__ = ["BulkToolCaller"]
diff --git a/src/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py b/src/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py
new file mode 100644
index 000000000..71ed25482
--- /dev/null
+++ b/src/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,
+            isError=result.isError,
+            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.isError 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.isError 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,
+                isError=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,
+                isError=result.isError,
+                content=result.content,
+            )
diff --git a/src/fastmcp/contrib/bulk_tool_caller/example.py b/src/fastmcp/contrib/bulk_tool_caller/example.py
new file mode 100644
index 000000000..b86a53e2a
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/component_manager/README.md b/src/fastmcp/contrib/component_manager/README.md
new file mode 100644
index 000000000..0cc99ad15
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/component_manager/__init__.py b/src/fastmcp/contrib/component_manager/__init__.py
new file mode 100644
index 000000000..b89a6d984
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/component_manager/component_manager.py b/src/fastmcp/contrib/component_manager/component_manager.py
new file mode 100644
index 000000000..099b9052f
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/component_manager/example.py b/src/fastmcp/contrib/component_manager/example.py
new file mode 100644
index 000000000..7780f8a7c
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/mcp_mixin/README.md b/src/fastmcp/contrib/mcp_mixin/README.md
new file mode 100644
index 000000000..39c3a2352
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/mcp_mixin/__init__.py b/src/fastmcp/contrib/mcp_mixin/__init__.py
new file mode 100644
index 000000000..48a536632
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/mcp_mixin/example.py b/src/fastmcp/contrib/mcp_mixin/example.py
new file mode 100644
index 000000000..b282b58fe
--- /dev/null
+++ b/src/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/src/fastmcp/contrib/mcp_mixin/mcp_mixin.py b/src/fastmcp/contrib/mcp_mixin/mcp_mixin.py
new file mode 100644
index 000000000..86f8c9aec
--- /dev/null
+++ b/src/fastmcp/contrib/mcp_mixin/mcp_mixin.py
@@ -0,0 +1,320 @@
+"""Provides a base mixin class and decorators for easy registration of class methods with FastMCP."""
+
+import inspect
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+import fastmcp
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource import Resource
+from fastmcp.tools.tool 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)}"
+        )
+
+    if "serializer" in kwargs and fastmcp.settings.deprecation_warnings:
+        warnings.warn(
+            "The `serializer` parameter is deprecated. "
+            "Return ToolResult from your tools for full control over serialization. "
+            "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    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/src/fastmcp/decorators.py b/src/fastmcp/decorators.py
new file mode 100644
index 000000000..75dff25ac
--- /dev/null
+++ b/src/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/src/fastmcp/dependencies.py b/src/fastmcp/dependencies.py
new file mode 100644
index 000000000..2aa8c145a
--- /dev/null
+++ b/src/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/src/fastmcp/exceptions.py b/src/fastmcp/exceptions.py
index 8295770b2..595961e3b 100644
--- a/src/fastmcp/exceptions.py
+++ b/src/fastmcp/exceptions.py
@@ -1,5 +1,7 @@
 """Custom exceptions for FastMCP."""
 
+from mcp import McpError  # noqa: F401
+
 
 class FastMCPError(Exception):
     """Base error for FastMCP."""
@@ -15,3 +17,27 @@ class ResourceError(FastMCPError):
 
 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."""
diff --git a/src/fastmcp/experimental/__init__.py b/src/fastmcp/experimental/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/experimental/sampling/__init__.py b/src/fastmcp/experimental/sampling/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/experimental/sampling/handlers/__init__.py b/src/fastmcp/experimental/sampling/handlers/__init__.py
new file mode 100644
index 000000000..627dfd011
--- /dev/null
+++ b/src/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/src/fastmcp/experimental/sampling/handlers/openai.py b/src/fastmcp/experimental/sampling/handlers/openai.py
new file mode 100644
index 000000000..b466f7a77
--- /dev/null
+++ b/src/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/src/fastmcp/experimental/server/openapi/__init__.py b/src/fastmcp/experimental/server/openapi/__init__.py
new file mode 100644
index 000000000..827a9ff81
--- /dev/null
+++ b/src/fastmcp/experimental/server/openapi/__init__.py
@@ -0,0 +1,40 @@
+"""Deprecated: Import from fastmcp.server.providers.openapi instead."""
+
+import warnings
+
+# Deprecated in 2.14 when OpenAPI support was promoted out of experimental
+warnings.warn(
+    "Importing from fastmcp.experimental.server.openapi is deprecated. "
+    "Import from fastmcp.server.providers.openapi instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Import from canonical location
+from fastmcp.server.openapi.server import FastMCPOpenAPI as FastMCPOpenAPI  # noqa: E402
+from fastmcp.server.providers.openapi import (  # noqa: E402
+    ComponentFn as ComponentFn,
+    MCPType as MCPType,
+    OpenAPIResource as OpenAPIResource,
+    OpenAPIResourceTemplate as OpenAPIResourceTemplate,
+    OpenAPITool as OpenAPITool,
+    RouteMap as RouteMap,
+    RouteMapFn as RouteMapFn,
+)
+from fastmcp.server.providers.openapi.routing import (  # noqa: E402
+    DEFAULT_ROUTE_MAPPINGS as DEFAULT_ROUTE_MAPPINGS,
+    _determine_route_type as _determine_route_type,
+)
+
+__all__ = [
+    "DEFAULT_ROUTE_MAPPINGS",
+    "ComponentFn",
+    "FastMCPOpenAPI",
+    "MCPType",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+    "RouteMap",
+    "RouteMapFn",
+    "_determine_route_type",
+]
diff --git a/src/fastmcp/experimental/transforms/__init__.py b/src/fastmcp/experimental/transforms/__init__.py
new file mode 100644
index 000000000..8b1378917
--- /dev/null
+++ b/src/fastmcp/experimental/transforms/__init__.py
@@ -0,0 +1 @@
+
diff --git a/src/fastmcp/experimental/transforms/code_mode.py b/src/fastmcp/experimental/transforms/code_mode.py
new file mode 100644
index 000000000..4d7723532
--- /dev/null
+++ b/src/fastmcp/experimental/transforms/code_mode.py
@@ -0,0 +1,575 @@
+import importlib
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Annotated, Any, Literal, Protocol
+
+from mcp.types import TextContent
+from pydantic import Field
+
+from fastmcp.exceptions import NotFoundError
+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.tool 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 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.
+    """
+
+    def __init__(
+        self,
+        *,
+        limits: dict[str, Any] | None = None,
+    ) -> None:
+        self.limits = 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.keys()),
+            external_functions=list(async_functions.keys()),
+        )
+        run_kwargs: dict[str, Any] = {"external_functions": async_functions}
+        if inputs:
+            run_kwargs["inputs"] = inputs
+        if self.limits is not None:
+            run_kwargs["limits"] = self.limits
+        return await pydantic_monty.run_monty_async(monty, **run_kwargs)
+
+
+# ---------------------------------------------------------------------------
+# 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]
+        ) -> 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]
+        ) -> 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]
+        ) -> 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]
+        ) -> 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,
+    ) -> None:
+        super().__init__()
+        self.execute_tool_name = execute_tool_name
+        self.execute_description = execute_description
+        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
+
+        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]
+        ) -> Any:
+            """Execute tool calls using Python code."""
+
+            async def call_tool(tool_name: str, params: dict[str, Any]) -> Any:
+                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/src/fastmcp/experimental/utilities/openapi/__init__.py b/src/fastmcp/experimental/utilities/openapi/__init__.py
new file mode 100644
index 000000000..0c8dd15e5
--- /dev/null
+++ b/src/fastmcp/experimental/utilities/openapi/__init__.py
@@ -0,0 +1,35 @@
+"""Deprecated: Import from fastmcp.utilities.openapi instead."""
+
+import warnings
+
+from fastmcp.utilities.openapi import (
+    HTTPRoute,
+    HttpMethod,
+    ParameterInfo,
+    ParameterLocation,
+    RequestBodyInfo,
+    ResponseInfo,
+    extract_output_schema_from_responses,
+    parse_openapi_to_http_routes,
+    _combine_schemas,
+)
+
+# Deprecated in 2.14 when OpenAPI support was promoted out of experimental
+warnings.warn(
+    "Importing from fastmcp.experimental.utilities.openapi is deprecated. "
+    "Import from fastmcp.utilities.openapi instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [
+    "HTTPRoute",
+    "HttpMethod",
+    "ParameterInfo",
+    "ParameterLocation",
+    "RequestBodyInfo",
+    "ResponseInfo",
+    "_combine_schemas",
+    "extract_output_schema_from_responses",
+    "parse_openapi_to_http_routes",
+]
diff --git a/src/fastmcp/mcp_config.py b/src/fastmcp/mcp_config.py
new file mode 100644
index 000000000..d4dbf2df5
--- /dev/null
+++ b/src/fastmcp/mcp_config.py
@@ -0,0 +1,371 @@
+"""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.tools.tool_transform import ToolTransformConfig
+from fastmcp.utilities.types import FastMCPBaseModel
+
+if TYPE_CHECKING:
+    from fastmcp.client.transports import (
+        ClientTransport,
+        SSETransport,
+        StdioTransport,
+        StreamableHttpTransport,
+    )
+    from fastmcp.server.server import FastMCP
+
+
+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"
+
+
+class _TransformingMCPServerMixin(FastMCPBaseModel):
+    """A mixin that enables wrapping an MCP Server with tool transforms."""
+
+    tools: dict[str, ToolTransformConfig] = 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[FastMCP[Any], ClientTransport]:
+        """Turn the Transforming MCPServer into a FastMCP Server and also return the underlying transport."""
+        from fastmcp.client import Client
+        from fastmcp.client.transports import (
+            ClientTransport,  # pyright: ignore[reportUnusedImport]
+        )
+        from fastmcp.server import create_proxy
+
+        transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]  # ty: ignore[unresolved-attribute]
+        transport = cast(ClientTransport, transport)
+
+        client: Client[ClientTransport] = 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)
+
+        # Apply tool transforms if configured
+        if self.tools:
+            from fastmcp.server.transforms import ToolTransform
+
+            wrapped_mcp_server.add_transform(ToolTransform(self.tools))
+
+        return wrapped_mcp_server, transport
+
+    def to_transport(self) -> ClientTransport:
+        """Get the transport for the transforming MCP server."""
+        from fastmcp.client.transports import FastMCPTransport
+
+        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,
+                sse_read_timeout=self.sse_read_timeout,
+            )
+
+
+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))
+
+    @classmethod
+    def from_file(cls, file_path: Path) -> Self:
+        """Load configuration from JSON file."""
+        if file_path.exists() and (content := file_path.read_text().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/src/fastmcp/prompts/__init__.py b/src/fastmcp/prompts/__init__.py
new file mode 100644
index 000000000..7148c052d
--- /dev/null
+++ b/src/fastmcp/prompts/__init__.py
@@ -0,0 +1,12 @@
+from .function_prompt import FunctionPrompt, prompt
+from .prompt import Message, Prompt, PromptArgument, PromptMessage, PromptResult
+
+__all__ = [
+    "FunctionPrompt",
+    "Message",
+    "Prompt",
+    "PromptArgument",
+    "PromptMessage",
+    "PromptResult",
+    "prompt",
+]
diff --git a/src/fastmcp/prompts/function_prompt.py b/src/fastmcp/prompts/function_prompt.py
new file mode 100644
index 000000000..132c36489
--- /dev/null
+++ b/src/fastmcp/prompts/function_prompt.py
@@ -0,0 +1,484 @@
+"""Standalone @prompt decorator for FastMCP."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    Protocol,
+    TypeVar,
+    overload,
+    runtime_checkable,
+)
+
+import pydantic_core
+from mcp.types import Icon
+from pydantic.json_schema import SkipJsonSchema
+
+import fastmcp
+from fastmcp.decorators import resolve_task_config
+from fastmcp.exceptions import PromptError
+from fastmcp.prompts.prompt import Prompt, PromptArgument, PromptResult
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.dependencies import (
+    transform_context_annotations,
+    without_injected_parameters,
+)
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+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")
+
+        description = metadata.description or inspect.getdoc(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__
+
+        # Transform Context type annotations to Depends() for unified DI
+        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)
+
+        # 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 Exception as e:
+            logger.exception(f"Error rendering prompt {self.name}")
+            raise PromptError(f"Error rendering prompt {self.name}.") from e
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this prompt with docket for background execution.
+
+        FunctionPrompt registers the underlying function, which has the user's
+        Depends parameters for docket to resolve.
+        """
+        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 create_prompt(
+        fn: Callable[..., Any], prompt_name: str | None
+    ) -> FunctionPrompt:
+        # Create metadata first, then pass it
+        prompt_meta = PromptMeta(
+            name=prompt_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            meta=meta,
+            task=resolve_task_config(task),
+            auth=auth,
+        )
+        return FunctionPrompt.from_function(fn, metadata=prompt_meta)
+
+    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 hasattr(fn, "__func__") else fn
+        target.__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F, prompt_name: str | None) -> F:
+        if fastmcp.settings.decorator_mode == "object":
+            warnings.warn(
+                "decorator_mode='object' is deprecated and will be removed in a future version. "
+                "Decorators now return the original function with metadata attached.",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            return create_prompt(fn, prompt_name)  # type: ignore[return-value]
+        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/src/fastmcp/prompts/prompt.py b/src/fastmcp/prompts/prompt.py
new file mode 100644
index 000000000..1b441253a
--- /dev/null
+++ b/src/fastmcp/prompts/prompt.py
@@ -0,0 +1,439 @@
+"""Base classes for FastMCP prompts."""
+
+from __future__ import annotations as _annotations
+
+import warnings
+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.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+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",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Deprecated re-exports for backwards compatibility."""
+    deprecated_exports = {
+        "FunctionPrompt": "FunctionPrompt",
+        "prompt": "prompt",
+    }
+
+    if name in deprecated_exports:
+        import fastmcp
+
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                f"Importing {name} from fastmcp.prompts.prompt is deprecated. "
+                f"Import from fastmcp.prompts.function_prompt instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        from fastmcp.prompts import function_prompt
+
+        return getattr(function_prompt, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/src/fastmcp/py.typed b/src/fastmcp/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/resources.py b/src/fastmcp/resources.py
deleted file mode 100644
index 71e9a9d8e..000000000
--- a/src/fastmcp/resources.py
+++ /dev/null
@@ -1,232 +0,0 @@
-import pydantic.json
-
-import abc
-import asyncio
-import json
-from pathlib import Path
-from typing import Dict, Optional, Callable, Any, Union, Awaitable
-
-import httpx
-from pydantic import BaseModel, field_validator
-from pydantic.networks import _BaseUrl
-
-from .utilities.logging import get_logger
-
-logger = get_logger(__name__)
-
-
-class Resource(BaseModel):
-    """Base class for all resources.
-
-    Resources can contain either text (UTF-8 encoded) or binary data.
-    Text resources are suitable for source code, logs, JSON, etc.
-    Binary resources are suitable for images, PDFs, audio, etc.
-    """
-
-    uri: _BaseUrl
-    name: str
-    description: Optional[str] = None
-    mime_type: Optional[str] = None
-    is_binary: bool = False
-
-    @field_validator("name", mode="before")
-    @classmethod
-    def set_default_name(cls, name: str | None, info) -> str:
-        """Set default name from URI if not provided."""
-        if name is not None:
-            return name
-        # Extract everything after the protocol (e.g., "desktop" from "resource://desktop")
-        uri = info.data.get("uri")
-        if uri:
-            return str(uri).split("://", 1)[1]
-        raise ValueError("Either name or uri must be provided")
-
-    @abc.abstractmethod
-    async def read(self) -> Union[str, bytes]:
-        """Read the resource content.
-
-        Returns:
-            Union[str, bytes]: Text content as str for text resources,
-                             binary content as bytes for binary resources
-        """
-        return ""
-
-
-class FunctionResource(Resource):
-    """A resource that is generated by a function call.
-
-    The function can be sync or async and must return a string, bytes,
-    or another Resource.
-    """
-
-    func: Union[Callable[[], Any], Callable[[], Awaitable[Any]]]
-    is_async: bool = False
-
-    def __init__(self, **data):
-        super().__init__(**data)
-        self.is_async = asyncio.iscoroutinefunction(self.func)
-
-    async def read(self) -> Union[str, bytes]:
-        """Read the resource content by calling the function."""
-        try:
-            result = (
-                await self.func()
-                if self.is_async
-                else await asyncio.to_thread(self.func)
-            )
-
-            if isinstance(result, Resource):
-                return await result.read()
-            if isinstance(result, bytes):
-                return result
-            if not isinstance(result, str):
-                try:
-                    return json.dumps(result, default=pydantic.json.pydantic_encoder)
-                except json.JSONDecodeError:
-                    return str(result)
-            return result
-        except Exception as e:
-            raise ValueError(f"Error calling function {self.func.__name__}: {e}")
-
-
-class FileResource(Resource):
-    """A file resource."""
-
-    path: Path
-
-    @field_validator("path")
-    @classmethod
-    def validate_absolute_path(cls, path: Path) -> Path:
-        """Ensure path is absolute."""
-        if not path.is_absolute():
-            raise ValueError(f"Path must be absolute: {path}")
-        return path
-
-    async def read(self) -> Union[str, bytes]:
-        """Read the file content."""
-        try:
-            if self.is_binary:
-                return await asyncio.to_thread(self.path.read_bytes)
-            return await asyncio.to_thread(self.path.read_text)
-        except FileNotFoundError:
-            raise FileNotFoundError(f"File not found: {self.path}")
-        except PermissionError:
-            raise PermissionError(f"Permission denied: {self.path}")
-        except Exception as e:
-            raise ValueError(f"Error reading file {self.path}: {e}")
-
-
-class HttpResource(Resource):
-    """An HTTP resource."""
-
-    url: str
-    headers: Optional[Dict[str, str]] = None
-
-    async def read(self) -> Union[str, bytes]:
-        """Read the HTTP resource content."""
-        try:
-            async with httpx.AsyncClient() as client:
-                response = await client.get(self.url, headers=self.headers)
-                response.raise_for_status()
-                return response.content if self.is_binary else response.text
-        except httpx.HTTPStatusError as e:
-            raise ValueError(f"HTTP error {e.response.status_code}: {e}")
-        except httpx.RequestError as e:
-            raise ValueError(f"Request failed: {e}")
-
-
-class DirectoryResource(Resource):
-    """A directory resource."""
-
-    path: Path
-    recursive: bool = False
-    pattern: Optional[str] = None
-    mime_type: Optional[str] = "application/json"
-
-    @field_validator("path")
-    @classmethod
-    def validate_absolute_path(cls, path: Path) -> Path:
-        """Ensure path is absolute."""
-        if not path.is_absolute():
-            raise ValueError(f"Path must be absolute: {path}")
-        return path
-
-    def list_files(self) -> list[Path]:
-        """List files in the directory."""
-        if not self.path.exists():
-            raise FileNotFoundError(f"Directory not found: {self.path}")
-        if not self.path.is_dir():
-            raise NotADirectoryError(f"Not a directory: {self.path}")
-
-        try:
-            if self.pattern:
-                return (
-                    list(self.path.glob(self.pattern))
-                    if not self.recursive
-                    else list(self.path.rglob(self.pattern))
-                )
-            return (
-                list(self.path.glob("*"))
-                if not self.recursive
-                else list(self.path.rglob("*"))
-            )
-        except Exception as e:
-            raise ValueError(f"Error listing directory {self.path}: {e}")
-
-    async def read(self) -> str:  # Always returns JSON string
-        """Read the directory listing."""
-        try:
-            files = await asyncio.to_thread(self.list_files)
-            file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
-            return json.dumps({"files": file_list}, indent=2)
-        except Exception as e:
-            raise ValueError(f"Error reading directory {self.path}: {e}")
-
-
-class ResourceManager:
-    """Manages FastMCP resources."""
-
-    def __init__(self, warn_on_duplicate_resources: bool = True):
-        self._resources: Dict[str, Resource] = {}
-        self.warn_on_duplicate_resources = warn_on_duplicate_resources
-
-    def get_resource(self, uri: Union[_BaseUrl, str]) -> Optional[Resource]:
-        """Get resource by URI."""
-        uri = str(uri)
-        logger.debug("Getting resource", extra={"uri": uri})
-
-        if resource := self._resources.get(uri):
-            return resource
-
-        raise ValueError(f"Unknown resource: {uri}")
-
-    def list_resources(self) -> list[Resource]:
-        """List all registered resources."""
-        logger.debug("Listing resources", extra={"count": len(self._resources)})
-        return list(self._resources.values())
-
-    def add_resource(self, resource: Resource) -> Resource:
-        """Add a resource to the manager.
-
-        Args:
-            resource: A Resource instance to add
-
-        Returns:
-            The added resource. If a resource with the same URI already exists,
-            returns the existing resource.
-        """
-        logger.debug(
-            "Adding resource",
-            extra={
-                "uri": resource.uri,
-                "type": type(resource).__name__,
-                "name": resource.name,
-            },
-        )
-        existing = self._resources.get(str(resource.uri))
-        if existing:
-            if self.warn_on_duplicate_resources:
-                logger.warning(f"Resource already exists: {resource.uri}")
-            return existing
-        self._resources[str(resource.uri)] = resource
-        return resource
diff --git a/src/fastmcp/resources/__init__.py b/src/fastmcp/resources/__init__.py
new file mode 100644
index 000000000..68785c144
--- /dev/null
+++ b/src/fastmcp/resources/__init__.py
@@ -0,0 +1,24 @@
+from .function_resource import FunctionResource, resource
+from .resource 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",
+]
diff --git a/src/fastmcp/resources/function_resource.py b/src/fastmcp/resources/function_resource.py
new file mode 100644
index 000000000..5a3f28ee8
--- /dev/null
+++ b/src/fastmcp/resources/function_resource.py
@@ -0,0 +1,344 @@
+"""Standalone @resource decorator for FastMCP."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeVar, runtime_checkable
+
+from mcp.types import Annotations, Icon
+from pydantic import AnyUrl
+from pydantic.json_schema import SkipJsonSchema
+
+import fastmcp
+from fastmcp.decorators import resolve_task_config
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.server.apps import resolve_ui_mime_type
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.dependencies import (
+    transform_context_annotations,
+    without_injected_parameters,
+)
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+
+if TYPE_CHECKING:
+    from docket import Docket
+
+    from fastmcp.resources.template import ResourceTemplate
+
+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
+        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 or 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.
+
+        FunctionResource registers the underlying function, which has the user's
+        Depends parameters for docket to resolve.
+        """
+        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 create_resource(fn: Callable[..., Any]) -> FunctionResource | ResourceTemplate:
+        from fastmcp.resources.template import ResourceTemplate
+        from fastmcp.server.dependencies import without_injected_parameters
+
+        resolved = resolve_task_config(task)
+        has_uri_params = "{" in uri and "}" in uri
+        wrapper_fn = without_injected_parameters(fn)
+        has_func_params = bool(inspect.signature(wrapper_fn).parameters)
+
+        # Create metadata first
+        resource_meta = ResourceMeta(
+            uri=uri,
+            name=name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            mime_type=mime_type,
+            annotations=annotations,
+            meta=meta,
+            task=resolved,
+            auth=auth,
+        )
+
+        if has_uri_params or has_func_params:
+            # ResourceTemplate doesn't have metadata support yet, so pass individual params
+            return ResourceTemplate.from_function(
+                fn=fn,
+                uri_template=uri,
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                mime_type=mime_type,
+                tags=tags,
+                annotations=annotations,
+                meta=meta,
+                task=resolved,
+                auth=auth,
+            )
+        else:
+            return FunctionResource.from_function(fn, metadata=resource_meta)
+
+    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 hasattr(fn, "__func__") else fn
+        target.__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F) -> F:
+        if fastmcp.settings.decorator_mode == "object":
+            warnings.warn(
+                "decorator_mode='object' is deprecated and will be removed in a future version. "
+                "Decorators now return the original function with metadata attached.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            return create_resource(fn)  # type: ignore[return-value]
+        return attach_metadata(fn)
+
+    return decorator
diff --git a/src/fastmcp/resources/resource.py b/src/fastmcp/resources/resource.py
new file mode 100644
index 000000000..26ed535de
--- /dev/null
+++ b/src/fastmcp/resources/resource.py
@@ -0,0 +1,466 @@
+"""Base classes and interfaces for FastMCP resources."""
+
+from __future__ import annotations
+
+import base64
+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.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.utilities.components import FastMCPComponent
+
+
+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=AnyUrl(uri) if isinstance(uri, str) else uri,
+                text=self.content,
+                mimeType=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=AnyUrl(uri) if isinstance(uri, str) else uri,
+                blob=base64.b64encode(self.content).decode(),
+                mimeType=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
+        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)]
+            )
+
+        # ResourceResult.__init__ handles all other normalization
+        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=overrides.get("uri", self.uri),
+            description=overrides.get("description", self.description),
+            mimeType=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",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Deprecated re-exports for backwards compatibility."""
+    deprecated_exports = {
+        "FunctionResource": "FunctionResource",
+        "resource": "resource",
+    }
+
+    if name in deprecated_exports:
+        import warnings
+
+        import fastmcp
+
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                f"Importing {name} from fastmcp.resources.resource is deprecated. "
+                f"Import from fastmcp.resources.function_resource instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        from fastmcp.resources import function_resource
+
+        return getattr(function_resource, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/src/fastmcp/resources/template.py b/src/fastmcp/resources/template.py
new file mode 100644
index 000000000..ea96af425
--- /dev/null
+++ b/src/fastmcp/resources/template.py
@@ -0,0 +1,599 @@
+"""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, 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.resource import Resource, ResourceResult
+from fastmcp.server.apps import resolve_ui_mime_type
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.dependencies import (
+    transform_context_annotations,
+    without_injected_parameters,
+)
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.json_schema import compress_schema
+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:
+    """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)
+    """
+    # 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]
+                pattern += f"(?P<{name}>.+)"
+            else:
+                pattern += f"(?P<{name}>[^/]+)"
+        else:
+            pattern += re.escape(part)
+    return re.compile(f"^{pattern}$")
+
+
+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)
+    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)
+        parsed_query = parse_qs(query_string)
+
+        for name in query_param_names:
+            if name in parsed_query:
+                # Take first value if multiple provided
+                params[name] = parsed_query[name][0]
+
+    return params
+
+
+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),
+            uriTemplate=overrides.get("uriTemplate", self.uri_template),
+            description=overrides.get("description", self.description),
+            mimeType=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.uriTemplate,
+            name=mcp_template.name,
+            description=mcp_template.description,
+            mime_type=mcp_template.mimeType 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,
+            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.
+
+        FunctionResourceTemplate registers the underlying function, which has the
+        user's Depends parameters for docket to resolve.
+        """
+        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
+        path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
+        query_params = extract_query_params(uri_template)
+        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)
+        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 or 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/src/fastmcp/resources/types.py b/src/fastmcp/resources/types.py
new file mode 100644
index 000000000..30642683b
--- /dev/null
+++ b/src/fastmcp/resources/types.py
@@ -0,0 +1,180 @@
+"""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.resource 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",
+    )
+
+    @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()
+            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/src/fastmcp/server.py b/src/fastmcp/server.py
deleted file mode 100644
index 54cf5dff6..000000000
--- a/src/fastmcp/server.py
+++ /dev/null
@@ -1,323 +0,0 @@
-"""FastMCP - A more ergonomic interface for MCP servers."""
-
-import asyncio
-import functools
-import json
-import logging
-from typing import Any, Callable, Optional, Sequence, Union, Literal
-
-import pydantic.json
-from mcp.server import Server as MCPServer
-from mcp.server.stdio import stdio_server
-from mcp.server.sse import SseServerTransport
-from mcp.types import (
-    Resource as MCPResource,
-    Tool,
-    TextContent,
-    ImageContent,
-)
-from pydantic_settings import BaseSettings
-from pydantic.networks import _BaseUrl
-
-from .exceptions import ResourceError
-from .resources import Resource, FunctionResource, ResourceManager
-from .tools import ToolManager, Image
-from .utilities.logging import get_logger, configure_logging
-
-logger = get_logger(__name__)
-
-
-class Settings(BaseSettings):
-    """FastMCP server settings.
-
-    All settings can be configured via environment variables with the prefix FASTMCP_.
-    For example, FASTMCP_DEBUG=true will set debug=True.
-    """
-
-    model_config: dict = dict(env_prefix="FASTMCP_")
-
-    # Server settings
-    debug: bool = False
-    log_level: Literal[
-        logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL
-    ] = logging.INFO
-
-    # HTTP settings
-    host: str = "0.0.0.0"
-    port: int = 8000
-
-    # resource settings
-    warn_on_duplicate_resources: bool = True
-
-    # tool settings
-    warn_on_duplicate_tools: bool = True
-
-
-class FastMCP:
-    def __init__(self, name=None, **settings: Optional[Settings]):
-        self.settings = Settings(**settings)
-        self._mcp_server = MCPServer(name=name or "FastMCP")
-        self._tool_manager = ToolManager(
-            warn_on_duplicate_tools=self.settings.warn_on_duplicate_tools
-        )
-        self._resource_manager = ResourceManager(
-            warn_on_duplicate_resources=self.settings.warn_on_duplicate_resources
-        )
-
-        # Set up MCP protocol handlers
-        self._setup_handlers()
-
-        # Configure logging
-        configure_logging(self.settings.log_level)
-
-    @property
-    def name(self) -> str:
-        return self._mcp_server.name
-
-    def run(self, transport: Literal["stdio", "sse"] = "stdio") -> None:
-        """Run the FastMCP server. Note this is a synchronous function.
-
-        Args:
-            transport: Transport protocol to use ("stdio" or "sse")
-        """
-        TRANSPORTS = Literal["stdio", "sse"]
-        if transport not in TRANSPORTS.__args__:  # type: ignore
-            raise ValueError(f"Unknown transport: {transport}")
-
-        if transport == "stdio":
-            asyncio.run(self.run_stdio_async())
-        else:  # transport == "sse"
-            asyncio.run(self.run_sse_async())
-
-    def _setup_handlers(self) -> None:
-        """Set up core MCP protocol handlers."""
-        self._mcp_server.list_tools()(self.list_tools)
-        self._mcp_server.call_tool()(self.call_tool)
-        self._mcp_server.list_resources()(self.list_resources)
-        self._mcp_server.read_resource()(self.read_resource)
-
-    async def list_tools(self) -> list[Tool]:
-        """List all available tools."""
-        tools = self._tool_manager.list_tools()
-        return [
-            Tool(
-                name=info.name,
-                description=info.description,
-                inputSchema=info.parameters,
-            )
-            for info in tools
-        ]
-
-    async def call_tool(
-        self, name: str, arguments: dict
-    ) -> Sequence[Union[TextContent, ImageContent]]:
-        """Call a tool by name with arguments."""
-        try:
-            result = await self._tool_manager.call_tool(name, arguments)
-            return self._convert_to_content(result)
-        except Exception as e:
-            logger.error(f"Error calling tool {name}: {e}")
-            return [
-                TextContent(
-                    type="text",
-                    text=str(e),
-                    is_error=True,
-                )
-            ]
-
-    async def list_resources(self) -> list[MCPResource]:
-        """List all available resources."""
-
-        resources = self._resource_manager.list_resources()
-        return [
-            MCPResource(
-                uri=resource.uri,
-                name=resource.name,
-                description=resource.description,
-                mimeType=resource.mime_type,
-            )
-            for resource in resources
-        ]
-
-    async def read_resource(self, uri: _BaseUrl) -> Union[str, bytes]:
-        """Read a resource by URI."""
-        resource = self._resource_manager.get_resource(uri)
-        if not resource:
-            raise ResourceError(f"Unknown resource: {uri}")
-
-        try:
-            return await resource.read()
-        except Exception as e:
-            logger.error(f"Error reading resource {uri}: {e}")
-            raise ResourceError(str(e))
-
-    def _convert_to_content(
-        self, value: Any
-    ) -> Sequence[Union[TextContent, ImageContent]]:
-        """Convert a tool result to MCP content types."""
-
-        # Already a sequence of valid content types
-        if isinstance(value, (list, tuple)):
-            if all(isinstance(x, (TextContent, ImageContent)) for x in value):
-                return value
-            # Handle mixed content including Image objects
-            result = []
-            for item in value:
-                if isinstance(item, (TextContent, ImageContent)):
-                    result.append(item)
-                elif isinstance(item, Image):
-                    result.append(item.to_image_content())
-                else:
-                    result.append(
-                        TextContent(
-                            type="text",
-                            text=json.dumps(
-                                item, indent=2, default=pydantic.json.pydantic_encoder
-                            ),
-                        )
-                    )
-            return result
-
-        # Single content type
-        if isinstance(value, (TextContent, ImageContent)):
-            return [value]
-
-        # Image helper
-        if isinstance(value, Image):
-            return [value.to_image_content()]
-
-        # All other types - convert to JSON string with pydantic encoder
-        return [
-            TextContent(
-                type="text",
-                text=json.dumps(
-                    value, indent=2, default=pydantic.json.pydantic_encoder
-                ),
-            )
-        ]
-
-    def add_tool(
-        self,
-        func: Callable,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-    ) -> None:
-        """Add a tool to the server."""
-        self._tool_manager.add_tool(func, name=name, description=description)
-
-    def tool(
-        self, name: Optional[str] = None, description: Optional[str] = None
-    ) -> Callable:
-        """Decorator to register a tool."""
-        # Check if user passed function directly instead of calling decorator
-        if callable(name):
-            raise TypeError(
-                "The @tool decorator was used incorrectly. "
-                "Did you forget to call it? Use @tool() instead of @tool"
-            )
-
-        def decorator(func: Callable) -> Callable:
-            self.add_tool(func, name=name, description=description)
-            return func
-
-        return decorator
-
-    def add_resource(self, resource: Resource) -> None:
-        """Add a resource to the server.
-
-        Args:
-            resource: A Resource instance to add
-        """
-        self._resource_manager.add_resource(resource)
-
-    def resource(
-        self,
-        uri: str,
-        *,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-        mime_type: Optional[str] = None,
-    ) -> Callable:
-        """Decorator to register a function as a resource.
-
-        The function will be called when the resource is read to generate its content.
-
-        Args:
-            uri: URI for the resource (e.g. "resource://my-resource")
-            description: Optional description of the resource
-            mime_type: Optional MIME type for the resource
-
-        Example:
-            @server.resource("resource://my-resource")
-            def get_data() -> str:
-                return "Hello, world!"
-        """
-        # Check if user passed function directly instead of calling decorator
-        if callable(uri):
-            raise TypeError(
-                "The @resource decorator was used incorrectly. "
-                "Did you forget to call it? Use @resource('uri') instead of @resource"
-            )
-
-        def decorator(func: Callable) -> Callable:
-            @functools.wraps(func)
-            def wrapper() -> Any:
-                return func()
-
-            resource = FunctionResource(
-                uri=uri,
-                name=name,
-                description=description,
-                mime_type=mime_type or "text/plain",
-                func=wrapper,
-            )
-            self.add_resource(resource)
-            return wrapper
-
-        return decorator
-
-    async def run_stdio_async(self) -> None:
-        """Run the server using stdio transport."""
-        async with stdio_server() as (read_stream, write_stream):
-            print(f'Starting "{self.name}"...')
-            await self._mcp_server.run(
-                read_stream,
-                write_stream,
-                self._mcp_server.create_initialization_options(),
-            )
-
-    async def run_sse_async(self) -> None:
-        """Run the server using SSE transport."""
-        from starlette.applications import Starlette
-        from starlette.routing import Route
-        import uvicorn
-
-        sse = SseServerTransport("/messages")
-
-        async def handle_sse(request):
-            async with sse.connect_sse(
-                request.scope, request.receive, request._send
-            ) as streams:
-                await self._mcp_server.run(
-                    streams[0],
-                    streams[1],
-                    self._mcp_server.create_initialization_options(),
-                )
-
-        async def handle_messages(request):
-            await sse.handle_post_message(request.scope, request.receive, request._send)
-
-        starlette_app = Starlette(
-            debug=self.settings.debug,
-            routes=[
-                Route("/sse", endpoint=handle_sse),
-                Route("/messages", endpoint=handle_messages, methods=["POST"]),
-            ],
-        )
-
-        uvicorn.run(
-            starlette_app,
-            host=self.settings.host,
-            port=self.settings.port,
-            log_level=self.settings.log_level,
-        )
diff --git a/src/fastmcp/server/__init__.py b/src/fastmcp/server/__init__.py
new file mode 100644
index 000000000..3f64a0f39
--- /dev/null
+++ b/src/fastmcp/server/__init__.py
@@ -0,0 +1,13 @@
+import importlib
+
+from .context import Context
+from .server import FastMCP, create_proxy
+
+
+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/src/fastmcp/server/apps.py b/src/fastmcp/server/apps.py
new file mode 100644
index 000000000..fcb0b673c
--- /dev/null
+++ b/src/fastmcp/server/apps.py
@@ -0,0 +1,142 @@
+"""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
+
+UI_EXTENSION_ID = "io.modelcontextprotocol/ui"
+UI_MIME_TYPE = "text/html;profile=mcp-app"
+
+
+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,
+        alias="connectDomains",
+        description="Origins allowed for fetch/XHR/WebSocket (connect-src)",
+    )
+    resource_domains: list[str] | None = Field(
+        default=None,
+        alias="resourceDomains",
+        description="Origins allowed for scripts, images, styles, fonts (script-src etc.)",
+    )
+    frame_domains: list[str] | None = Field(
+        default=None,
+        alias="frameDomains",
+        description="Origins allowed for nested iframes (frame-src)",
+    )
+    base_uri_domains: list[str] | None = Field(
+        default=None,
+        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,
+        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,
+        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,
+        alias="prefersBorder",
+        description="Whether the UI prefers a visible border",
+    )
+
+    model_config = {"populate_by_name": True, "extra": "allow"}
+
+
+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
+
+
+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. This ensures UI resources are correctly
+    identified regardless of how they're registered (via FastMCP.resource,
+    the standalone @resource decorator, or resource templates).
+
+    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
+    # Case-insensitive scheme check per RFC 3986
+    if uri.lower().startswith("ui://"):
+        return UI_MIME_TYPE
+    return None
diff --git a/src/fastmcp/server/auth/__init__.py b/src/fastmcp/server/auth/__init__.py
new file mode 100644
index 000000000..cd6a300ad
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/auth.py b/src/fastmcp/server/auth/auth.py
new file mode 100644
index 000000000..873c1945a
--- /dev/null
+++ b/src/fastmcp/server/auth/auth.py
@@ -0,0 +1,786 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, cast
+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,
+    ):
+        """
+        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.
+            required_scopes: List of OAuth scopes required for all requests.
+        """
+        if isinstance(base_url, str):
+            base_url = AnyHttpUrl(base_url)
+        self.base_url = 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
+        """
+        # TODO(ty): remove type ignores when ty supports Starlette Middleware typing
+        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.
+
+        Args:
+            path: The path where the resource endpoint is mounted (e.g., "/mcp")
+
+        Returns:
+            The full URL of the protected resource
+        """
+        if self.base_url is None:
+            return None
+
+        if path:
+            prefix = str(self.base_url).rstrip("/")
+            suffix = path.lstrip("/")
+            return AnyHttpUrl(f"{prefix}/{suffix}")
+        return self.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,
+    ):
+        """
+        Initialize the token verifier.
+
+        Args:
+            base_url: The base URL of this server
+            required_scopes: Scopes that are required for all requests
+        """
+        super().__init__(base_url=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_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
+            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,
+            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).
+        """
+        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,
+        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.
+            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_scopes = (
+            required_scopes
+            if required_scopes is not None
+            else (server.required_scopes if server else None)
+        )
+
+        super().__init__(base_url=effective_base_url, required_scopes=effective_scopes)
+        self.server = server
+        self.verifiers = list(verifiers)
+
+        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,
+        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
+            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, 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=[cast(AnyHttpUrl, 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)
+
+        # RFC 8414: If issuer_url has a path, use path-aware discovery
+        if self.issuer_url:
+            parsed = urlparse(str(self.issuer_url))
+            issuer_path = parsed.path.rstrip("/")
+
+            if issuer_path and issuer_path != "/":
+                # Replace /.well-known/oauth-authorization-server with path-aware version
+                new_routes = []
+                for route in routes:
+                    if route.path == "/.well-known/oauth-authorization-server":
+                        new_path = (
+                            f"/.well-known/oauth-authorization-server{issuer_path}"
+                        )
+                        new_routes.append(
+                            Route(
+                                new_path,
+                                endpoint=route.endpoint,
+                                methods=route.methods,
+                            )
+                        )
+                    else:
+                        new_routes.append(route)
+                return new_routes
+
+        return routes
diff --git a/src/fastmcp/server/auth/authorization.py b/src/fastmcp/server/auth/authorization.py
new file mode 100644
index 000000000..8455b81f5
--- /dev/null
+++ b/src/fastmcp/server/auth/authorization.py
@@ -0,0 +1,182 @@
+"""Authorization checks for FastMCP components.
+
+This module provides callable-based authorization for tools, resources, and prompts.
+Auth checks are functions that receive an AuthContext and return True to allow access
+or False to deny.
+
+Auth checks can also raise exceptions:
+- AuthorizationError: Propagates with the custom message for explicit denial
+- Other exceptions: Masked for security (logged, treated as auth failure)
+
+Example:
+    ```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(): ...
+    ```
+"""
+
+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.tool import Tool
+    from fastmcp.utilities.components import FastMCPComponent
+
+
+@dataclass
+class AuthContext:
+    """Context passed to auth check callables.
+
+    This object is passed to each auth check function and provides
+    access to the current authentication token and the component being accessed.
+
+    Attributes:
+        token: The current access token, or None if unauthenticated.
+        component: The component (tool, resource, or prompt) being accessed.
+        tool: Backwards-compatible alias for component when it's a Tool.
+    """
+
+    token: AccessToken | None
+    component: FastMCPComponent
+
+    @property
+    def tool(self) -> Tool | None:
+        """Backwards-compatible access to the component as a Tool.
+
+        Returns the component if it's a Tool, None otherwise.
+        """
+        from fastmcp.tools.tool import Tool
+
+        return self.component if isinstance(self.component, Tool) else None
+
+
+# Type alias for auth check functions (sync or async)
+AuthCheck = Callable[[AuthContext], bool] | Callable[[AuthContext], Awaitable[bool]]
+
+
+def require_scopes(*scopes: str) -> AuthCheck:
+    """Require specific OAuth scopes.
+
+    Returns an auth check that requires ALL specified scopes to be present
+    in the token (AND logic).
+
+    Args:
+        *scopes: One or more scope strings that must all be present.
+
+    Example:
+        ```python
+        @mcp.tool(auth=require_scopes("admin"))
+        def admin_tool(): ...
+
+        @mcp.tool(auth=require_scopes("read", "write"))
+        def read_write_tool(): ...
+        ```
+    """
+    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:
+    """Restrict components with a specific tag to require certain scopes.
+
+    If the component has the specified tag, the token must have ALL the
+    required scopes. If the component doesn't have the tag, access is allowed.
+
+    Args:
+        tag: The tag that triggers the scope requirement.
+        scopes: List of scopes required when the tag is present.
+
+    Example:
+        ```python
+        # Components tagged "admin" require the "admin" scope
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+        ```
+    """
+    required = set(scopes)
+
+    def check(ctx: AuthContext) -> bool:
+        if tag not in ctx.component.tags:
+            return True  # Tag not present, no restriction
+        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.
+
+    All checks must pass for authorization to succeed. Checks can be
+    synchronous or asynchronous functions.
+
+    Auth checks can:
+    - Return True to allow access
+    - Return False to deny access
+    - Raise AuthorizationError to deny with a custom message (propagates)
+    - Raise other exceptions (masked for security, treated as denial)
+
+    Args:
+        checks: A single check function or list of check functions.
+            Each check can be sync (returns bool) or async (returns Awaitable[bool]).
+        ctx: The auth context to pass to each check.
+
+    Returns:
+        True if all checks pass, False if any check fails.
+
+    Raises:
+        AuthorizationError: If an auth check explicitly raises it.
+    """
+    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:
+            # Let AuthorizationError propagate with its custom message
+            raise
+        except Exception:
+            # Mask other exceptions for security - log and treat as auth failure
+            logger.warning(
+                f"Auth check {getattr(check, '__name__', repr(check))} "
+                "raised an unexpected exception",
+                exc_info=True,
+            )
+            return False
+
+    return True
diff --git a/src/fastmcp/server/auth/cimd.py b/src/fastmcp/server/auth/cimd.py
new file mode 100644
index 000000000..caef56f96
--- /dev/null
+++ b/src/fastmcp/server/auth/cimd.py
@@ -0,0 +1,799 @@
+"""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 fnmatch
+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 pydantic import AnyHttpUrl, BaseModel, Field, field_validator
+
+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__)
+
+
+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.
+
+        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 redirect_uri == allowed_str:
+                return True
+
+            # Check for wildcard port matching (http://localhost:*/callback)
+            if "*" in allowed_str:
+                if fnmatch.fnmatch(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
+        """
+        import base64
+        import json
+
+        from authlib.jose import JsonWebKey
+
+        # 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 Exception 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:
+            jwk = JsonWebKey.import_key(matching_key)
+            return jwk.as_pem().decode("utf-8")
+        except Exception 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/src/fastmcp/server/auth/handlers/authorize.py b/src/fastmcp/server/auth/handlers/authorize.py
new file mode 100644
index 000000000..f91b266b7
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/jwt_issuer.py b/src/fastmcp/server/auth/jwt_issuer.py
new file mode 100644
index 000000000..90d7bc0cf
--- /dev/null
+++ b/src/fastmcp/server/auth/jwt_issuer.py
@@ -0,0 +1,246 @@
+"""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 authlib.jose import JsonWebToken
+from authlib.jose.errors import JoseError
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+KDF_ITERATIONS = 1000000
+
+
+@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:
+        pbkdf2 = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            iterations=KDF_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 = JsonWebToken(["HS256"])
+
+    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_bytes = self._jwt.encode(header, payload, self._signing_key)
+        token = token_bytes.decode("utf-8")
+
+        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_bytes = self._jwt.encode(header, payload, self._signing_key)
+        token = token_bytes.decode("utf-8")
+
+        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) -> dict[str, Any]:
+        """Verify and decode a FastMCP token.
+
+        Validates JWT signature, expiration, issuer, and audience.
+
+        Args:
+            token: JWT token to verify
+
+        Returns:
+            Decoded token payload
+
+        Raises:
+            JoseError: If token is invalid, expired, or has wrong claims
+        """
+        try:
+            # Decode and verify signature
+            payload = self._jwt.decode(token, self._signing_key)
+
+            # Validate expiration
+            exp = payload.get("exp")
+            if exp 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/src/fastmcp/server/auth/middleware.py b/src/fastmcp/server/auth/middleware.py
new file mode 100644
index 000000000..a7e80a7ff
--- /dev/null
+++ b/src/fastmcp/server/auth/middleware.py
@@ -0,0 +1,96 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.auth.middleware.bearer_auth import (
+    RequireAuthMiddleware as SDKRequireAuthMiddleware,
+)
+from starlette.types import 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.
+    """
+
+    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/src/fastmcp/server/auth/oauth_proxy/__init__.py b/src/fastmcp/server/auth/oauth_proxy/__init__.py
new file mode 100644
index 000000000..5e9ff4315
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/oauth_proxy/consent.py b/src/fastmcp/server/auth/oauth_proxy/consent.py
new file mode 100644
index 000000000..0d7ccc32f
--- /dev/null
+++ b/src/fastmcp/server/auth/oauth_proxy/consent.py
@@ -0,0 +1,478 @@
+"""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.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
+
+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 _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 _sign_cookie(self: OAuthProxy, payload: str) -> str:
+        """Sign a cookie payload with HMAC-SHA256.
+
+        Returns: base64(payload).base64(signature)
+        """
+        # Use upstream client secret as signing key
+        key = self._upstream_client_secret.get_secret_value().encode()
+        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._upstream_client_secret.get_secret_value().encode()
+            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."""
+        # Prefer secure name, but also check non-secure variant for dev
+        secure_name = self._cookie_name(base_name)
+        raw = request.cookies.get(secure_name) or 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 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"])
+
+        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:
+            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,
+            )
+
+        # 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)
+        # Store CSRF in cookie with short lifetime
+        self._set_list_cookie(
+            response,
+            "MCP_CONSENT_STATE",
+            self._encode_list_cookie([csrf_token]),
+            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
+            )
+
+        client_key = self._make_client_key(txn["client_id"], txn["client_redirect_uri"])
+
+        if action == "approve":
+            approved = set(self._decode_list_cookie(request, "MCP_APPROVED_CLIENTS"))
+            if client_key not in approved:
+                approved.add(client_key)
+            approved_b64 = self._encode_list_cookie(sorted(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_list_cookie(
+                response, "MCP_APPROVED_CLIENTS", approved_b64, 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":
+            denied = set(self._decode_list_cookie(request, "MCP_DENIED_CLIENTS"))
+            if client_key not in denied:
+                denied.add(client_key)
+            denied_b64 = self._encode_list_cookie(sorted(denied))
+
+            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)
+            self._set_list_cookie(
+                response, "MCP_DENIED_CLIENTS", denied_b64, 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/src/fastmcp/server/auth/oauth_proxy/models.py b/src/fastmcp/server/auth/oauth_proxy/models.py
new file mode 100644
index 000000000..b78decf17
--- /dev/null
+++ b/src/fastmcp/server/auth/oauth_proxy/models.py
@@ -0,0 +1,252 @@
+"""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 mcp.shared.auth import InvalidRedirectUriError, OAuthClientInformationFull
+from pydantic import AnyUrl, BaseModel, Field
+
+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_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()
+
+
+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)
+
+    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 first, falling back to
+        base validation (registered redirect_uris) if patterns don't match.
+        """
+        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 Exception as e:
+                    raise InvalidRedirectUriError(
+                        f"Invalid CIMD redirect_uri: {e}"
+                    ) from e
+
+                # Respect proxy-level redirect URI restrictions even when the
+                # client omits redirect_uri and we fall back to CIMD defaults.
+                if (
+                    self.allowed_redirect_uri_patterns is not None
+                    and 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:
+            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
+
+            pattern_matches = validate_redirect_uri(
+                redirect_uri=redirect_uri,
+                allowed_patterns=self.allowed_redirect_uri_patterns,
+            )
+
+            if pattern_matches:
+                return redirect_uri
+
+            # Patterns configured but didn't match
+            if self.allowed_redirect_uri_patterns:
+                raise InvalidRedirectUriError(
+                    f"Redirect URI '{redirect_uri}' does not match allowed patterns."
+                )
+
+        # No redirect_uri provided or no patterns configured — use base validation
+        return super().validate_redirect_uri(redirect_uri)
diff --git a/src/fastmcp/server/auth/oauth_proxy/proxy.py b/src/fastmcp/server/auth/oauth_proxy/proxy.py
new file mode 100644
index 000000000..0a72ae9f9
--- /dev/null
+++ b/src/fastmcp/server/auth/oauth_proxy/proxy.py
@@ -0,0 +1,1827 @@
+"""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 typing import Any
+from urllib.parse import urlencode, urlparse, urlunparse
+
+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,
+    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,
+    HTTP_TIMEOUT_SECONDS,
+    ClientCode,
+    JTIMapping,
+    OAuthTransaction,
+    ProxyDCRClient,
+    RefreshTokenMetadata,
+    UpstreamTokenSet,
+    _hash_token,
+)
+from fastmcp.server.auth.oauth_proxy.ui import create_error_html
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+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,
+        upstream_revocation_endpoint: str | None = None,
+        # Token validation
+        token_verifier: TokenVerifier,
+        # FastMCP server configuration
+        base_url: AnyHttpUrl | str,
+        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,
+        # 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 = True,
+        consent_csp_policy: str | None = None,
+        # Token expiry fallback
+        fallback_access_token_expiry_seconds: int | None = None,
+        # 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
+            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
+            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), all redirect URIs are allowed (for DCR compatibility).
+                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: 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.
+                SECURITY WARNING: Only disable 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.
+            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.
+        """
+
+        # Always enable DCR since we implement it locally for MCP clients
+        client_registration_options = ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=valid_scopes or token_verifier.required_scopes,
+        )
+
+        # Enable revocation only if upstream endpoint provided
+        revocation_options = (
+            RevocationOptions(enabled=True) if upstream_revocation_endpoint else None
+        )
+
+        super().__init__(
+            base_url=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 = SecretStr(
+            secret_value=upstream_client_secret
+        )
+        self._upstream_revocation_endpoint: str | None = upstream_revocation_endpoint
+        self._default_scope_str: str = " ".join(self.required_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
+
+        # Token endpoint authentication
+        self._token_endpoint_auth_method: str | None = token_endpoint_auth_method
+
+        # Consent screen configuration
+        self._require_authorization_consent: bool = require_authorization_consent
+        self._consent_csp_policy: str | None = consent_csp_policy
+        if 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
+        )
+
+        if jwt_signing_key is None:
+            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,
+            )
+
+        logger.debug(
+            "Initialized OAuth proxy provider with upstream server %s",
+            self._upstream_authorization_endpoint,
+        )
+
+    # -------------------------------------------------------------------------
+    # 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
+
+    # -------------------------------------------------------------------------
+    # 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 client.allowed_redirect_uri_patterns is 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
+
+        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")
+        # 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=client_info.redirect_uris or [AnyUrl("http://localhost")],
+            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), skip the consent screen
+        and redirect directly to the upstream IdP.
+        """
+        # 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
+                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, skip consent screen and go directly to upstream IdP
+        if not self._require_authorization_consent:
+            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
+                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
+
+        # 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
+            )
+
+        # 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:
+                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:
+                # Default to 30 days if upstream doesn't specify
+                # This is conservative - most providers use longer expiry
+                refresh_expires_in = 60 * 60 * 24 * 30  # 30 days
+                refresh_token_expires_at = time.time() + refresh_expires_in
+                logger.debug(
+                    "Upstream refresh token expiry unknown, using 30-day default"
+                )
+
+        # 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(authorization_code.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, 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=authorization_code.scopes,
+            jti=access_jti,
+            expires_in=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=authorization_code.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=expires_in,  # Auto-expire with 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=60 * 60 * 24 * 30,  # Auto-expire with refresh token (30 days)
+            )
+
+        # 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=authorization_code.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=expires_in,
+            refresh_token=fastmcp_refresh_token,
+            scope=" ".join(authorization_code.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 _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:
+            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)
+            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")
+
+        # Refresh upstream token using authlib
+        oauth_client = AsyncOAuth2Client(
+            client_id=self._upstream_client_id,
+            client_secret=self._upstream_client_secret.get_secret_value(),
+            token_endpoint_auth_method=self._token_endpoint_auth_method,
+            timeout=HTTP_TIMEOUT_SECONDS,
+        )
+
+        # 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])
+            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
+
+        # 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:
+                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:
+                # Default to 30 days if unknown
+                new_refresh_expires_in = 60 * 60 * 24 * 30
+                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 60 * 60 * 24 * 30  # Default to 30 days if unknown
+        )
+        await self._upstream_token_store.put(
+            key=upstream_token_set.upstream_token_id,
+            value=upstream_token_set,
+            ttl=max(
+                refresh_ttl, new_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=scopes,
+            jti=new_access_jti,
+            expires_in=new_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=new_expires_in,  # Auto-expire with refreshed access token
+        )
+
+        # Issue NEW minimal FastMCP refresh token (rotation for security)
+        # Use upstream refresh token expiry to align lifetimes
+        new_refresh_jti = secrets.token_urlsafe(32)
+        new_fastmcp_refresh = self.jwt_issuer.issue_refresh_token(
+            client_id=client.client_id,
+            scopes=scopes,
+            jti=new_refresh_jti,
+            expires_in=new_refresh_expires_in
+            or 60 * 60 * 24 * 30,  # Fallback to 30 days
+            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=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=new_expires_in,
+            refresh_token=new_fastmcp_refresh,  # NEW refresh token (rotated)
+            scope=" ".join(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
+
+    async def load_access_token(self, token: str) -> AccessToken | None:  # type: ignore[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. 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"]
+
+            # 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)
+
+            if not validated:
+                logger.debug("Upstream token validation failed")
+                return None
+
+            # When the verification token differs from the access token
+            # (e.g., id_token verification), ensure the returned AccessToken
+            # carries the upstream access token and its scopes, not the
+            # verification token's values.
+            if verification_token != upstream_token_set.access_token:
+                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),
+                    }
+                )
+
+            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:
+                    await http_client.post(
+                        self._upstream_revocation_endpoint,
+                        data={"token": token.token},
+                        auth=(
+                            self._upstream_client_id,
+                            self._upstream_client_secret.get_secret_value(),
+                        ),
+                    )
+                    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
+                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 error:
+                error_description = request.query_params.get("error_description")
+                logger.error(
+                    "IdP callback error: %s - %s",
+                    error,
+                    error_description,
+                )
+                # Show error page to user
+                html_content = create_error_html(
+                    error_title="OAuth Error",
+                    error_message=f"Authentication failed: {error_description or 'Unknown error'}",
+                    error_details={"Error Code": error} if error else None,
+                )
+                return HTMLResponse(content=html_content, status_code=400)
+
+            if not idp_code or not txn_id:
+                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 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)
+            # 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.
+            if self._require_authorization_consent:
+                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()
+
+            # Exchange IdP code for tokens (server-side)
+            oauth_client = AsyncOAuth2Client(
+                client_id=self._upstream_client_id,
+                client_secret=self._upstream_client_secret.get_secret_value(),
+                token_endpoint_auth_method=self._token_endpoint_auth_method,
+                timeout=HTTP_TIMEOUT_SECONDS,
+            )
+
+            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()),
+                    )
+
+                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/src/fastmcp/server/auth/oauth_proxy/ui.py b/src/fastmcp/server/auth/oauth_proxy/ui.py
new file mode 100644
index 000000000..4ae6b5fb5
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/oidc_proxy.py b/src/fastmcp/server/auth/oidc_proxy.py
new file mode 100644
index 000000000..418bea34c
--- /dev/null
+++ b/src/fastmcp/server/auth/oidc_proxy.py
@@ -0,0 +1,471 @@
+"""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
+
+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__)
+
+
+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 = {}
+        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,
+        audience: str | None = None,
+        timeout_seconds: int | None = None,
+        # 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,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        # 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,
+        # 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
+            audience: Audience for upstream server
+            timeout_seconds: HTTP request timeout in seconds
+            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)
+            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), all redirect URIs are allowed (for DCR compatibility).
+                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.
+                SECURITY WARNING: Only disable 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).
+            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:
+            raise ValueError("Missing required client secret")
+
+        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,
+            "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,
+            "fallback_access_token_expiry_seconds": fallback_access_token_expiry_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._default_scope_str = " ".join(required_scopes)
+            if self.client_registration_options:
+                self.client_registration_options.valid_scopes = required_scopes
+            if self._cimd_manager is not None:
+                self._cimd_manager.default_scope = self._default_scope_str
+
+    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 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/src/fastmcp/server/auth/providers/__init__.py b/src/fastmcp/server/auth/providers/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/server/auth/providers/auth0.py b/src/fastmcp/server/auth/providers/auth0.py
new file mode 100644
index 000000000..3eec61776
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/auth0.py
@@ -0,0 +1,125 @@
+"""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 key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oidc_proxy import 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,
+        base_url: AnyHttpUrl | str,
+        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 = True,
+        consent_csp_policy: str | None = None,
+    ) -> 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
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            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.
+                SECURITY WARNING: Only disable for local development or testing environments.
+        """
+        # 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,
+            base_url=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,
+        )
+
+        logger.debug(
+            "Initialized Auth0 OAuth provider for client %s with scopes: %s",
+            client_id,
+            auth0_required_scopes,
+        )
diff --git a/src/fastmcp/server/auth/providers/aws.py b/src/fastmcp/server/auth/providers/aws.py
new file mode 100644
index 000000000..58f1ab5a1
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/aws.py
@@ -0,0 +1,196 @@
+"""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 key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oidc_proxy import 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 that filters claims to Cognito-specific subset."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token and filter claims to Cognito-specific subset."""
+        # Use base JWT verification
+        access_token = await super().verify_token(token)
+        if not access_token:
+            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 new AccessToken with filtered claims
+        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,
+        base_url: AnyHttpUrl | str,
+        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 = True,
+        consent_csp_policy: str | None = None,
+    ):
+        """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
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            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.
+                SECURITY WARNING: Only disable for local development or testing environments.
+        """
+        # 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,
+            algorithm="RS256",
+            required_scopes=required_scopes_final,
+            base_url=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,
+        )
+
+        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/src/fastmcp/server/auth/providers/azure.py b/src/fastmcp/server/auth/providers/azure.py
new file mode 100644
index 000000000..009cf9316
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/azure.py
@@ -0,0 +1,725 @@
+"""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, cast
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+
+from fastmcp.dependencies import Dependency
+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
+
+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,
+        tenant_id: str,
+        required_scopes: list[str],
+        base_url: str,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        base_authority: str = "login.microsoftonline.com",
+        http_client: httpx.AsyncClient | None = None,
+    ) -> 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
+            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)
+            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".
+            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.
+                SECURITY WARNING: Only disable 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.
+        """
+        # 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
+
+        # 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 = 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).
+        if parsed_required_scopes:
+            validation_scopes = [
+                s for s in parsed_required_scopes if s not in OIDC_SCOPES
+            ]
+            # If all scopes were OIDC scopes, use None (no scope validation)
+            if not validation_scopes:
+                validation_scopes = None
+        else:
+            validation_scopes = None
+
+        token_verifier = JWTVerifier(
+            jwks_uri=jwks_uri,
+            issuer=issuer,
+            audience=client_id,
+            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,
+            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,
+            valid_scopes=parsed_required_scopes,
+        )
+
+        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,
+        )
+
+    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 _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
+        prefixed_scopes = self._prefix_scopes_for_azure(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)
+
+        # 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 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:
+            ImportError: If azure-identity is not installed (requires fastmcp[azure]).
+        """
+        _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]
+
+        credential = OnBehalfOfCredential(
+            tenant_id=self._tenant_id,
+            client_id=self._upstream_client_id,
+            client_secret=self._upstream_client_secret.get_secret_value(),
+            user_assertion=user_assertion,
+            authority=f"https://{self._base_authority}",
+        )
+        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,
+            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
+
+
+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()
+        if not isinstance(server.auth, AzureProvider):
+            raise RuntimeError(
+                "EntraOBOToken requires an AzureProvider as the auth provider. "
+                f"Current provider: {type(server.auth).__name__}"
+            )
+
+        credential = await server.auth.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/src/fastmcp/server/auth/providers/debug.py b/src/fastmcp/server/auth/providers/debug.py
new file mode 100644
index 000000000..5b6de01e3
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/providers/descope.py b/src/fastmcp/server/auth/providers/descope.py
new file mode 100644
index 000000000..3bdccf8d5
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/providers/discord.py b/src/fastmcp/server/auth/providers/discord.py
new file mode 100644
index 000000000..c07dfd86f
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/discord.py
@@ -0,0 +1,275 @@
+"""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
+
+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,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """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)
+            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.
+                SECURITY WARNING: Only disable 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.
+        """
+        # 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,
+            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,
+        )
+
+        logger.debug(
+            "Initialized Discord OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/src/fastmcp/server/auth/providers/github.py b/src/fastmcp/server/auth/providers/github.py
new file mode 100644
index 000000000..3d0c31d27
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/github.py
@@ -0,0 +1,258 @@
+"""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
+
+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 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.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+        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
+            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
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify GitHub OAuth token by calling GitHub 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:
+                # 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
+                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
+                return 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,
+                    },
+                )
+
+        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,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """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)
+            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)
+            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.
+                SECURITY WARNING: Only disable 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.
+        """
+        # 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,
+            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,
+            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,
+        )
+
+        logger.debug(
+            "Initialized GitHub OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/src/fastmcp/server/auth/providers/google.py b/src/fastmcp/server/auth/providers/google.py
new file mode 100644
index 000000000..265a9dd48
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/google.py
@@ -0,0 +1,295 @@
+"""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
+
+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 GoogleTokenVerifier(TokenVerifier):
+    """Token verifier for Google OAuth tokens.
+
+    Google OAuth tokens are opaque (not JWTs), so we verify them
+    by calling Google's tokeninfo API to check if they're valid and get user info.
+    """
+
+    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.
+        """
+        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 Google OAuth token by calling Google'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 Google's tokeninfo endpoint to validate the token
+                response = await client.get(
+                    "https://www.googleapis.com/oauth2/v1/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_info = response.json()
+
+                # Check if token is expired
+                expires_in = token_info.get("expires_in")
+                if expires_in and int(expires_in) <= 0:
+                    logger.debug("Google token has expired")
+                    return None
+
+                # Extract scopes from token info
+                scope_string = token_info.get("scope", "")
+                token_scopes = [
+                    scope.strip() for scope in scope_string.split(" ") if scope.strip()
+                ]
+
+                # 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
+
+                # Get additional user info if we have the right scopes
+                user_data = {}
+                if "openid" in token_scopes or "profile" in token_scopes:
+                    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 info: %s", e)
+
+                # Calculate expiration time
+                expires_at = None
+                if expires_in:
+                    expires_at = int(time.time() + int(expires_in))
+
+                # Create AccessToken with Google user info
+                access_token = AccessToken(
+                    token=token,
+                    client_id=token_info.get(
+                        "audience", "unknown"
+                    ),  # Use audience as client_id
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": user_data.get("id")
+                        or token_info.get("user_id", "unknown"),
+                        "email": user_data.get("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,
+                        "google_token_info": token_info,
+                    },
+                )
+                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,
+        base_url: AnyHttpUrl | str,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        extra_authorize_params: dict[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """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...")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            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
+            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.
+                SECURITY WARNING: Only disable 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.
+        """
+        # 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"]
+        )
+
+        # Create Google token verifier
+        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,
+            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,
+            extra_authorize_params=extra_authorize_params_final,
+        )
+
+        logger.debug(
+            "Initialized Google OAuth provider for client %s with scopes: %s",
+            client_id,
+            required_scopes_final,
+        )
diff --git a/src/fastmcp/server/auth/providers/in_memory.py b/src/fastmcp/server/auth/providers/in_memory.py
new file mode 100644
index 000000000..de1e786b1
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/in_memory.py
@@ -0,0 +1,364 @@
+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,
+        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",
+            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]
+        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]
+        """
+        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/src/fastmcp/server/auth/providers/introspection.py b/src/fastmcp/server/auth/providers/introspection.py
new file mode 100644
index 000000000..09e20abfd
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/introspection.py
@@ -0,0 +1,404 @@
+"""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 hashlib
+import time
+from dataclasses import dataclass
+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
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class _IntrospectionCacheEntry:
+    """Cached introspection result with expiration."""
+
+    result: AccessToken
+    expires_at: float
+
+
+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"]
+        )
+        ```
+    """
+
+    # Default cache settings
+    DEFAULT_MAX_CACHE_SIZE = 10000
+
+    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__)
+
+        # Cache configuration (None or 0 = disabled)
+        self._cache_ttl = cache_ttl_seconds or 0
+        self._max_cache_size = (
+            max_cache_size
+            if max_cache_size is not None
+            else self.DEFAULT_MAX_CACHE_SIZE
+        )
+        self._cache: dict[str, _IntrospectionCacheEntry] = {}
+        self._last_cleanup = time.monotonic()
+        self._cleanup_interval = 60  # Cleanup every 60 seconds
+
+    def _hash_token(self, token: str) -> str:
+        """Hash token for use as cache key.
+
+        Using SHA-256 for memory efficiency (fixed 64-char hex digest
+        regardless of token length).
+        """
+        return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+    def _cleanup_expired_cache(self) -> None:
+        """Remove expired entries from cache."""
+        now = time.time()
+        expired = [key for key, entry in self._cache.items() if entry.expires_at < now]
+        for key in expired:
+            del self._cache[key]
+        if expired:
+            self.logger.debug("Cleaned up %d expired cache entries", len(expired))
+
+    def _maybe_cleanup(self) -> None:
+        """Periodically cleanup expired entries to prevent unbounded growth."""
+        now = time.monotonic()
+        if now - self._last_cleanup > self._cleanup_interval:
+            self._cleanup_expired_cache()
+            self._last_cleanup = now
+
+    def _get_cached(self, token: str) -> tuple[bool, AccessToken | None]:
+        """Get cached introspection result.
+
+        Returns:
+            Tuple of (is_cached, result):
+            - (True, AccessToken) if cached valid token
+            - (False, None) if not in cache or expired
+        """
+        if self._cache_ttl <= 0 or self._max_cache_size <= 0:
+            return (False, None)  # Caching disabled
+
+        cache_key = self._hash_token(token)
+        entry = self._cache.get(cache_key)
+
+        if entry is None:
+            return (False, None)  # Not in cache
+
+        if entry.expires_at < time.time():
+            del self._cache[cache_key]
+            return (False, None)  # Expired
+
+        # Return a copy to prevent mutations from affecting cached value
+        return (True, entry.result.model_copy(deep=True))
+
+    def _set_cached(self, token: str, result: AccessToken) -> None:
+        """Cache a valid introspection result with TTL.
+
+        Only successful validations are cached. Failures (inactive, expired,
+        missing scopes, errors) are never cached to avoid sticky false negatives.
+        """
+        if self._cache_ttl <= 0 or self._max_cache_size <= 0:
+            return  # Caching disabled
+
+        # Periodic cleanup
+        self._maybe_cleanup()
+
+        # Check cache size limit
+        if len(self._cache) >= self._max_cache_size:
+            self._cleanup_expired_cache()
+            # If still at limit after cleanup, evict oldest entry
+            if len(self._cache) >= self._max_cache_size:
+                oldest_key = next(iter(self._cache))
+                del self._cache[oldest_key]
+
+        cache_key = self._hash_token(token)
+
+        # Use token's expiration if available and sooner than TTL
+        expires_at = time.time() + self._cache_ttl
+        if result.expires_at:
+            expires_at = min(expires_at, float(result.expires_at))
+
+        # Store a deep copy to prevent mutations from affecting cached value
+        self._cache[cache_key] = _IntrospectionCacheEntry(
+            result=result.model_copy(deep=True),
+            expires_at=expires_at,
+        )
+
+    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._get_cached(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 else None,
+                    claims=introspection_data,  # Store full response for extensibility
+                )
+                self._set_cached(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/src/fastmcp/server/auth/providers/jwt.py b/src/fastmcp/server/auth/providers/jwt.py
new file mode 100644
index 000000000..45f4ac99e
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/jwt.py
@@ -0,0 +1,594 @@
+"""TokenVerifier implementations for FastMCP."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, cast
+
+import httpx
+from authlib.jose import JsonWebKey, JsonWebToken
+from authlib.jose.errors import JoseError
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+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__)
+
+
+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 = {
+            "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
+        jwt_lib = JsonWebToken(["RS256"])
+        token_bytes = jwt_lib.encode(
+            header, payload, self.private_key.get_secret_value()
+        )
+
+        return token_bytes.decode("utf-8")
+
+
+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.jwt = JsonWebToken([self.algorithm])
+        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")
+                jwk = JsonWebKey.import_key(key_data)
+                public_key = jwk.get_public_key()
+
+                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) 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
+            claims = self.jwt.decode(token, verification_key)
+
+            # Extract client ID early for logging
+            client_id = (
+                claims.get("client_id")
+                or claims.get("azp")
+                or claims.get("sub")
+                or "unknown"
+            )
+
+            # Validate expiration
+            exp = claims.get("exp")
+            if exp and exp < time.time():
+                self.logger.debug(
+                    "Token validation failed: expired token for client %s", client_id
+                )
+                self.logger.info("Bearer token rejected for client %s", 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.debug(
+                        "Token validation failed: issuer mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
+                    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.debug(
+                        "Token validation failed: audience mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
+                    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.debug(
+                        "Token missing required scopes. Has: %s, Required: %s",
+                        token_scopes,
+                        required_scopes,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
+                    return None
+
+            return AccessToken(
+                token=token,
+                client_id=str(client_id),
+                scopes=scopes,
+                expires_at=int(exp) if exp 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/src/fastmcp/server/auth/providers/oci.py b/src/fastmcp/server/auth/providers/oci.py
new file mode 100644
index 000000000..29527f07a
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/oci.py
@@ -0,0 +1,172 @@
+"""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 key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl
+
+from fastmcp.server.auth.oidc_proxy import 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,
+        base_url: AnyHttpUrl | str,
+        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 = True,
+        consent_csp_policy: str | None = None,
+    ) -> 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
+            base_url: Public URL where OIDC endpoints will be accessible (includes any mount path)
+            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.
+        """
+        # 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,
+            base_url=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,
+        )
+
+        logger.debug(
+            "Initialized OCI OAuth provider for client %s with scopes: %s",
+            client_id,
+            oci_required_scopes,
+        )
diff --git a/src/fastmcp/server/auth/providers/propelauth.py b/src/fastmcp/server/auth/providers/propelauth.py
new file mode 100644
index 000000000..82e55e172
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/providers/scalekit.py b/src/fastmcp/server/auth/providers/scalekit.py
new file mode 100644
index 000000000..ffcacc9c5
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/providers/supabase.py b/src/fastmcp/server/auth/providers/supabase.py
new file mode 100644
index 000000000..527d701ee
--- /dev/null
+++ b/src/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/src/fastmcp/server/auth/providers/workos.py b/src/fastmcp/server/auth/providers/workos.py
new file mode 100644
index 000000000..204beeb48
--- /dev/null
+++ b/src/fastmcp/server/auth/providers/workos.py
@@ -0,0 +1,388 @@
+"""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
+
+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,
+        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 = True,
+        consent_csp_policy: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ):
+        """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)
+            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)
+            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.
+                SECURITY WARNING: Only disable 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.
+        """
+        # 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 []
+        )
+
+        # 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,
+            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,
+        )
+
+        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
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+        # Create AuthKit metadata provider (JWT verifier created automatically)
+        workos_auth = AuthKitProvider(
+            authkit_domain="https://your-workos-domain.authkit.app",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=workos_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        authkit_domain: AnyHttpUrl | str,
+        base_url: AnyHttpUrl | str,
+        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 AuthKit metadata provider.
+
+        Args:
+            authkit_domain: Your AuthKit domain (e.g., "https://your-app.authkit.app")
+            base_url: Public URL of this FastMCP server
+            client_id: Your WorkOS project client ID (e.g., "client_01ABC..."). Used to
+                validate the JWT audience claim. Found in your WorkOS Dashboard under
+                API Keys. This is the project-level client ID, not individual MCP client IDs.
+            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 None, creates JWT verifier for AuthKit
+        """
+        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
+        )
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            logger.warning(
+                "AuthKitProvider cannot validate token audience for the specific resource "
+                "because AuthKit does not support RFC 8707 resource indicators. "
+                "This may leave the server vulnerable to cross-server token replay. "
+                "Consider using WorkOSProvider (OAuth proxy) for audience-bound tokens."
+            )
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.authkit_domain}/oauth2/jwks",
+                issuer=self.authkit_domain,
+                algorithm="RS256",
+                audience=client_id,
+                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,
+            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 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/src/fastmcp/server/auth/redirect_validation.py b/src/fastmcp/server/auth/redirect_validation.py
new file mode 100644
index 000000000..4d011416f
--- /dev/null
+++ b/src/fastmcp/server/auth/redirect_validation.py
@@ -0,0 +1,212 @@
+"""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 urlparse
+
+from pydantic import AnyUrl
+
+
+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 _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 _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 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
+
+    # 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
+
+    # 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
+
+    # Port must match (with * wildcard support)
+    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, all URIs are allowed (for DCR compatibility).
+                         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 no patterns specified, allow all for DCR compatibility
+    # (clients need to dynamically register with their own redirect URIs)
+    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/src/fastmcp/server/auth/ssrf.py b/src/fastmcp/server/auth/ssrf.py
new file mode 100644
index 000000000..39c28e959
--- /dev/null
+++ b/src/fastmcp/server/auth/ssrf.py
@@ -0,0 +1,356 @@
+"""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__)
+
+
+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 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
+
+    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 not ip.is_global:
+        return False
+
+    # Block multicast (not caught by is_global for some ranges)
+    if ip.is_multicast:
+        return False
+
+    # IPv6-specific checks for embedded IPv4 addresses
+    if isinstance(ip, ipaddress.IPv6Address):
+        if ip.ipv4_mapped:
+            return is_ip_allowed(str(ip.ipv4_mapped))
+        if ip.sixtofour:
+            return is_ip_allowed(str(ip.sixtofour))
+        if ip.teredo:
+            server, client = ip.teredo
+            return is_ip_allowed(str(server)) and is_ip_allowed(str(client))
+
+    return True
+
+
+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
+    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/src/fastmcp/server/context.py b/src/fastmcp/server/context.py
new file mode 100644
index 000000000..d7b23a245
--- /dev/null
+++ b/src/fastmcp/server/context.py
@@ -0,0 +1,1384 @@
+from __future__ import annotations
+
+import logging
+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, overload
+
+import mcp.types
+from mcp import LoggingLevel, ServerSession
+from mcp.server.lowlevel.server import request_ctx
+from mcp.shared.context import RequestContext
+from mcp.types import (
+    GetPromptResult,
+    ModelPreferences,
+    Root,
+    SamplingMessage,
+)
+from mcp.types import Prompt as SDKPrompt
+from mcp.types import Resource as SDKResource
+from pydantic.networks import AnyUrl
+from starlette.requests import Request
+from typing_extensions import TypeVar
+from uncalled_for import SharedContext
+
+from fastmcp.resources.resource import ResourceResult
+from fastmcp.server.elicitation import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    DeclinedElicitation,
+    handle_elicit_accept,
+    parse_elicit_response_type,
+)
+from fastmcp.server.low_level import MiddlewareServerSession
+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
+
+_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))
+
+        # Set docket/worker from server instance for this request's context.
+        # This ensures ContextVars work even in ASGI environments (Lambda, FastAPI mount)
+        # where lifespan ContextVars don't propagate to request handlers.
+        server = self.fastmcp
+        if is_docket_available():
+            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)
+        else:
+            # 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,
+        )
+
+        # Mirror __aenter__: clean up docket/worker tokens or SharedContext
+        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) -> RequestContext[ServerSession, Any, Request] | None:
+        """Access to the underlying request context.
+
+        Returns None when the MCP session has not been established yet.
+        Returns the full RequestContext 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)
+        ```
+        """
+        try:
+            return request_ctx.get()
+        except LookupError:
+            return None
+
+    @property
+    def lifespan_context(self) -> dict[str, Any]:
+        """Access the server's lifespan context.
+
+        Returns the context dict yielded by the server's lifespan function.
+        Returns an empty dict if no lifespan was configured or if the MCP
+        session is not yet established.
+
+        In background tasks (Docket workers), where request_context is not
+        available, falls back to reading from the FastMCP server's lifespan
+        result directly.
+
+        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"
+        ```
+        """
+        rc = self.request_context
+        if rc is None:
+            # In background tasks, request_context is not available.
+            # Fall back to the server's lifespan result directly (#3095).
+            result = self.fastmcp._lifespan_result
+            if result is not None:
+                return result
+            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
+        """
+
+        progress_token = (
+            self.request_context.meta.progressToken
+            if self.request_context and self.request_context.meta
+            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]
+
+            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,
+        request_factory: Callable[[str | None], Any],
+        call_method: Callable[[Any], Any],
+        extract_items: Callable[[Any], list[Any]],
+    ) -> list[Any]:
+        """Generic pagination helper for list operations.
+
+        Args:
+            request_factory: Function that creates a request from a cursor
+            call_method: Async method to call with the request
+            extract_items: Function to extract items from the result
+
+        Returns:
+            List of all items across all pages
+        """
+        all_items: list[Any] = []
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+        while True:
+            request = request_factory(cursor)
+            result = await call_method(request)
+            all_items.extend(extract_items(result))
+            if not result.nextCursor:
+                break
+            if result.nextCursor in seen_cursors:
+                break
+            seen_cursors.add(result.nextCursor)
+            cursor = result.nextCursor
+        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(
+            request_factory=lambda cursor: mcp.types.ListResourcesRequest(
+                params=mcp.types.PaginatedRequestParams(cursor=cursor)
+                if cursor
+                else None
+            ),
+            call_method=self.fastmcp._list_resources_mcp,
+            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(
+            request_factory=lambda cursor: mcp.types.ListPromptsRequest(
+                params=mcp.types.PaginatedRequestParams(cursor=cursor)
+                if cursor
+                else None
+            ),
+            call_method=self.fastmcp._list_prompts_mcp,
+            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
+
+        await _log_to_server_and_client(
+            data=data,
+            session=self.session,
+            level=level or "info",
+            logger_name=logger_name,
+            related_request_id=related_request_id,
+        )
+
+    @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.
+
+        Returns ``False`` when no session is available (e.g., outside a
+        request context) or when the client did not advertise the extension.
+
+        Example::
+
+            from fastmcp.server.apps 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"
+        """
+        rc = self.request_context
+        if rc is None:
+            return False
+        session = rc.session
+        if not isinstance(session, MiddlewareServerSession):
+            return False
+        return session.client_supports_extension(extension_id)
+
+    @property
+    def client_id(self) -> str | None:
+        """Get the client ID if available."""
+        return (
+            getattr(self.request_context.meta, "client_id", None)
+            if self.request_context and self.request_context.meta
+            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."
+            )
+
+        # Check for cached session ID
+        session_id = getattr(session, "_fastmcp_state_prefix", None)
+        if session_id is not None:
+            return session_id
+
+        # For HTTP, try to get from header
+        if 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 session for consistency
+        session._fastmcp_state_prefix = session_id  # type: ignore[attr-defined]
+        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."""
+        result = await self.session.list_roots()
+        return result.roots
+
+    async def send_notification(
+        self, notification: mcp.types.ServerNotificationType
+    ) -> None:
+        """Send a notification to the client immediately.
+
+        Args:
+            notification: An MCP notification instance (e.g., ToolListChangedNotification())
+        """
+        await self.session.send_notification(mcp.types.ServerNotification(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()
+
+    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
+        """
+        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,
+        )
+
+    @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
+
+        Note:
+            Background task support for sampling is planned for a future release.
+            Currently, sampling in background tasks requires using the low-level
+            session.create_message() API directly.
+        """
+        # TODO: Add background task support similar to elicit() when is_background_task
+        return await sample_impl(
+            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,
+        )
+
+    @overload
+    async def elicit(
+        self,
+        message: str,
+        response_type: 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],
+    ) -> 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],
+    ) -> 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]],
+    ) -> 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]],
+    ) -> (
+        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]]],
+    ) -> (
+        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,
+    ) -> (
+        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.
+
+        If the response_type is None, the generated schema will be that of an
+        empty object in order to comply with the MCP protocol requirements.
+        Clients must send an empty object ("{}")in response.
+
+        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.
+
+        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.
+        """
+        config = parse_elicit_response_type(response_type)
+
+        if self.is_background_task:
+            # Background task mode: use task-aware elicitation
+            result = await self._elicit_for_task(
+                message=message,
+                schema=config.schema,
+            )
+        else:
+            # Standard request mode: use session.elicit directly
+            result = await self.session.elicit(
+                message=message,
+                requestedSchema=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]
+            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)
+
+
+async def _log_to_server_and_client(
+    data: LogData,
+    session: ServerSession,
+    level: LoggingLevel,
+    logger_name: str | None = None,
+    related_request_id: str | None = None,
+) -> None:
+    """Log a message to the server and client."""
+
+    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,
+    )
+
+    await session.send_log_message(
+        level=level,
+        data=data,
+        logger=logger_name,
+        related_request_id=related_request_id,
+    )
diff --git a/src/fastmcp/server/dependencies.py b/src/fastmcp/server/dependencies.py
new file mode 100644
index 000000000..94e244ea7
--- /dev/null
+++ b/src/fastmcp/server/dependencies.py
@@ -0,0 +1,1458 @@
+"""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 contextlib
+import inspect
+import logging
+import weakref
+from collections.abc import AsyncGenerator, Callable
+from contextlib import AsyncExitStack, asynccontextmanager
+from contextvars import ContextVar, Token
+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.lowlevel.server import request_ctx
+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
+
+_logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.worker import Worker
+    from mcp.server.session import ServerSession
+
+    from fastmcp.server.context import Context
+    from fastmcp.server.server import FastMCP
+
+
+__all__ = [
+    "AccessToken",
+    "CurrentAccessToken",
+    "CurrentContext",
+    "CurrentDocket",
+    "CurrentFastMCP",
+    "CurrentHeaders",
+    "CurrentRequest",
+    "CurrentWorker",
+    "Progress",
+    "TaskContextInfo",
+    "TokenClaim",
+    "get_access_token",
+    "get_context",
+    "get_http_headers",
+    "get_http_request",
+    "get_server",
+    "get_task_context",
+    "get_task_session",
+    "is_docket_available",
+    "register_task_session",
+    "require_docket",
+    "resolve_dependencies",
+    "transform_context_annotations",
+    "without_injected_parameters",
+]
+
+
+# --- TaskContextInfo and get_task_context ---
+
+
+@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)."""
+
+    session_id: str
+    """The session ID that submitted this task."""
+
+
+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 session_id, or None if not in a task.
+    """
+    if not is_docket_available():
+        return None
+
+    from docket.dependencies import current_execution
+
+    try:
+        execution = current_execution.get()
+        # Parse the task key: {session_id}:{task_id}:{task_type}:{component}
+        from fastmcp.server.tasks.keys import parse_task_key
+
+        key_parts = parse_task_key(execution.key)
+        return TaskContextInfo(
+            task_id=key_parts["client_task_id"],
+            session_id=key_parts["session_id"],
+        )
+    except LookupError:
+        # Not in worker context
+        return None
+    except (ValueError, KeyError):
+        # Invalid task key format
+        return None
+
+
+# --- Session registry for background task Context ---
+
+
+_task_sessions: dict[str, weakref.ref[ServerSession]] = {}
+
+
+def register_task_session(session_id: str, session: ServerSession) -> None:
+    """Register a session for Context access in background tasks.
+
+    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.
+
+    Args:
+        session_id: The session identifier
+        session: The ServerSession instance
+    """
+    _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.
+
+    Args:
+        session_id: The session identifier
+
+    Returns:
+        The ServerSession if found and alive, None otherwise
+    """
+    ref = _task_sessions.get(session_id)
+    if ref is None:
+        return None
+    session = ref()
+    if session is None:
+        # Session was garbage collected, clean up entry
+        _task_sessions.pop(session_id, None)
+    return session
+
+
+# --- ContextVars ---
+
+_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)
+_task_access_token: ContextVar[AccessToken | None] = ContextVar(
+    "task_access_token", default=None
+)
+
+
+# --- Docket availability check ---
+
+_DOCKET_AVAILABLE: bool | None = None
+
+
+def is_docket_available() -> bool:
+    """Check if pydocket is installed."""
+    global _DOCKET_AVAILABLE
+    if _DOCKET_AVAILABLE is None:
+        try:
+            import docket  # noqa: F401
+
+            _DOCKET_AVAILABLE = True
+        except 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 not is_docket_available():
+        raise ImportError(
+            f"FastMCP background tasks require the `tasks` extra. "
+            f"Install with: pip install 'fastmcp[tasks]'. "
+            f"(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]
+
+
+# --- 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]
+    else:
+        new_sig = sig.replace(parameters=new_params)
+        fn.__signature__ = new_sig  # type: ignore[attr-defined]
+
+    # 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.
+
+    Returns:
+        The active FastMCP server
+
+    Raises:
+        RuntimeError: If no server in context
+    """
+    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.
+    """
+    # Try MCP SDK's request_ctx first (set during normal MCP request handling)
+    request = None
+    with contextlib.suppress(LookupError):
+        request = request_ctx.get().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()
+
+    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}
+        # (just in case)
+        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 HTTP request nor SDK context var are available.
+    # The token was snapshotted in Redis at submit_to_docket() time and restored
+    # into this ContextVar by _CurrentContext.__aenter__().
+    if access_token is None:
+        task_token = _task_access_token.get()
+        if task_token is not None:
+            # Check expiration: if expires_at is set and past, treat as expired
+            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]) -> 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
+
+    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)
+            else:
+                # 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
+
+    # 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]
+    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.
+
+
+async def _restore_task_access_token(
+    session_id: str, task_id: str
+) -> Token[AccessToken | None] | None:
+    """Restore the access token snapshot from Redis into a ContextVar.
+
+    Called when setting up context in a Docket worker. The token was stored at
+    submit_to_docket() time. The token is restored regardless of expiration;
+    get_access_token() checks expiry when reading from the ContextVar.
+
+    Returns:
+        The ContextVar token for resetting, or None if nothing was restored.
+    """
+    docket = _current_docket.get()
+    if docket is None:
+        return None
+
+    token_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:access_token")
+    try:
+        async with docket.redis() as redis:
+            token_data = await redis.get(token_key)
+        if token_data is not None:
+            restored = AccessToken.model_validate_json(token_data)
+            return _task_access_token.set(restored)
+    except Exception:
+        _logger.warning(
+            "Failed to restore access token for task %s:%s",
+            session_id,
+            task_id,
+            exc_info=True,
+        )
+    return None
+
+
+async def _restore_task_origin_request_id(session_id: str, task_id: str) -> str | None:
+    """Restore the origin request ID snapshot for a background task.
+
+    Returns None if no request ID was captured at submission time.
+    """
+    docket = _current_docket.get()
+    if docket is None:
+        return None
+
+    request_id_key = docket.key(
+        f"fastmcp:task:{session_id}:{task_id}:origin_request_id"
+    )
+    try:
+        async with docket.redis() as redis:
+            request_id_data = await redis.get(request_id_key)
+        if request_id_data is None:
+            return None
+        if isinstance(request_id_data, bytes):
+            return request_id_data.decode()
+        return str(request_id_data)
+    except Exception:
+        _logger.warning(
+            "Failed to restore origin request ID for task %s:%s",
+            session_id,
+            task_id,
+            exc_info=True,
+        )
+        return None
+
+
+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 restores the access token snapshot from Redis.
+    """
+
+    _context: Context | None = None
+    _access_token_cv_token: Token[AccessToken | None] | None = None
+
+    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:
+            # Get session from registry (registered when task was submitted)
+            session = get_task_session(task_info.session_id)
+            # Get server from ContextVar
+            server = get_server()
+            origin_request_id = await _restore_task_origin_request_id(
+                task_info.session_id, task_info.task_id
+            )
+            # Create task-aware Context
+            self._context = Context(
+                fastmcp=server,
+                session=session,
+                task_id=task_info.task_id,
+                origin_request_id=origin_request_id,
+            )
+            # Enter the context to set up ContextVars
+            await self._context.__aenter__()
+
+            # Restore access token snapshot from Redis (#3095)
+            self._access_token_cv_token = await _restore_task_access_token(
+                task_info.session_id, task_info.task_id
+            )
+
+            return self._context
+
+        # Neither foreground nor background context available
+        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:
+        # Clean up access token ContextVar
+        if self._access_token_cv_token is not None:
+            _task_access_token.reset(self._access_token_cv_token)
+            self._access_token_cv_token = None
+        # Clean up if we created a context for background task
+        if self._context is not None:
+            await self._context.__aexit__(exc_type, exc_value, traceback)
+            self._context = None
+
+
+class _OptionalCurrentContext(Dependency["Context | None"]):
+    """Context dependency that degrades to None when no context is active.
+
+    This is implemented as a wrapper (composition), not a subclass of
+    `_CurrentContext`, to avoid overriding `__aenter__` with an incompatible
+    return type.
+    """
+
+    _inner: _CurrentContext | None = None
+
+    async def __aenter__(self) -> Context | None:
+        inner = _CurrentContext()
+        try:
+            context = await inner.__aenter__()
+        except RuntimeError as exc:
+            if "No active context found" in str(exc):
+                return None
+            raise
+        self._inner = inner
+        return context
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._inner is None:
+            return
+        await self._inner.__aexit__(exc_type, exc_value, traceback)
+        self._inner = None
+
+
+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()")
+        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()")
+        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:
+        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
+
+    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"]):
+    """FastMCP Progress dependency that works in both server and worker contexts.
+
+    Handles three execution modes:
+    - In Docket worker: Uses the execution's progress (observable via Redis)
+    - In FastMCP server with Docket: Falls back to in-memory progress
+    - In FastMCP server without Docket: Uses in-memory progress
+
+    This allows tools to use Progress() regardless of whether they're called
+    immediately or as background tasks, and regardless of whether pydocket
+    is installed.
+    """
+
+    _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.")
+
+        if is_docket_available():
+            from docket.dependencies import Progress as DocketProgress
+
+            try:
+                docket_progress = DocketProgress()
+                self._impl = await docket_progress.__aenter__()
+                return self
+            except LookupError:
+                pass
+
+        self._impl = InMemoryProgress()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self._impl = None
+
+    @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."""
+
+    _access_token_cv_token: Token[AccessToken | None] | None = None
+
+    async def __aenter__(self) -> AccessToken:
+        token = get_access_token()
+
+        # If no token found and we're in a Docket worker, try restoring from
+        # Redis. This handles the case where ctx: Context is not in the
+        # function signature, so _CurrentContext never ran the restoration.
+        if token is None:
+            task_info = get_task_context()
+            if task_info is not None:
+                self._access_token_cv_token = await _restore_task_access_token(
+                    task_info.session_id, task_info.task_id
+                )
+                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:
+        if self._access_token_cv_token is not None:
+            _task_access_token.reset(self._access_token_cv_token)
+            self._access_token_cv_token = None
+
+
+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/src/fastmcp/server/elicitation.py b/src/fastmcp/server/elicitation.py
new file mode 100644
index 000000000..6f8a050d4
--- /dev/null
+++ b/src/fastmcp/server/elicitation.py
@@ -0,0 +1,464 @@
+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]
+        """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]
+            # 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) -> 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
+    """
+    if response_type is None:
+        return ElicitConfig(
+            schema={"type": "object", "properties": {}},
+            response_type=None,
+            is_raw=False,
+        )
+
+    if isinstance(response_type, dict):
+        return _parse_dict_syntax(response_type)
+
+    if isinstance(response_type, list):
+        return _parse_list_syntax(response_type)
+
+    if get_origin(response_type) is list:
+        return _parse_generic_list(response_type)
+
+    if _is_scalar_type(response_type):
+        return _parse_scalar_type(response_type)
+
+    # Other types (dataclass, BaseModel, etc.) - use directly
+    return ElicitConfig(
+        schema=get_elicitation_schema(response_type),
+        response_type=response_type,
+        is_raw=False,
+    )
+
+
+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]
+        wrapped = ScalarElicitationType[choice_literal]  # type: ignore[valid-type]
+        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/src/fastmcp/server/event_store.py b/src/fastmcp/server/event_store.py
new file mode 100644
index 000000000..9304a931e
--- /dev/null
+++ b/src/fastmcp/server/event_store.py
@@ -0,0 +1,177 @@
+"""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 fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import FastMCPBaseModel
+
+logger = get_logger(__name__)
+
+
+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 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") 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 = JSONRPCMessage.model_validate(event.message)
+                await send_callback(EventMessage(msg, event.event_id))
+
+        return stream_id
diff --git a/src/fastmcp/server/http.py b/src/fastmcp/server/http.py
new file mode 100644
index 000000000..c29c39ec8
--- /dev/null
+++ b/src/fastmcp/server/http.py
@@ -0,0 +1,383 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Generator
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+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 starlette.applications import Starlette
+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 Lifespan, Receive, Scope, Send
+
+from fastmcp.server.auth import AuthProvider
+from fastmcp.server.auth.middleware import RequireAuthMiddleware
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+class StreamableHTTPASGIApp:
+    """ASGI application wrapper for Streamable HTTP server transport."""
+
+    def __init__(self, session_manager):
+        self.session_manager = session_manager
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            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
+
+
+_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
+    # TODO(ty): remove type ignore when ty supports Starlette Middleware typing
+    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,
+) -> 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
+
+    Returns:
+        A Starlette application with StreamableHTTP support
+    """
+    server_routes: list[BaseRoute] = []
+    server_middleware: list[Middleware] = []
+
+    # Create session manager using the provided event store
+    session_manager = StreamableHTTPSessionManager(
+        app=server._mcp_server,
+        event_store=event_store,
+        retry_interval=retry_interval,
+        json_response=json_response,
+        stateless=stateless_http,
+    )
+
+    # Create the ASGI app wrapper
+    streamable_http_app = StreamableHTTPASGIApp(session_manager)
+
+    # 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 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]:
+        async with server._lifespan_manager(), session_manager.run():
+            yield
+
+    # 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/src/fastmcp/server/lifespan.py b/src/fastmcp/server/lifespan.py
new file mode 100644
index 000000000..c3cd91695
--- /dev/null
+++ b/src/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/src/fastmcp/server/low_level.py b/src/fastmcp/server/low_level.py
new file mode 100644
index 000000000..420424fc1
--- /dev/null
+++ b/src/fastmcp/server/low_level.py
@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+import weakref
+from collections.abc import Awaitable, Callable
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any
+
+import anyio
+import mcp.types
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import McpError
+from mcp.server.lowlevel.server import (
+    LifespanResultT,
+    NotificationOptions,
+    RequestT,
+)
+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.message import SessionMessage
+from mcp.shared.session import RequestResponder
+from pydantic import AnyUrl
+
+from fastmcp.server.apps import UI_EXTENSION_ID
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+logger = get_logger(__name__)
+
+
+class MiddlewareServerSession(ServerSession):
+    """ServerSession that routes initialization requests through FastMCP middleware."""
+
+    def __init__(self, fastmcp: FastMCP, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._fastmcp_ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+        # Task group for subscription tasks (set during session run)
+        self._subscription_task_group: anyio.TaskGroup | None = None  # type: ignore[valid-type]
+
+    @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 client_supports_extension(self, extension_id: str) -> bool:
+        """Check if the connected client supports a given MCP extension.
+
+        Inspects the ``extensions`` extra field on ``ClientCapabilities``
+        sent by the client during initialization.
+        """
+        client_params = self._client_params
+        if client_params is None:
+            return False
+        caps = client_params.capabilities
+        if caps is None:
+            return False
+        # ClientCapabilities uses extra="allow" — extensions is an extra field
+        extras = caps.model_extra or {}
+        extensions: dict[str, Any] | None = extras.get("extensions")
+        if not extensions:
+            return False
+        return extension_id in extensions
+
+    async def _received_request(
+        self,
+        responder: RequestResponder[mcp.types.ClientRequest, mcp.types.ServerResult],
+    ):
+        """
+        Override the _received_request method to route special requests
+        through FastMCP middleware.
+
+        Handles initialization requests and SEP-1686 task methods.
+        """
+        import fastmcp.server.context
+        from fastmcp.server.middleware.middleware import MiddlewareContext
+
+        if isinstance(responder.request.root, mcp.types.InitializeRequest):
+            # The MCP SDK's ServerSession._received_request() handles the
+            # initialize request internally by calling responder.respond()
+            # to send the InitializeResult directly to the write stream, then
+            # returning None. This bypasses the middleware return path entirely,
+            # so middleware would only see the request, never the response.
+            #
+            # To expose the response to middleware (e.g., for logging server
+            # capabilities), we wrap responder.respond() to capture the
+            # InitializeResult before it's sent, then return it from
+            # call_original_handler so it flows back through the middleware chain.
+            captured_response: mcp.types.ServerResult | None = None
+            original_respond = responder.respond
+
+            async def capturing_respond(
+                response: mcp.types.ServerResult,
+            ) -> None:
+                nonlocal captured_response
+                captured_response = response
+                return await original_respond(response)
+
+            responder.respond = capturing_respond  # type: ignore[method-assign]
+
+            async def call_original_handler(
+                ctx: MiddlewareContext,
+            ) -> mcp.types.InitializeResult | None:
+                await super(MiddlewareServerSession, self)._received_request(responder)
+                if captured_response is not None and isinstance(
+                    captured_response.root, mcp.types.InitializeResult
+                ):
+                    return captured_response.root
+                return None
+
+            async with fastmcp.server.context.Context(
+                fastmcp=self.fastmcp, session=self
+            ) as fastmcp_ctx:
+                # Create the middleware context.
+                mw_context = MiddlewareContext(
+                    message=responder.request.root,
+                    source="client",
+                    type="request",
+                    method="initialize",
+                    fastmcp_context=fastmcp_ctx,
+                )
+
+                try:
+                    return await self.fastmcp._run_middleware(
+                        mw_context, call_original_handler
+                    )
+                except McpError as e:
+                    # McpError can be thrown from middleware in `on_initialize`
+                    # send the error to responder.
+                    if not responder._completed:
+                        with responder:
+                            await responder.respond(e.error)
+                    else:
+                        # Don't re-raise: prevents responding to initialize request twice
+                        logger.warning(
+                            "Received McpError but responder is already completed. "
+                            "Cannot send error response as response was already sent.",
+                            exc_info=e,
+                        )
+                    return None
+
+        # Fall through to default handling (task methods now handled via registered handlers)
+        return await super()._received_request(responder)
+
+
+class LowLevelServer(_Server[LifespanResultT, RequestT]):
+    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
+        self.notification_options = NotificationOptions(
+            prompts_changed=True,
+            resources_changed=True,
+            tools_changed=True,
+        )
+
+    @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,
+        **kwargs: Any,
+    ) -> InitializationOptions:
+        # ensure we use the FastMCP notification options
+        if notification_options is None:
+            notification_options = self.notification_options
+        return super().create_initialization_options(
+            notification_options=notification_options,
+            experimental_capabilities=experimental_capabilities,
+            **kwargs,
+        )
+
+    def get_capabilities(
+        self,
+        notification_options: NotificationOptions,
+        experimental_capabilities: dict[str, dict[str, Any]],
+    ) -> mcp.types.ServerCapabilities:
+        """Override to set capabilities.tasks as a first-class field per SEP-1686.
+
+        This ensures task capabilities appear in capabilities.tasks instead of
+        capabilities.experimental.tasks, which is required by the MCP spec and
+        enables proper task detection by clients like VS Code Copilot 1.107+.
+        """
+        from fastmcp.server.tasks.capabilities import get_task_capabilities
+
+        # Get base capabilities from SDK (pass empty dict for experimental)
+        # since we'll set tasks as a first-class field instead
+        capabilities = super().get_capabilities(
+            notification_options,
+            experimental_capabilities or {},
+        )
+
+        # Set tasks as a first-class field (not experimental) per SEP-1686
+        capabilities.tasks = get_task_capabilities()
+
+        # Advertise MCP Apps extension support (io.modelcontextprotocol/ui)
+        # Uses the same extra-field pattern as tasks above — ServerCapabilities
+        # has extra="allow" so this survives serialization.
+        # Merge with any existing extensions to avoid clobbering other features.
+        existing_extensions: dict[str, Any] = (
+            getattr(capabilities, "extensions", None) or {}
+        )
+        capabilities.extensions = {**existing_extensions, UI_EXTENSION_ID: {}}
+
+        return capabilities
+
+    async def run(
+        self,
+        read_stream: MemoryObjectReceiveStream[SessionMessage | Exception],
+        write_stream: MemoryObjectSendStream[SessionMessage],
+        initialization_options: InitializationOptions,
+        raise_exceptions: bool = False,
+        stateless: bool = False,
+    ):
+        """
+        Overrides the run method to use the MiddlewareServerSession.
+        """
+        async with AsyncExitStack() as stack:
+            lifespan_context = await stack.enter_async_context(self.lifespan(self))
+            session = await stack.enter_async_context(
+                MiddlewareServerSession(
+                    self.fastmcp,
+                    read_stream,
+                    write_stream,
+                    initialization_options,
+                    stateless=stateless,
+                )
+            )
+
+            async with anyio.create_task_group() as tg:
+                # Store task group on session for subscription tasks (SEP-1686)
+                session._subscription_task_group = tg
+
+                async for message in session.incoming_messages:
+                    tg.start_soon(
+                        self._handle_message,
+                        message,
+                        session,
+                        lifespan_context,
+                        raise_exceptions,
+                    )
+
+    def read_resource(
+        self,
+    ) -> Callable[
+        [
+            Callable[
+                [AnyUrl],
+                Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+            ]
+        ],
+        Callable[
+            [AnyUrl],
+            Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+        ],
+    ]:
+        """
+        Decorator for registering a read_resource handler with CreateTaskResult support.
+
+        The MCP SDK's read_resource decorator does not support returning CreateTaskResult
+        for background task execution. This decorator wraps the result in ServerResult.
+
+        This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+        for resources.
+        """
+
+        def decorator(
+            func: Callable[
+                [AnyUrl],
+                Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+            ],
+        ) -> Callable[
+            [AnyUrl],
+            Awaitable[mcp.types.ReadResourceResult | mcp.types.CreateTaskResult],
+        ]:
+            async def handler(
+                req: mcp.types.ReadResourceRequest,
+            ) -> mcp.types.ServerResult:
+                result = await func(req.params.uri)
+                return mcp.types.ServerResult(result)
+
+            self.request_handlers[mcp.types.ReadResourceRequest] = handler
+            return func
+
+        return decorator
+
+    def get_prompt(
+        self,
+    ) -> Callable[
+        [
+            Callable[
+                [str, dict[str, Any] | None],
+                Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+            ]
+        ],
+        Callable[
+            [str, dict[str, Any] | None],
+            Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+        ],
+    ]:
+        """
+        Decorator for registering a get_prompt handler with CreateTaskResult support.
+
+        The MCP SDK's get_prompt decorator does not support returning CreateTaskResult
+        for background task execution. This decorator wraps the result in ServerResult.
+
+        This decorator can be removed once the MCP SDK adds native CreateTaskResult support
+        for prompts.
+        """
+
+        def decorator(
+            func: Callable[
+                [str, dict[str, Any] | None],
+                Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+            ],
+        ) -> Callable[
+            [str, dict[str, Any] | None],
+            Awaitable[mcp.types.GetPromptResult | mcp.types.CreateTaskResult],
+        ]:
+            async def handler(
+                req: mcp.types.GetPromptRequest,
+            ) -> mcp.types.ServerResult:
+                result = await func(req.params.name, req.params.arguments)
+                return mcp.types.ServerResult(result)
+
+            self.request_handlers[mcp.types.GetPromptRequest] = handler
+            return func
+
+        return decorator
diff --git a/src/fastmcp/server/middleware/__init__.py b/src/fastmcp/server/middleware/__init__.py
new file mode 100644
index 000000000..8df6962bd
--- /dev/null
+++ b/src/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/src/fastmcp/server/middleware/authorization.py b/src/fastmcp/server/middleware/authorization.py
new file mode 100644
index 000000000..4d3914a18
--- /dev/null
+++ b/src/fastmcp/server/middleware/authorization.py
@@ -0,0 +1,321 @@
+"""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 Sequence
+
+import mcp.types as mt
+
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.prompts.prompt import Prompt, PromptResult
+from fastmcp.resources.resource 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.tool import Tool, ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+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 (component auth is checked in get_tool, raises if unauthorized)
+        tool = await fastmcp.fastmcp.get_tool(tool_name)
+        if tool is None:
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': tool not found"
+            )
+
+        # 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/template (component auth is checked in get_*, raises if unauthorized)
+        component = await fastmcp.fastmcp.get_resource(str(uri))
+        if component is None:
+            component = await fastmcp.fastmcp.get_resource_template(str(uri))
+        if component is None:
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': resource not found"
+            )
+
+        # 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 (component auth is checked in get_prompt, raises if unauthorized)
+        prompt = await fastmcp.fastmcp.get_prompt(prompt_name)
+        if prompt is None:
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': prompt not found"
+            )
+
+        # 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/src/fastmcp/server/middleware/caching.py b/src/fastmcp/server/middleware/caching.py
new file mode 100644
index 000000000..acc50f026
--- /dev/null
+++ b/src/fastmcp/server/middleware/caching.py
@@ -0,0 +1,551 @@
+"""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.prompt import Message, Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceContent, ResourceResult
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool 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
+
+GLOBAL_KEY = "__global__"
+
+
+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
+
+    @classmethod
+    def wrap(cls, value: ToolResult) -> Self:
+        return cls(
+            content=value.content,
+            structured_content=value.structured_content,
+            meta=value.meta,
+        )
+
+    def unwrap(self) -> ToolResult:
+        return ToolResult(
+            content=self.content,
+            structured_content=self.structured_content,
+            meta=self.meta,
+        )
+
+
+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]
+                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 method name and arguments.
+    """
+
+    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)
+
+        if cached_value := await self._list_tools_cache.get(key=GLOBAL_KEY):
+            return cached_value
+
+        tools: Sequence[Tool] = await call_next(context=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=GLOBAL_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)
+
+        if cached_value := await self._list_resources_cache.get(key=GLOBAL_KEY):
+            return cached_value
+
+        resources: Sequence[Resource] = await call_next(context=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=GLOBAL_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)
+
+        if cached_value := await self._list_prompts_cache.get(key=GLOBAL_KEY):
+            return cached_value
+
+        prompts: Sequence[Prompt] = await call_next(context=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=GLOBAL_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=context)
+
+        cache_key: str = _make_call_tool_cache_key(msg=context.message)
+
+        if cached_value := await self._call_tool_cache.get(key=cache_key):
+            return cached_value.unwrap()
+
+        tool_result: ToolResult = await call_next(context=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=context)
+
+        cache_key: str = _make_read_resource_cache_key(msg=context.message)
+        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=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=context)
+
+        cache_key: str = _make_get_prompt_cache_key(msg=context.message)
+
+        if cached_value := await self._get_prompt_cache.get(key=cache_key):
+            return cached_value.unwrap()
+
+        value: PromptResult = await call_next(context=context)
+
+        await self._get_prompt_cache.put(
+            key=cache_key,
+            value=CachablePromptResult.wrap(value),
+            ttl=self._get_prompt_settings.get("ttl", ONE_HOUR_IN_SECONDS),
+        )
+
+        return value
+
+    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 _make_call_tool_cache_key(msg: mcp.types.CallToolRequestParams) -> str:
+    """Make a cache key for a tool call using a stable hash of name and arguments."""
+
+    return _hash_cache_key(f"{msg.name}:{_get_arguments_str(msg.arguments)}")
+
+
+def _make_read_resource_cache_key(msg: mcp.types.ReadResourceRequestParams) -> str:
+    """Make a cache key for a resource read using a stable hash of URI."""
+
+    return _hash_cache_key(str(msg.uri))
+
+
+def _make_get_prompt_cache_key(msg: mcp.types.GetPromptRequestParams) -> str:
+    """Make a cache key for a prompt get using a stable hash of name and arguments."""
+
+    return _hash_cache_key(f"{msg.name}:{_get_arguments_str(msg.arguments)}")
diff --git a/src/fastmcp/server/middleware/dereference.py b/src/fastmcp/server/middleware/dereference.py
new file mode 100644
index 000000000..89150d655
--- /dev/null
+++ b/src/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.tool 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/src/fastmcp/server/middleware/error_handling.py b/src/fastmcp/server/middleware/error_handling.py
new file mode 100644
index 000000000..5b235e804
--- /dev/null
+++ b/src/fastmcp/server/middleware/error_handling.py
@@ -0,0 +1,216 @@
+"""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 mcp.types import ErrorData
+
+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(
+                ErrorData(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(
+                    ErrorData(code=-32002, message=f"Resource not found: {error!s}")
+                )
+            return McpError(ErrorData(code=-32001, message=f"Not found: {error!s}"))
+        elif error_type is PermissionError:
+            return McpError(
+                ErrorData(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(
+                ErrorData(code=-32000, message=f"Request timeout: {error!s}")
+            )
+        else:
+            return McpError(
+                ErrorData(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."""
+        return isinstance(error, 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/src/fastmcp/server/middleware/logging.py b/src/fastmcp/server/middleware/logging.py
new file mode 100644
index 000000000..af2eff4b4
--- /dev/null
+++ b/src/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 = {
+            "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/src/fastmcp/server/middleware/middleware.py b/src/fastmcp/server/middleware/middleware.py
new file mode 100644
index 000000000..8022ee9dd
--- /dev/null
+++ b/src/fastmcp/server/middleware/middleware.py
@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    Protocol,
+    runtime_checkable,
+)
+
+import mcp.types as mt
+from typing_extensions import TypeVar
+
+from fastmcp.prompts.prompt import Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.tools.tool 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
+
+
+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 = partial(self.on_initialize, call_next=handler)
+            case "tools/call":
+                handler = partial(self.on_call_tool, call_next=handler)
+            case "resources/read":
+                handler = partial(self.on_read_resource, call_next=handler)
+            case "prompts/get":
+                handler = partial(self.on_get_prompt, call_next=handler)
+            case "tools/list":
+                handler = partial(self.on_list_tools, call_next=handler)
+            case "resources/list":
+                handler = partial(self.on_list_resources, call_next=handler)
+            case "resources/templates/list":
+                handler = partial(self.on_list_resource_templates, call_next=handler)
+            case "prompts/list":
+                handler = partial(self.on_list_prompts, call_next=handler)
+
+        match context.type:
+            case "request":
+                handler = partial(self.on_request, call_next=handler)
+            case "notification":
+                handler = partial(self.on_notification, call_next=handler)
+
+        handler = partial(self.on_message, call_next=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/src/fastmcp/server/middleware/ping.py b/src/fastmcp/server/middleware/ping.py
new file mode 100644
index 000000000..3ee61dac2
--- /dev/null
+++ b/src/fastmcp/server/middleware/ping.py
@@ -0,0 +1,70 @@
+"""Ping middleware for keeping client connections alive."""
+
+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 session."""
+        if (
+            context.fastmcp_context is None
+            or context.fastmcp_context.request_context is None
+        ):
+            return await call_next(context)
+
+        session = context.fastmcp_context.session
+        session_id = id(session)
+
+        async with self._lock:
+            if session_id not in self._active_sessions:
+                # _subscription_task_group is added by MiddlewareServerSession
+                tg = session._subscription_task_group  # type: ignore[attr-defined]
+                if tg is not None:
+                    self._active_sessions.add(session_id)
+                    tg.start_soon(self._ping_loop, session, session_id)
+
+        return await call_next(context)
+
+    async def _ping_loop(self, session: Any, session_id: int) -> None:
+        """Send periodic pings until session ends."""
+        try:
+            while True:
+                await anyio.sleep(self.interval_ms / 1000)
+                await session.send_ping()
+        finally:
+            self._active_sessions.discard(session_id)
diff --git a/src/fastmcp/server/middleware/rate_limiting.py b/src/fastmcp/server/middleware/rate_limiting.py
new file mode 100644
index 000000000..703fd393a
--- /dev/null
+++ b/src/fastmcp/server/middleware/rate_limiting.py
@@ -0,0 +1,231 @@
+"""Rate limiting middleware for protecting FastMCP servers from abuse."""
+
+import time
+from collections import defaultdict, deque
+from collections.abc import Callable
+from typing import Any
+
+import anyio
+from mcp import McpError
+from mcp.types import ErrorData
+
+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__(ErrorData(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] | 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. 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
+            )
+
+    def _get_client_identifier(self, context: MiddlewareContext) -> str:
+        """Get client identifier for rate limiting."""
+        if self.get_client_id:
+            return self.get_client_id(context)
+        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 = 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] | 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
+        """
+        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)
+        )
+
+    def _get_client_identifier(self, context: MiddlewareContext) -> str:
+        """Get client identifier for rate limiting."""
+        if self.get_client_id:
+            return self.get_client_id(context)
+        return "global"
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        """Apply sliding window rate limiting to requests."""
+        client_id = 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/src/fastmcp/server/middleware/response_limiting.py b/src/fastmcp/server/middleware/response_limiting.py
new file mode 100644
index 000000000..df83e81a0
--- /dev/null
+++ b/src/fastmcp/server/middleware/response_limiting.py
@@ -0,0 +1,125 @@
+"""Response limiting middleware for controlling tool response sizes."""
+
+from __future__ import annotations
+
+import logging
+
+import mcp.types as mt
+import pydantic_core
+from mcp.types import TextContent
+
+from fastmcp.tools.tool 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) -> 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
+                )
+
+        return ToolResult(content=[TextContent(type="text", text=truncated)])
+
+    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)
diff --git a/src/fastmcp/server/middleware/timing.py b/src/fastmcp/server/middleware/timing.py
new file mode 100644
index 000000000..178b3b250
--- /dev/null
+++ b/src/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/src/fastmcp/server/middleware/tool_injection.py b/src/fastmcp/server/middleware/tool_injection.py
new file mode 100644
index 000000000..e824eb8dc
--- /dev/null
+++ b/src/fastmcp/server/middleware/tool_injection.py
@@ -0,0 +1,140 @@
+"""A middleware for injecting tools into the MCP server context."""
+
+import warnings
+from collections.abc import Sequence
+from logging import Logger
+from typing import Annotated, Any
+
+import mcp.types
+from mcp.types import Prompt
+from pydantic import AnyUrl
+from typing_extensions import override
+
+import fastmcp
+from fastmcp.resources.resource import ResourceResult
+from fastmcp.server.context import Context
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool 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)
+
+
+async def list_prompts(context: Context) -> list[Prompt]:
+    """List prompts available on the server."""
+    return await context.list_prompts()
+
+
+list_prompts_tool = Tool.from_function(
+    fn=list_prompts,
+)
+
+
+async def get_prompt(
+    context: Context,
+    name: Annotated[str, "The name of the prompt to render."],
+    arguments: Annotated[
+        dict[str, Any] | None, "The arguments to pass to the prompt."
+    ] = None,
+) -> mcp.types.GetPromptResult:
+    """Render a prompt available on the server."""
+    return await context.get_prompt(name=name, arguments=arguments)
+
+
+get_prompt_tool = Tool.from_function(
+    fn=get_prompt,
+)
+
+
+class PromptToolMiddleware(ToolInjectionMiddleware):
+    """A middleware for injecting prompts as tools into the context.
+
+    .. deprecated::
+        Use ``fastmcp.server.transforms.PromptsAsTools`` instead.
+    """
+
+    def __init__(self) -> None:
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "PromptToolMiddleware is deprecated. Use the PromptsAsTools transform instead: "
+                "from fastmcp.server.transforms import PromptsAsTools",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        tools: list[Tool] = [list_prompts_tool, get_prompt_tool]
+        super().__init__(tools=tools)
+
+
+async def list_resources(context: Context) -> list[mcp.types.Resource]:
+    """List resources available on the server."""
+    return await context.list_resources()
+
+
+list_resources_tool = Tool.from_function(
+    fn=list_resources,
+)
+
+
+async def read_resource(
+    context: Context,
+    uri: Annotated[AnyUrl | str, "The URI of the resource to read."],
+) -> ResourceResult:
+    """Read a resource available on the server."""
+    return await context.read_resource(uri=uri)
+
+
+read_resource_tool = Tool.from_function(
+    fn=read_resource,
+)
+
+
+class ResourceToolMiddleware(ToolInjectionMiddleware):
+    """A middleware for injecting resources as tools into the context.
+
+    .. deprecated::
+        Use ``fastmcp.server.transforms.ResourcesAsTools`` instead.
+    """
+
+    def __init__(self) -> None:
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "ResourceToolMiddleware is deprecated. Use the ResourcesAsTools transform instead: "
+                "from fastmcp.server.transforms import ResourcesAsTools",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        tools: list[Tool] = [list_resources_tool, read_resource_tool]
+        super().__init__(tools=tools)
diff --git a/src/fastmcp/server/mixins/__init__.py b/src/fastmcp/server/mixins/__init__.py
new file mode 100644
index 000000000..3df6e8d36
--- /dev/null
+++ b/src/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/src/fastmcp/server/mixins/lifespan.py b/src/fastmcp/server/mixins/lifespan.py
new file mode 100644
index 000000000..0f2589272
--- /dev/null
+++ b/src/fastmcp/server/mixins/lifespan.py
@@ -0,0 +1,242 @@
+"""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 typing import TYPE_CHECKING, Any
+
+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__)
+
+
+class LifespanMixin:
+    """Mixin providing lifespan and Docket task infrastructure for FastMCP."""
+
+    @property
+    def docket(self: FastMCP) -> Docket | None:
+        """Get the Docket instance if Docket support is enabled.
+
+        Returns None if Docket is not enabled or server hasn't been started yet.
+        """
+        return self._docket
+
+    @asynccontextmanager
+    async def _docket_lifespan(self: FastMCP) -> AsyncIterator[None]:
+        """Manage Docket instance and Worker for background task execution.
+
+        Docket infrastructure is only initialized if:
+        1. pydocket is installed (fastmcp[tasks] extra)
+        2. There are task-enabled components (task_config.mode != 'forbidden')
+
+        This means users with pydocket installed but no task-enabled components
+        won't spin up Docket/Worker infrastructure.
+        """
+        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():
+                    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():
+                    yield
+                return
+
+            # Docket is available AND there are task-enabled components
+            from docket import Docket, Worker
+
+            from fastmcp import settings
+            from fastmcp.server.dependencies import (
+                _current_docket,
+                _current_worker,
+            )
+
+            # Create Docket instance using configured name and URL
+            async with Docket(
+                name=settings.docket.name,
+                url=settings.docket.url,
+            ) as docket:
+                # Store on server instance for cross-task access (FastMCPTransport)
+                self._docket = docket
+
+                # Register task-enabled components with Docket
+                for component in task_components:
+                    component.register_with_docket(docket)
+
+                # Set Docket in ContextVar so CurrentDocket can access it
+                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,
+                    }
+                    if settings.docket.worker_name:
+                        worker_kwargs["name"] = settings.docket.worker_name
+
+                    # Create and start Worker
+                    async with Worker(docket, **worker_kwargs) as worker:
+                        # Store on server instance for cross-context access
+                        self._worker = worker
+                        # Set Worker in ContextVar so CurrentWorker can access it
+                        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:
+                    # Reset ContextVar
+                    _current_docket.reset(docket_token)
+                    # Clear instance attribute
+                    self._docket = None
+        finally:
+            # Reset server ContextVar
+            _current_server.reset(server_token)
+
+    @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
+
+        try:
+            async with (
+                self._lifespan(self) as user_lifespan_result,
+                self._docket_lifespan(),
+            ):
+                self._lifespan_result = user_lifespan_result
+                self._lifespan_result_set = True
+
+                async with AsyncExitStack[bool | None]() as stack:
+                    # 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:
+            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.types import (
+            CancelTaskRequest,
+            GetTaskPayloadRequest,
+            GetTaskRequest,
+            ListTasksRequest,
+            ServerResult,
+        )
+
+        from fastmcp.server.tasks.requests import (
+            tasks_cancel_handler,
+            tasks_get_handler,
+            tasks_list_handler,
+            tasks_result_handler,
+        )
+
+        # Manually register handlers (SDK decorators fail with locally-defined functions)
+        # SDK expects handlers that receive Request objects and return ServerResult
+
+        async def handle_get_task(req: GetTaskRequest) -> ServerResult:
+            params = req.params.model_dump(by_alias=True, exclude_none=True)
+            result = await tasks_get_handler(self, params)
+            return ServerResult(result)
+
+        async def handle_get_task_result(req: GetTaskPayloadRequest) -> ServerResult:
+            params = req.params.model_dump(by_alias=True, exclude_none=True)
+            result = await tasks_result_handler(self, params)
+            return ServerResult(result)
+
+        async def handle_list_tasks(req: ListTasksRequest) -> ServerResult:
+            params = (
+                req.params.model_dump(by_alias=True, exclude_none=True)
+                if req.params
+                else {}
+            )
+            result = await tasks_list_handler(self, params)
+            return ServerResult(result)
+
+        async def handle_cancel_task(req: CancelTaskRequest) -> ServerResult:
+            params = req.params.model_dump(by_alias=True, exclude_none=True)
+            result = await tasks_cancel_handler(self, params)
+            return ServerResult(result)
+
+        # Register directly with SDK (same as what decorators do internally)
+        self._mcp_server.request_handlers[GetTaskRequest] = handle_get_task
+        self._mcp_server.request_handlers[GetTaskPayloadRequest] = (
+            handle_get_task_result
+        )
+        self._mcp_server.request_handlers[ListTasksRequest] = handle_list_tasks
+        self._mcp_server.request_handlers[CancelTaskRequest] = handle_cancel_task
diff --git a/src/fastmcp/server/mixins/mcp_operations.py b/src/fastmcp/server/mixins/mcp_operations.py
new file mode 100644
index 000000000..440fba4b3
--- /dev/null
+++ b/src/fastmcp/server/mixins/mcp_operations.py
@@ -0,0 +1,354 @@
+"""MCP protocol handler setup and wire-format handlers for FastMCP Server."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+import mcp.types
+from mcp.shared.exceptions import McpError
+from mcp.types import ContentBlock
+from pydantic import AnyUrl
+
+from fastmcp.exceptions import DisabledError, NotFoundError
+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(mcp.types.ErrorData(code=-32602, message=str(e))) from e
+
+
+class MCPOperationsMixin:
+    """Mixin providing MCP protocol handler setup and wire-format handlers.
+
+    Note: Methods registered with SDK decorators (e.g., _list_tools_mcp, _call_tool_mcp)
+    cannot use `self: FastMCP` type hints because the SDK's `get_type_hints()` fails
+    to resolve FastMCP at runtime (it's only available under TYPE_CHECKING). When
+    type hints fail to resolve, the SDK falls back to calling handlers with no arguments.
+    These methods use untyped `self` to avoid this issue.
+    """
+
+    def _setup_handlers(self: FastMCP) -> None:
+        """Set up core MCP protocol handlers.
+
+        List handlers use SDK decorators that pass the request object to our handler
+        (needed for pagination cursor). The SDK also populates caches like _tool_cache.
+
+        Exception: list_resource_templates SDK decorator doesn't pass the request,
+        so we register that handler directly.
+
+        The call_tool decorator is from the SDK (supports CreateTaskResult + validate_input).
+        The read_resource and get_prompt decorators are from LowLevelServer to add
+        CreateTaskResult support until the SDK provides it natively.
+        """
+        self._mcp_server.list_tools()(self._list_tools_mcp)
+        self._mcp_server.list_resources()(self._list_resources_mcp)
+        self._mcp_server.list_prompts()(self._list_prompts_mcp)
+
+        # list_resource_templates SDK decorator doesn't pass the request to handlers,
+        # so we register directly to get cursor access for pagination
+        self._mcp_server.request_handlers[mcp.types.ListResourceTemplatesRequest] = (
+            self._wrap_list_handler(self._list_resource_templates_mcp)
+        )
+
+        self._mcp_server.call_tool(validate_input=self.strict_input_validation)(
+            self._call_tool_mcp
+        )
+        self._mcp_server.read_resource()(self._read_resource_mcp)
+        self._mcp_server.get_prompt()(self._get_prompt_mcp)
+
+        # Register SEP-1686 task protocol handlers
+        self._setup_task_protocol_handlers()
+
+    def _wrap_list_handler(
+        self: FastMCP, handler: Callable[..., Awaitable[Any]]
+    ) -> Callable[..., Awaitable[mcp.types.ServerResult]]:
+        """Wrap a list handler to pass the request and return ServerResult."""
+
+        async def wrapper(request: Any) -> mcp.types.ServerResult:
+            result = await handler(request)
+            return mcp.types.ServerResult(result)
+
+        return wrapper
+
+    async def _list_tools_mcp(
+        self, request: mcp.types.ListToolsRequest
+    ) -> mcp.types.ListToolsResult:
+        """
+        List all available tools, in the format expected by the low-level MCP
+        server. Supports pagination when list_page_size is configured.
+        """
+        # Cast self to FastMCP for type checking (see class docstring for why
+        # we can't use `self: FastMCP` annotation on SDK-registered handlers)
+        server = cast("FastMCP", self)
+        logger.debug(f"[{server.name}] Handler called: list_tools")
+
+        tools = dedupe_with_versions(list(await server.list_tools()), lambda t: t.name)
+        sdk_tools = [tool.to_mcp_tool(name=tool.name) for tool in tools]
+
+        # SDK may pass None for internal cache refresh despite type hint
+        cursor = (
+            request.params.cursor if request is not None and request.params else None
+        )
+        page, next_cursor = _apply_pagination(sdk_tools, cursor, server._list_page_size)
+        return mcp.types.ListToolsResult(tools=page, nextCursor=next_cursor)
+
+    async def _list_resources_mcp(
+        self, request: mcp.types.ListResourcesRequest
+    ) -> mcp.types.ListResourcesResult:
+        """
+        List all available resources, in the format expected by the low-level MCP
+        server. Supports pagination when list_page_size is configured.
+        """
+        server = cast("FastMCP", self)
+        logger.debug(f"[{server.name}] Handler called: list_resources")
+
+        resources = dedupe_with_versions(
+            list(await server.list_resources()), lambda r: str(r.uri)
+        )
+        sdk_resources = [
+            resource.to_mcp_resource(uri=str(resource.uri)) for resource in resources
+        ]
+
+        cursor = request.params.cursor if request.params else None
+        page, next_cursor = _apply_pagination(
+            sdk_resources, cursor, server._list_page_size
+        )
+        return mcp.types.ListResourcesResult(resources=page, nextCursor=next_cursor)
+
+    async def _list_resource_templates_mcp(
+        self, request: mcp.types.ListResourceTemplatesRequest
+    ) -> mcp.types.ListResourceTemplatesResult:
+        """
+        List all available resource templates, in the format expected by the low-level MCP
+        server. Supports pagination when list_page_size is configured.
+        """
+        server = cast("FastMCP", self)
+        logger.debug(f"[{server.name}] Handler called: list_resource_templates")
+
+        templates = dedupe_with_versions(
+            list(await server.list_resource_templates()), lambda t: t.uri_template
+        )
+        sdk_templates = [
+            template.to_mcp_template(uriTemplate=template.uri_template)
+            for template in templates
+        ]
+        cursor = request.params.cursor if request.params else None
+        page, next_cursor = _apply_pagination(
+            sdk_templates, cursor, server._list_page_size
+        )
+        return mcp.types.ListResourceTemplatesResult(
+            resourceTemplates=page, nextCursor=next_cursor
+        )
+
+    async def _list_prompts_mcp(
+        self, request: mcp.types.ListPromptsRequest
+    ) -> mcp.types.ListPromptsResult:
+        """
+        List all available prompts, in the format expected by the low-level MCP
+        server. Supports pagination when list_page_size is configured.
+        """
+        server = cast("FastMCP", self)
+        logger.debug(f"[{server.name}] Handler called: list_prompts")
+
+        prompts = dedupe_with_versions(
+            list(await server.list_prompts()), lambda p: p.name
+        )
+        sdk_prompts = [prompt.to_mcp_prompt(name=prompt.name) for prompt in prompts]
+        cursor = request.params.cursor if request.params else None
+        page, next_cursor = _apply_pagination(
+            sdk_prompts, cursor, server._list_page_size
+        )
+        return mcp.types.ListPromptsResult(prompts=page, nextCursor=next_cursor)
+
+    async def _call_tool_mcp(
+        self, key: str, arguments: dict[str, Any]
+    ) -> (
+        list[ContentBlock]
+        | tuple[list[ContentBlock], dict[str, Any]]
+        | mcp.types.CallToolResult
+        | mcp.types.CreateTaskResult
+    ):
+        """
+        Handle MCP 'callTool' requests.
+
+        Extracts task metadata from MCP request context and passes it explicitly
+        to call_tool(). The tool's _run() method handles the backgrounding decision,
+        ensuring middleware runs before Docket.
+
+        Args:
+            key: The name of the tool to call
+            arguments: Arguments to pass to the tool
+
+        Returns:
+            Tool result or CreateTaskResult for background execution
+        """
+        server = cast("FastMCP", self)
+        logger.debug(
+            f"[{server.name}] Handler called: call_tool %s with %s", key, arguments
+        )
+
+        try:
+            # Extract version and task metadata from request context.
+            # fn_key is set by call_tool() after finding the tool.
+            version_str: str | None = None
+            task_meta: TaskMeta | None = None
+            try:
+                ctx = server._mcp_server.request_context
+                # Extract version from request-level _meta.fastmcp.version
+                if ctx.meta:
+                    meta_dict = ctx.meta.model_dump(exclude_none=True)
+                    version_str = meta_dict.get("fastmcp", {}).get("version")
+                # Extract SEP-1686 task metadata
+                if ctx.experimental.is_task:
+                    mcp_task_meta = ctx.experimental.task_metadata
+                    task_meta_dict = mcp_task_meta.model_dump(exclude_none=True)
+                    task_meta = TaskMeta(ttl=task_meta_dict.get("ttl"))
+            except (AttributeError, LookupError):
+                pass
+
+            version = VersionSpec(eq=version_str) if version_str else None
+            result = await server.call_tool(
+                key, arguments, version=version, task_meta=task_meta
+            )
+
+            if isinstance(result, mcp.types.CreateTaskResult):
+                return result
+            return result.to_mcp_result()
+
+        except DisabledError as e:
+            raise NotFoundError(f"Unknown tool: {key!r}") from e
+        except NotFoundError as e:
+            raise NotFoundError(f"Unknown tool: {key!r}") from e
+
+    async def _read_resource_mcp(
+        self, uri: AnyUrl | str
+    ) -> mcp.types.ReadResourceResult | mcp.types.CreateTaskResult:
+        """Handle MCP 'readResource' requests.
+
+        Extracts task metadata from MCP request context and passes it explicitly
+        to read_resource(). The resource's _read() method handles the backgrounding
+        decision, ensuring middleware runs before Docket.
+
+        Args:
+            uri: The resource URI
+
+        Returns:
+            ReadResourceResult or CreateTaskResult for background execution
+        """
+        server = cast("FastMCP", self)
+        logger.debug(f"[{server.name}] Handler called: read_resource %s", uri)
+
+        try:
+            # Extract version and task metadata from request context.
+            version_str: str | None = None
+            task_meta: TaskMeta | None = None
+            try:
+                ctx = server._mcp_server.request_context
+                # Extract version from _meta.fastmcp.version if provided
+                if ctx.meta:
+                    meta_dict = ctx.meta.model_dump(exclude_none=True)
+                    fastmcp_meta = meta_dict.get("fastmcp") or {}
+                    version_str = fastmcp_meta.get("version")
+                # Extract SEP-1686 task metadata
+                if ctx.experimental.is_task:
+                    mcp_task_meta = ctx.experimental.task_metadata
+                    task_meta_dict = mcp_task_meta.model_dump(exclude_none=True)
+                    task_meta = TaskMeta(ttl=task_meta_dict.get("ttl"))
+            except (AttributeError, LookupError):
+                pass
+
+            version = VersionSpec(eq=version_str) if version_str else None
+            result = await server.read_resource(
+                str(uri), version=version, task_meta=task_meta
+            )
+
+            if isinstance(result, mcp.types.CreateTaskResult):
+                return result
+            return result.to_mcp_result(uri)
+        except DisabledError as e:
+            raise McpError(
+                mcp.types.ErrorData(
+                    code=-32002, message=f"Resource not found: {str(uri)!r}"
+                )
+            ) from e
+        except NotFoundError as e:
+            raise McpError(
+                mcp.types.ErrorData(code=-32002, message=f"Resource not found: {e}")
+            ) from e
+
+    async def _get_prompt_mcp(
+        self, name: str, arguments: dict[str, Any] | None
+    ) -> mcp.types.GetPromptResult | mcp.types.CreateTaskResult:
+        """Handle MCP 'getPrompt' requests.
+
+        Extracts task metadata from MCP request context and passes it explicitly
+        to render_prompt(). The prompt's _render() method handles the backgrounding
+        decision, ensuring middleware runs before Docket.
+
+        Args:
+            name: The prompt name
+            arguments: Prompt arguments
+
+        Returns:
+            GetPromptResult or CreateTaskResult for background execution
+        """
+        server = cast("FastMCP", self)
+        logger.debug(
+            f"[{server.name}] Handler called: get_prompt %s with %s", name, arguments
+        )
+
+        try:
+            # Extract version and task metadata from request context.
+            # fn_key is set by render_prompt() after finding the prompt.
+            version_str: str | None = None
+            task_meta: TaskMeta | None = None
+            try:
+                ctx = server._mcp_server.request_context
+                # Extract version from request-level _meta.fastmcp.version
+                if ctx.meta:
+                    meta_dict = ctx.meta.model_dump(exclude_none=True)
+                    version_str = meta_dict.get("fastmcp", {}).get("version")
+                # Extract SEP-1686 task metadata
+                if ctx.experimental.is_task:
+                    mcp_task_meta = ctx.experimental.task_metadata
+                    task_meta_dict = mcp_task_meta.model_dump(exclude_none=True)
+                    task_meta = TaskMeta(ttl=task_meta_dict.get("ttl"))
+            except (AttributeError, LookupError):
+                pass
+
+            version = VersionSpec(eq=version_str) if version_str else None
+            result = await server.render_prompt(
+                name, arguments, version=version, task_meta=task_meta
+            )
+
+            if isinstance(result, mcp.types.CreateTaskResult):
+                return result
+            return result.to_mcp_prompt_result()
+        except DisabledError as e:
+            raise NotFoundError(f"Unknown prompt: {name!r}") from e
+        except NotFoundError:
+            raise
diff --git a/src/fastmcp/server/mixins/transport.py b/src/fastmcp/server/mixins/transport.py
new file mode 100644
index 000000000..833b5e385
--- /dev/null
+++ b/src/fastmcp/server/mixins/transport.py
@@ -0,0 +1,339 @@
+"""Transport-related methods for FastMCP Server."""
+
+from __future__ import annotations
+
+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 (
+    StarletteWithLifespan,
+    create_sse_app,
+    create_streamable_http_app,
+)
+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__)
+
+
+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 providers.
+
+        Returns a list of all custom HTTP routes from this server and
+        from all providers that have HTTP routes (e.g., FastMCPProvider).
+
+        Returns:
+            List of Starlette BaseRoute objects
+        """
+        return list(self._additional_http_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
+                                ),
+                            ),
+                            stateless=stateless,
+                        )
+        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,
+    ) -> 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
+        """
+        # 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 or fastmcp.settings.host
+        port = port or fastmcp.settings.port
+        default_log_level_to_use = (log_level or fastmcp.settings.log_level).lower()
+
+        app = self.http_app(
+            path=path,
+            transport=transport,
+            middleware=middleware,
+            json_response=json_response,
+            stateless_http=stateless_http,
+        )
+
+        # 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": 0,
+            "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 ""
+                logger.info(
+                    f"Starting MCP server {self.name!r} with transport {transport!r}{mode} on http://{host}:{port}/{path}"
+                )
+
+                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,
+    ) -> 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.
+
+        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 or 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,
+            )
+        elif transport == "sse":
+            return create_sse_app(
+                server=self,
+                message_path=fastmcp.settings.message_path,
+                sse_path=path or fastmcp.settings.sse_path,
+                auth=self.auth,
+                debug=fastmcp.settings.debug,
+                middleware=middleware,
+            )
+        else:
+            raise ValueError(f"Unknown transport: {transport}")
diff --git a/src/fastmcp/server/openapi/__init__.py b/src/fastmcp/server/openapi/__init__.py
new file mode 100644
index 000000000..5c19c90eb
--- /dev/null
+++ b/src/fastmcp/server/openapi/__init__.py
@@ -0,0 +1,55 @@
+"""OpenAPI server implementation for FastMCP.
+
+.. deprecated::
+    This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+
+The recommended approach is to use OpenAPIProvider with FastMCP:
+
+    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("My API Server")
+    mcp.add_provider(provider)
+
+FastMCPOpenAPI is still available but deprecated.
+"""
+
+import warnings
+
+warnings.warn(
+    "fastmcp.server.openapi is deprecated. "
+    "Import from fastmcp.server.providers.openapi instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export from new canonical location
+from fastmcp.server.providers.openapi import (  # noqa: E402
+    ComponentFn as ComponentFn,
+    MCPType as MCPType,
+    OpenAPIProvider as OpenAPIProvider,
+    OpenAPIResource as OpenAPIResource,
+    OpenAPIResourceTemplate as OpenAPIResourceTemplate,
+    OpenAPITool as OpenAPITool,
+    RouteMap as RouteMap,
+    RouteMapFn as RouteMapFn,
+)
+
+# Keep FastMCPOpenAPI for backwards compat (it has its own deprecation warning)
+from fastmcp.server.openapi.server import FastMCPOpenAPI as FastMCPOpenAPI  # noqa: E402
+
+__all__ = [
+    "ComponentFn",
+    "FastMCPOpenAPI",
+    "MCPType",
+    "OpenAPIProvider",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+    "RouteMap",
+    "RouteMapFn",
+]
diff --git a/src/fastmcp/server/openapi/components.py b/src/fastmcp/server/openapi/components.py
new file mode 100644
index 000000000..06a381a9e
--- /dev/null
+++ b/src/fastmcp/server/openapi/components.py
@@ -0,0 +1,28 @@
+"""OpenAPI component implementations - backwards compatibility stub.
+
+This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+warnings.warn(
+    "fastmcp.server.openapi.components is deprecated. "
+    "Import from fastmcp.server.providers.openapi instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from fastmcp.server.providers.openapi import (  # noqa: E402
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+    OpenAPITool,
+)
+
+# Export public symbols
+__all__ = [
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+]
diff --git a/src/fastmcp/server/openapi/routing.py b/src/fastmcp/server/openapi/routing.py
new file mode 100644
index 000000000..9acad5e84
--- /dev/null
+++ b/src/fastmcp/server/openapi/routing.py
@@ -0,0 +1,46 @@
+"""Route mapping logic for OpenAPI operations.
+
+.. deprecated::
+    This module is deprecated. Import from fastmcp.server.providers.openapi instead.
+"""
+
+# ruff: noqa: E402
+
+import warnings
+
+# Backwards compatibility - export everything that was previously public
+__all__ = [
+    "DEFAULT_ROUTE_MAPPINGS",
+    "ComponentFn",
+    "MCPType",
+    "RouteMap",
+    "RouteMapFn",
+    "_determine_route_type",
+]
+
+warnings.warn(
+    "fastmcp.server.openapi.routing is deprecated. "
+    "Import from fastmcp.server.providers.openapi instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export from new canonical location
+from fastmcp.server.providers.openapi.routing import (
+    DEFAULT_ROUTE_MAPPINGS as DEFAULT_ROUTE_MAPPINGS,
+)
+from fastmcp.server.providers.openapi.routing import (
+    ComponentFn as ComponentFn,
+)
+from fastmcp.server.providers.openapi.routing import (
+    MCPType as MCPType,
+)
+from fastmcp.server.providers.openapi.routing import (
+    RouteMap as RouteMap,
+)
+from fastmcp.server.providers.openapi.routing import (
+    RouteMapFn as RouteMapFn,
+)
+from fastmcp.server.providers.openapi.routing import (
+    _determine_route_type as _determine_route_type,
+)
diff --git a/src/fastmcp/server/openapi/server.py b/src/fastmcp/server/openapi/server.py
new file mode 100644
index 000000000..3171ca763
--- /dev/null
+++ b/src/fastmcp/server/openapi/server.py
@@ -0,0 +1,124 @@
+"""FastMCPOpenAPI - backwards compatibility wrapper.
+
+This class is deprecated. Use FastMCP with OpenAPIProvider instead:
+
+    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("My API Server", providers=[provider])
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import httpx
+
+from fastmcp.server.providers.openapi import (
+    ComponentFn,
+    OpenAPIProvider,
+    RouteMap,
+    RouteMapFn,
+)
+from fastmcp.server.server import FastMCP
+
+
+class FastMCPOpenAPI(FastMCP):
+    """FastMCP server implementation that creates components from an OpenAPI schema.
+
+    .. deprecated::
+        Use FastMCP with OpenAPIProvider instead. This class will be
+        removed in a future version.
+
+    Example (deprecated):
+        ```python
+        from fastmcp.server.openapi import FastMCPOpenAPI
+        import httpx
+
+        server = FastMCPOpenAPI(
+            openapi_spec=spec,
+            client=httpx.AsyncClient(),
+        )
+        ```
+
+    New approach:
+        ```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])
+        ```
+    """
+
+    def __init__(
+        self,
+        openapi_spec: dict[str, Any],
+        client: httpx.AsyncClient | None = None,
+        name: str | 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,
+        **settings: Any,
+    ):
+        """Initialize a FastMCP server from an OpenAPI schema.
+
+        .. deprecated::
+            Use FastMCP with OpenAPIProvider instead.
+
+        Args:
+            openapi_spec: OpenAPI schema as a dictionary
+            client: Optional httpx AsyncClient for making HTTP requests.
+                If not provided, a default client is created from the spec.
+            name: Optional name for the 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
+            **settings: Additional settings for FastMCP
+        """
+        warnings.warn(
+            "FastMCPOpenAPI is deprecated. Use FastMCP with OpenAPIProvider instead:\n"
+            "    provider = OpenAPIProvider(openapi_spec=spec, client=client)\n"
+            "    mcp = FastMCP('name', providers=[provider])",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        super().__init__(name=name or "OpenAPI FastMCP", **settings)
+
+        # Store references for backwards compatibility
+        self._client = client
+        self._mcp_component_fn = mcp_component_fn
+
+        # Create provider with the client
+        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,
+        )
+
+        self.add_provider(provider)
+
+        # Expose internal attributes for backwards compatibility
+        self._spec = provider._spec
+        self._director = provider._director
+
+
+# Export public symbols
+__all__ = [
+    "FastMCPOpenAPI",
+]
diff --git a/src/fastmcp/server/providers/__init__.py b/src/fastmcp/server/providers/__init__.py
new file mode 100644
index 000000000..4c673be03
--- /dev/null
+++ b/src/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):
+    """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/src/fastmcp/server/providers/aggregate.py b/src/fastmcp/server/providers/aggregate.py
new file mode 100644
index 000000000..674e2b2c3
--- /dev/null
+++ b/src/fastmcp/server/providers/aggregate.py
@@ -0,0 +1,261 @@
+"""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, 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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool import Tool
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+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 (graceful degradation).
+
+    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) -> None:
+        """Initialize with an optional sequence of providers.
+
+        Args:
+            providers: Optional initial providers (without namespacing).
+                For namespaced providers, use add_provider() instead.
+        """
+        super().__init__()
+        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."""
+        collected: list[T] = []
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                logger.debug(
+                    f"Error during {operation} from provider "
+                    f"{self.providers[i]}: {result}"
+                )
+                continue
+            collected.extend(result)
+        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):
+                    logger.debug(
+                        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]
+
+    # -------------------------------------------------------------------------
+    # 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]
+
+    # -------------------------------------------------------------------------
+    # 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(
+            results, f"get_resource_template({uri!r})"
+        )  # type: ignore[return-value]
+
+    # -------------------------------------------------------------------------
+    # 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]
+
+    # -------------------------------------------------------------------------
+    # 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/src/fastmcp/server/providers/base.py b/src/fastmcp/server/providers/base.py
new file mode 100644
index 000000000..ccd48765f
--- /dev/null
+++ b/src/fastmcp/server/providers/base.py
@@ -0,0 +1,578 @@
+"""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, Literal, cast
+
+from typing_extensions import Self
+
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.transforms.visibility import Visibility
+from fastmcp.tools.tool import Tool
+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.server.transforms import Transform
+
+
+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 = base
+        for transform in self.transforms:
+            chain = partial(transform.get_tool, call_next=chain)
+
+        return await chain(name, version=version)
+
+    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 = base
+        for transform in self.transforms:
+            chain = partial(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 = base
+        for transform in self.transforms:
+            chain = partial(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 = base
+        for transform in self.transforms:
+            chain = partial(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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    # -------------------------------------------------------------------------
+    # 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/src/fastmcp/server/providers/fastmcp_provider.py b/src/fastmcp/server/providers/fastmcp_provider.py
new file mode 100644
index 000000000..92038c540
--- /dev/null
+++ b/src/fastmcp/server/providers/fastmcp_provider.py
@@ -0,0 +1,704 @@
+"""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
+
+import re
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, overload
+from urllib.parse import quote
+
+import mcp.types
+from mcp.types import AnyUrl
+
+from fastmcp.prompts.prompt import Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.telemetry import delegate_span
+from fastmcp.tools.tool 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
+
+
+def _expand_uri_template(template: str, params: dict[str, Any]) -> str:
+    """Expand a URI template with parameters.
+
+    Handles both {name} path placeholders and RFC 6570 {?param1,param2}
+    query parameter syntax.
+    """
+    result = template
+
+    # Replace {name} path placeholders
+    for key, value in params.items():
+        result = re.sub(rf"\{{{key}\}}", str(value), result)
+
+    # 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:
+            if name in params:
+                parts.append(f"{quote(name)}={quote(str(params[name]))}")
+        if parts:
+            return "?" + "&".join(parts)
+        return ""
+
+    result = re.sub(r"\{\?([^}]+)\}", _expand_query_block, result)
+
+    return result
+
+
+# -----------------------------------------------------------------------------
+# 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,
+            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 ""
+        ):
+            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 ""
+        ):
+            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 ""
+        ):
+            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,
+        )
+
+    @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 ""
+        ):
+            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)
+
+    # -------------------------------------------------------------------------
+    # 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 user lifespan.
+
+        This starts only the wrapped server's user-defined lifespan, NOT its
+        full _lifespan_manager() (which includes Docket). The parent server's
+        Docket handles all background tasks.
+        """
+        async with self.server._lifespan(self.server):
+            yield
diff --git a/src/fastmcp/server/providers/filesystem.py b/src/fastmcp/server/providers/filesystem.py
new file mode 100644
index 000000000..2306a48a7
--- /dev/null
+++ b/src/fastmcp/server/providers/filesystem.py
@@ -0,0 +1,226 @@
+"""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 Sequence
+from pathlib import Path
+
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource 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.tool 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
+
+        # 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."""
+        # Clear existing components if reloading
+        if self._loaded:
+            self._components.clear()
+
+        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 _ensure_loaded(self) -> None:
+        """Ensure components are loaded, reloading if in reload mode.
+
+        Uses a lock to serialize concurrent reload operations and runs
+        filesystem I/O off the event loop using asyncio.to_thread.
+        """
+        if not self._reload and self._loaded:
+            return
+
+        # Create lock lazily (can't create in __init__ without event loop)
+        if self._reload_lock is None:
+            self._reload_lock = asyncio.Lock()
+
+        async with self._reload_lock:
+            # Double-check after acquiring lock
+            if self._reload or not self._loaded:
+                await asyncio.to_thread(self._load_components)
+
+    # Override provider methods to support reload mode
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all tools, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_tools()
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_tool(name, version)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all resources, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_resources()
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_resource(uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Return all resource templates, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_resource_templates()
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_resource_template(uri, version)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return all prompts, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_prompts()
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_prompt(name, version)
+
+    def __repr__(self) -> str:
+        return f"FileSystemProvider(root={self._root!r}, reload={self._reload})"
diff --git a/src/fastmcp/server/providers/filesystem_discovery.py b/src/fastmcp/server/providers/filesystem_discovery.py
new file mode 100644
index 000000000..96fe81b81
--- /dev/null
+++ b/src/fastmcp/server/providers/filesystem_discovery.py
@@ -0,0 +1,327 @@
+"""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 importlib.util
+import sys
+from dataclasses import dataclass, field
+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) -> Path | None:
+    """Find the root of the package containing this file.
+
+    Walks up the directory tree until we find a directory without __init__.py.
+
+    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 _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 import_module_from_file(file_path: Path) -> 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.
+
+    Args:
+        file_path: Path to the Python file.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported.
+    """
+    file_path = file_path.resolve()
+
+    # Check if this file is part of a package
+    package_root = _find_package_root(file_path)
+
+    if package_root is not None:
+        # Import as part of a package
+        module_name = _compute_module_name(file_path, package_root)
+
+        # Ensure package root's parent is in sys.path
+        package_parent = str(package_root.parent)
+        if package_parent not in sys.path:
+            sys.path.insert(0, package_parent)
+
+        # Import using standard import machinery
+        # If already imported, reload to pick up changes (for reload mode)
+        try:
+            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
+    else:
+        # Import directly using spec_from_file_location
+        module_name = file_path.stem
+
+        # Ensure parent directory is in sys.path for imports
+        parent_dir = str(file_path.parent)
+        if parent_dir not in sys.path:
+            sys.path.insert(0, parent_dir)
+
+        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}")
+
+        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
+
+
+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.function_prompt import PromptMeta
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.function_resource import ResourceMeta
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.dependencies import without_injected_parameters
+    from fastmcp.tools.function_tool import ToolMeta
+    from fastmcp.tools.tool import Tool
+
+    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,
+                    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,
+                    exclude_args=meta.exclude_args,
+                    serializer=meta.serializer,
+                    auth=meta.auth,
+                )
+                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,
+                        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,
+                        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,
+                    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)
+        except ImportError as e:
+            result.failed_files[file_path] = str(e)
+            continue
+        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/src/fastmcp/server/providers/local_provider/__init__.py b/src/fastmcp/server/providers/local_provider/__init__.py
new file mode 100644
index 000000000..f3587e2d8
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/local_provider/decorators/__init__.py b/src/fastmcp/server/providers/local_provider/decorators/__init__.py
new file mode 100644
index 000000000..fe66eafa4
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/local_provider/decorators/prompts.py b/src/fastmcp/server/providers/local_provider/decorators/prompts.py
new file mode 100644
index 000000000..d36c7d2f4
--- /dev/null
+++ b/src/fastmcp/server/providers/local_provider/decorators/prompts.py
@@ -0,0 +1,258 @@
+"""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 mcp.types import AnyFunction
+
+import fastmcp
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+
+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"
+                )
+
+            resolved_task: bool | TaskConfig = task if task is not None else False
+
+            if fastmcp.settings.decorator_mode == "object":
+                prompt_obj = Prompt.from_function(
+                    fn,
+                    name=prompt_name,
+                    version=version,
+                    title=title,
+                    description=description,
+                    icons=icons,
+                    tags=tags,
+                    meta=meta,
+                    task=resolved_task,
+                    auth=auth,
+                )
+                self._add_component(prompt_obj)
+                if not enabled:
+                    self.disable(keys={prompt_obj.key})
+                return prompt_obj
+            else:
+                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]
+                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/src/fastmcp/server/providers/local_provider/decorators/resources.py b/src/fastmcp/server/providers/local_provider/decorators/resources.py
new file mode 100644
index 000000000..80a3e9a5c
--- /dev/null
+++ b/src/fastmcp/server/providers/local_provider/decorators/resources.py
@@ -0,0 +1,242 @@
+"""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, AnyFunction
+
+import fastmcp
+from fastmcp.resources.function_resource import resource as standalone_resource
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+
+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"
+            )
+
+        resolved_task: bool | TaskConfig = task if task is not None else False
+
+        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"
+                )
+
+            if fastmcp.settings.decorator_mode == "object":
+                create_resource = standalone_resource(
+                    uri,
+                    name=name,
+                    version=version,
+                    title=title,
+                    description=description,
+                    icons=icons,
+                    mime_type=mime_type,
+                    tags=tags,
+                    annotations=annotations,
+                    meta=meta,
+                    task=resolved_task,
+                    auth=auth,
+                )
+                obj = create_resource(fn)
+                # In legacy mode, standalone_resource always returns a component
+                assert isinstance(obj, (Resource, ResourceTemplate))
+                if isinstance(obj, ResourceTemplate):
+                    self.add_template(obj)
+                    if not enabled:
+                        self.disable(keys={obj.key})
+                else:
+                    self.add_resource(obj)
+                    if not enabled:
+                        self.disable(keys={obj.key})
+                return obj
+            else:
+                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]
+                self.add_resource(fn)
+                return fn
+
+        return decorator
diff --git a/src/fastmcp/server/providers/local_provider/decorators/tools.py b/src/fastmcp/server/providers/local_provider/decorators/tools.py
new file mode 100644
index 000000000..796be4224
--- /dev/null
+++ b/src/fastmcp/server/providers/local_provider/decorators/tools.py
@@ -0,0 +1,444 @@
+"""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
+import warnings
+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 AnyFunction, ToolAnnotations
+
+import fastmcp
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.types import 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
+    from fastmcp.tools.tool import ToolResultSerializerType
+
+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 _ensure_prefab_renderer(provider: LocalProvider) -> None:
+    """Lazily register the shared prefab renderer as a ui:// resource."""
+    from prefab_ui.renderer import get_renderer_csp, get_renderer_html
+
+    from fastmcp.resources.types import TextResource
+    from fastmcp.server.apps import (
+        UI_MIME_TYPE,
+        AppConfig,
+        ResourceCSP,
+        app_config_to_meta_dict,
+    )
+
+    renderer_key = f"resource:{PREFAB_RENDERER_URI}@"
+    if renderer_key in provider._components:
+        return
+
+    csp = get_renderer_csp()
+    resource_app = AppConfig(
+        csp=ResourceCSP(
+            resource_domains=csp.get("resource_domains"),
+            connect_domains=csp.get("connect_domains"),
+        )
+    )
+    resource = TextResource(
+        uri=PREFAB_RENDERER_URI,  # type: ignore[arg-type]  # AnyUrl accepts ui:// scheme at runtime
+        name="Prefab Renderer",
+        text=get_renderer_html(),
+        mime_type=UI_MIME_TYPE,
+        meta={"ui": app_config_to_meta_dict(resource_app)},
+    )
+    provider._add_component(resource)
+
+
+def _expand_prefab_ui_meta(tool: Tool) -> None:
+    """Expand meta["ui"] = True into the full AppConfig dict for a prefab tool."""
+    from prefab_ui.renderer import get_renderer_csp
+
+    from fastmcp.server.apps import AppConfig, ResourceCSP, app_config_to_meta_dict
+
+    csp = get_renderer_csp()
+    app_config = AppConfig(
+        resource_uri=PREFAB_RENDERER_URI,
+        csp=ResourceCSP(
+            resource_domains=csp.get("resource_domains"),
+            connect_domains=csp.get("connect_domains"),
+        ),
+    )
+    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:
+    """Auto-wire prefab UI metadata and renderer resource if needed."""
+    if not _HAS_PREFAB:
+        return
+
+    meta = tool.meta or {}
+    ui = meta.get("ui")
+
+    if ui is True:
+        # Explicit app=True: expand to full AppConfig and register renderer
+        _ensure_prefab_renderer(provider)
+        _expand_prefab_ui_meta(tool)
+    elif ui is None and _has_prefab_return_type(tool):
+        # Inference: return type is a prefab type, auto-wire
+        _ensure_prefab_renderer(provider)
+        _expand_prefab_ui_meta(tool)
+    # If ui is a dict, it's already manually configured — leave it alone
+
+
+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.server.apps 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,
+                    exclude_args=fmeta.exclude_args,
+                    serializer=fmeta.serializer,
+                    timeout=fmeta.timeout,
+                    auth=fmeta.auth,
+                )
+            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,
+        exclude_args: list[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        serializer: ToolResultSerializerType | None = None,  # Deprecated
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> 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,
+        exclude_args: list[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        serializer: ToolResultSerializerType | None = None,  # Deprecated
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> Callable[[F], F]: ...
+
+    # NOTE: This method mirrors fastmcp.tools.tool() but adds registration,
+    # the `enabled` param, and supports deprecated params (serializer, exclude_args).
+    # When deprecated params are removed, this should 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,
+        exclude_args: list[str] | None = None,
+        meta: dict[str, Any] | None = None,
+        enabled: bool = True,
+        task: bool | TaskConfig | None = None,
+        serializer: ToolResultSerializerType | None = None,  # Deprecated
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | None = None,
+    ) -> (
+        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
+            exclude_args: Optional list of argument names to exclude from the tool schema
+            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
+            serializer: Deprecated. Return ToolResult from your tools for full control over serialization.
+
+        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 serializer is not None and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The `serializer` parameter is deprecated. "
+                "Return ToolResult from your tools for full control over serialization. "
+                "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        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"
+                )
+
+            resolved_task: bool | TaskConfig = task if task is not None else False
+
+            if fastmcp.settings.decorator_mode == "object":
+                tool_obj = Tool.from_function(
+                    fn,
+                    name=tool_name,
+                    version=version,
+                    title=title,
+                    description=description,
+                    icons=icons,
+                    tags=tags,
+                    output_schema=output_schema,
+                    annotations=annotations,
+                    exclude_args=exclude_args,
+                    meta=meta,
+                    serializer=serializer,
+                    task=resolved_task,
+                    timeout=timeout,
+                    auth=auth,
+                )
+                self._add_component(tool_obj)
+                if not enabled:
+                    self.disable(keys={tool_obj.key})
+                _maybe_apply_prefab_ui(self, tool_obj)
+                return tool_obj
+            else:
+                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,
+                    exclude_args=exclude_args,
+                    serializer=serializer,
+                    timeout=timeout,
+                    auth=auth,
+                    enabled=enabled,
+                )
+                target = fn.__func__ if hasattr(fn, "__func__") else fn
+                target.__fastmcp__ = metadata  # type: ignore[attr-defined]
+                tool_obj = 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,
+            exclude_args=exclude_args,
+            meta=meta,
+            enabled=enabled,
+            task=task,
+            serializer=serializer,
+            timeout=timeout,
+            auth=auth,
+        )
diff --git a/src/fastmcp/server/providers/local_provider/local_provider.py b/src/fastmcp/server/providers/local_provider/local_provider.py
new file mode 100644
index 000000000..a1b8fe584
--- /dev/null
+++ b/src/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.prompt import Prompt
+from fastmcp.resources.resource 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.tool 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]
+            # "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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    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)  # type: ignore[type-var]
+
+    # =========================================================================
+    # 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/src/fastmcp/server/providers/openapi/README.md b/src/fastmcp/server/providers/openapi/README.md
new file mode 100644
index 000000000..8c5e890c4
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/openapi/__init__.py b/src/fastmcp/server/providers/openapi/__init__.py
new file mode 100644
index 000000000..3cbdde5e8
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/openapi/components.py b/src/fastmcp/server/providers/openapi/components.py
new file mode 100644
index 000000000..7d7722666
--- /dev/null
+++ b/src/fastmcp/server/providers/openapi/components.py
@@ -0,0 +1,420 @@
+"""OpenAPI component classes: Tool, Resource, and ResourceTemplate."""
+
+from __future__ import annotations
+
+import json
+import re
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from mcp.types import ToolAnnotations
+from pydantic.networks import AnyUrl
+
+import fastmcp
+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.tool 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,
+        serializer: Callable[[Any], str] | None = None,  # Deprecated
+    ):
+        if serializer is not None and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The `serializer` parameter is deprecated. "
+                "Return ToolResult from your tools for full control over serialization. "
+                "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        super().__init__(
+            name=name,
+            description=description,
+            parameters=parameters,
+            output_schema=output_schema,
+            tags=tags or set(),
+            annotations=annotations,
+            serializer=serializer,
+        )
+        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,
+    ):
+        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
+
+    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:
+            path = self._route.path
+            resource_uri = str(self.uri)
+
+            # If this is a templated resource, extract path parameters from the URI
+            if "{" in path and "}" in path:
+                parts = resource_uri.split("/")
+
+                if len(parts) > 1:
+                    path_params = {}
+                    param_matches = re.findall(r"\{([^}]+)\}", path)
+                    if param_matches:
+                        param_matches.sort(reverse=True)
+                        expected_param_count = len(parts) - 1
+                        for i, param_name in enumerate(param_matches):
+                            if i < expected_param_count:
+                                param_value = parts[-1 - i]
+                                path_params[param_name] = param_value
+
+                    for param_name, param_value in path_params.items():
+                        path = path.replace(f"{{{param_name}}}", str(param_value))
+
+            # Build headers with correct precedence
+            headers: dict[str, str] = {}
+            if self._client.headers:
+                headers.update(self._client.headers)
+            mcp_headers = get_http_headers()
+            if mcp_headers:
+                headers.update(mcp_headers)
+
+            response = await self._client.request(
+                method=self._route.method,
+                url=path,
+                headers=headers,
+            )
+            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
+
+
+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()]
+
+        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 []),
+        )
diff --git a/src/fastmcp/server/providers/openapi/provider.py b/src/fastmcp/server/providers/openapi/provider.py
new file mode 100644
index 000000000..1e64d88c9
--- /dev/null
+++ b/src/fastmcp/server/providers/openapi/provider.py
@@ -0,0 +1,433 @@
+"""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.tool 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"]
+        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)  # type: ignore[type-var]
+
+    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/src/fastmcp/server/providers/openapi/routing.py b/src/fastmcp/server/providers/openapi/routing.py
new file mode 100644
index 000000000..7805f0011
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/proxy.py b/src/fastmcp/server/providers/proxy.py
new file mode 100644
index 000000000..8fc1da93e
--- /dev/null
+++ b/src/fastmcp/server/providers/proxy.py
@@ -0,0 +1,968 @@
+"""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
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import quote
+
+import mcp.types
+from mcp import ServerSession
+from mcp.client.session import ClientSession
+from mcp.server.lowlevel.server import request_ctx
+from mcp.shared.context import LifespanContextT, RequestContext
+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, FastMCP1Server
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.roots import RootsList
+from fastmcp.client.telemetry import client_span
+from fastmcp.client.transports import ClientTransportT
+from fastmcp.exceptions import ResourceError, ToolError
+from fastmcp.mcp_config import MCPConfig
+from fastmcp.prompts import Message, Prompt, PromptResult
+from fastmcp.prompts.prompt import PromptArgument
+from fastmcp.resources import Resource, ResourceTemplate
+from fastmcp.resources.resource import ResourceContent, ResourceResult
+from fastmcp.server.context import Context
+from fastmcp.server.dependencies import get_context
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.server import FastMCP
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.tool import Tool, ToolResult
+from fastmcp.utilities.components import FastMCPComponent, get_fastmcp_metadata
+from fastmcp.utilities.logging import get_logger
+
+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]]
+
+
+# -----------------------------------------------------------------------------
+# 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.inputSchema,
+            annotations=mcp_tool.annotations,
+            output_schema=mcp_tool.outputSchema,
+            icons=mcp_tool.icons,
+            meta=mcp_tool.meta,
+            tags=get_fastmcp_metadata(mcp_tool.meta).get("tags", []),
+        )
+
+    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
+        ) as span:
+            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
+            client = await self._get_client()
+            async with client:
+                ctx = context or get_context()
+                # StatefulProxyClient reuses sessions across requests, so
+                # its receive-loop task has stale ContextVars from the first
+                # request. Stash the current RequestContext in the shared
+                # ref so handlers can restore it before forwarding.
+                if isinstance(client, StatefulProxyClient):
+                    cast(list[Any], client._proxy_rc_ref)[0] = (
+                        ctx.request_context,
+                        ctx._fastmcp,  # weakref to FastMCP, not the Context
+                    )
+                # Build meta dict from request context
+                meta: dict[str, Any] | None = None
+                if hasattr(ctx, "request_context"):
+                    req_ctx = ctx.request_context
+                    # Start with existing meta if present
+                    if hasattr(req_ctx, "meta") and req_ctx.meta:
+                        meta = dict(req_ctx.meta)
+                    # Add task metadata if this is a task request
+                    if (
+                        hasattr(req_ctx, "experimental")
+                        and hasattr(req_ctx.experimental, "is_task")
+                        and req_ctx.experimental.is_task
+                    ):
+                        task_metadata = req_ctx.experimental.task_metadata
+                        if task_metadata:
+                            meta = meta or {}
+                            meta["modelcontextprotocol.io/task"] = (
+                                task_metadata.model_dump(exclude_none=True)
+                            )
+
+                result = await client.call_tool_mcp(
+                    name=backend_name, arguments=arguments, meta=meta
+                )
+            if result.isError:
+                raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)
+            # Preserve backend's meta (includes task metadata for background tasks)
+            return ToolResult(
+                content=result.content,
+                structured_content=result.structuredContent,
+                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,
+        }
+
+
+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,
+    ):
+        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.mimeType 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(
+            f"resources/read {backend_uri}",
+            "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:
+                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.mimeType,
+                            meta=item.meta,
+                        )
+                    )
+                elif isinstance(item, BlobResourceContents):
+                    contents.append(
+                        ResourceContent(
+                            content=base64.b64decode(item.blob),
+                            mime_type=item.mimeType,
+                            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,
+        }
+
+
+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:
+        """Factory method to create a ProxyTemplate from a raw MCP template schema."""
+
+        return cls(
+            client_factory=client_factory,
+            uri_template=mcp_template.uriTemplate,
+            name=mcp_template.name,
+            title=mcp_template.title,
+            description=mcp_template.description,
+            mime_type=mcp_template.mimeType 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.
+        # quote params to ensure they are valid for the uri_template
+        backend_template = self._backend_uri_template or self.uri_template
+        parameterized_uri = backend_template.format(
+            **{k: quote(v, safe="") for k, v in params.items()}
+        )
+        client = await self._get_client()
+        async with client:
+            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.mimeType,
+                        meta=item.meta,
+                    )
+                )
+            elif isinstance(item, BlobResourceContents):
+                contents.append(
+                    ResourceContent(
+                        content=base64.b64decode(item.blob),
+                        mime_type=item.mimeType,
+                        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
+            ].mimeType,  # 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,
+        }
+
+
+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]
+        """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
+        ) as span:
+            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
+            client = await self._get_client()
+            async with client:
+                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,
+        }
+
+
+# -----------------------------------------------------------------------------
+# ProxyProvider
+# -----------------------------------------------------------------------------
+
+
+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.
+
+    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,
+    ):
+        """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.
+        """
+        super().__init__()
+        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
+
+    # -------------------------------------------------------------------------
+    # 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()
+                return [
+                    ProxyTool.from_mcp_tool(self.client_factory, t) for t in mcp_tools
+                ]
+        except McpError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                return []
+            raise
+
+    # -------------------------------------------------------------------------
+    # 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()
+                return [
+                    ProxyResource.from_mcp_resource(self.client_factory, r)
+                    for r in mcp_resources
+                ]
+        except McpError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                return []
+            raise
+
+    # -------------------------------------------------------------------------
+    # 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()
+                return [
+                    ProxyTemplate.from_mcp_template(self.client_factory, t)
+                    for t in mcp_templates
+                ]
+        except McpError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                return []
+            raise
+
+    # -------------------------------------------------------------------------
+    # 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()
+                return [
+                    ProxyPrompt.from_mcp_prompt(self.client_factory, p)
+                    for p in mcp_prompts
+                ]
+        except McpError as e:
+            if e.error.code == METHOD_NOT_FOUND:
+                return []
+            raise
+
+    # -------------------------------------------------------------------------
+    # 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]
+        | FastMCP1Server
+        | 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
+        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,
+        **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.
+            **kwargs: Additional settings for the FastMCP server.
+        """
+        super().__init__(**kwargs)
+        self.client_factory = client_factory
+        provider: Provider = ProxyProvider(client_factory)
+        self.add_provider(provider)
+
+
+# -----------------------------------------------------------------------------
+# ProxyClient and Related
+# -----------------------------------------------------------------------------
+
+
+async def default_proxy_roots_handler(
+    context: RequestContext[ClientSession, LifespanContextT],
+) -> 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: RequestContext[ClientSession, LifespanContextT],
+) -> 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.systemPrompt,
+        temperature=params.temperature,
+        max_tokens=params.maxTokens,
+        model_preferences=params.modelPreferences,
+    )
+    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: RequestContext[ClientSession, LifespanContextT],
+) -> 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.requestedSchema
+        if isinstance(params, ElicitRequestFormParams)
+        else {"type": "object", "properties": {}}
+    )
+    result = await ctx.session.elicit(
+        message=message,
+        requestedSchema=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`` and ``_current_context`` ContextVars from stashed values.
+
+    Called at the start of proxy handler invocations in
+    ``StatefulProxyClient`` to fix stale ContextVars in the receive-loop
+    task.  Only overrides when the ContextVar is genuinely stale (same
+    session, different request_id) to avoid corrupting the concurrent
+    case where multiple sessions share the same ref via ``copy.copy``.
+
+    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.
+    """
+    from fastmcp.server.context import Context, _current_context
+
+    stashed = rc_ref[0]
+    if stashed is None:
+        return
+
+    rc, fastmcp_ref = stashed
+    try:
+        current_rc = request_ctx.get()
+    except LookupError:
+        request_ctx.set(rc)
+        fastmcp = fastmcp_ref()
+        if fastmcp is not None:
+            _current_context.set(Context(fastmcp))
+        return
+    if current_rc.session is rc.session and current_rc.request_id != rc.request_id:
+        request_ctx.set(rc)
+        fastmcp = fastmcp_ref()
+        if fastmcp is not None:
+            _current_context.set(Context(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.
+    """
+
+    def __init__(
+        self,
+        transport: ClientTransportT
+        | FastMCP[Any]
+        | FastMCP1Server
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str,
+        **kwargs,
+    ):
+        if "name" not in kwargs:
+            kwargs["name"] = self.generate_name()
+        if "roots" not in kwargs:
+            kwargs["roots"] = default_proxy_roots_handler
+        if "sampling_handler" not in kwargs:
+            kwargs["sampling_handler"] = default_proxy_sampling_handler
+        if "elicitation_handler" not in kwargs:
+            kwargs["elicitation_handler"] = default_proxy_elicitation_handler
+        if "log_handler" not in kwargs:
+            kwargs["log_handler"] = default_proxy_log_handler
+        if "progress_handler" not in kwargs:
+            kwargs["progress_handler"] = default_proxy_progress_handler
+        super().__init__(**kwargs | {"transport": transport})
+
+
+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.
+
+    Because session reuse means the receive-loop task inherits a stale
+    ``request_ctx`` ContextVar snapshot, the default proxy handlers are
+    replaced with versions that restore the ContextVar before forwarding.
+    ``ProxyTool.run`` stashes the current ``RequestContext`` in
+    ``_proxy_rc_ref`` before each backend call, and the handlers consult
+    it to detect (and correct) staleness.
+    """
+
+    # Mutable list shared across copies (Client.new() uses copy.copy,
+    # which preserves references to mutable containers).  ProxyTool.run
+    # writes [0] before each backend call; handlers read it to detect
+    # stale ContextVars and restore the correct request_ctx.
+    #
+    # 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.  The restore helper
+    # constructs a fresh Context from the weakref after setting request_ctx.
+    _proxy_rc_ref: list[Any]
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        # Install context-restoring handler wrappers BEFORE super().__init__
+        # registers them with the Client's session kwargs.
+        self._proxy_rc_ref = [None]
+        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)
+
+        super().__init__(*args, **kwargs)
+        self._caches: dict[ServerSession, Client[ClientTransportT]] = {}
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:  # type: ignore[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
+        proxy_client = self._caches.get(session, None)
+
+        if proxy_client is None:
+            proxy_client = self.new()
+            logger.debug(f"{proxy_client} created for {session}")
+            self._caches[session] = proxy_client
+
+            async def _on_session_exit():
+                self._caches.pop(session)
+                logger.debug(f"{proxy_client} will be disconnect")
+                await proxy_client._disconnect(force=True)
+
+            session._exit_stack.push_async_callback(_on_session_exit)
+
+        return proxy_client
diff --git a/src/fastmcp/server/providers/skills/__init__.py b/src/fastmcp/server/providers/skills/__init__.py
new file mode 100644
index 000000000..b15c1c636
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/skills/_common.py b/src/fastmcp/server/providers/skills/_common.py
new file mode 100644
index 000000000..d0e1177a5
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/skills/claude_provider.py b/src/fastmcp/server/providers/skills/claude_provider.py
new file mode 100644
index 000000000..b7264953c
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/skills/directory_provider.py b/src/fastmcp/server/providers/skills/directory_provider.py
new file mode 100644
index 000000000..27f7c1e4c
--- /dev/null
+++ b/src/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.resource 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/src/fastmcp/server/providers/skills/skill_provider.py b/src/fastmcp/server/providers/skills/skill_provider.py
new file mode 100644
index 000000000..86bcba5e3
--- /dev/null
+++ b/src/fastmcp/server/providers/skills/skill_provider.py
@@ -0,0 +1,449 @@
+"""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 pydantic import AnyUrl
+
+from fastmcp.resources.resource 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()
+
+    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", "")
+        full_path = self.skill_info.path / file_path
+
+        # Security: ensure path doesn't escape skill directory
+        try:
+            full_path = full_path.resolve()
+            if not full_path.is_relative_to(self.skill_info.path):
+                raise ValueError(f"Path {file_path} escapes skill directory")
+        except ValueError 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()
+        else:
+            return full_path.read_bytes()
+
+    async def _read(  # type: ignore[override]
+        self,
+        uri: str,
+        params: dict[str, Any],
+        task_meta: Any = None,
+    ) -> ResourceResult:
+        """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", "")
+        full_path = (self.skill_info.path / file_path).resolve()
+
+        # Security: ensure path doesn't escape skill directory
+        if not full_path.is_relative_to(self.skill_info.path):
+            raise ValueError(f"Path {file_path} escapes skill directory")
+
+        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."""
+        full_path = self.skill_info.path / self.file_path
+
+        # Security check
+        full_path = full_path.resolve()
+        if not full_path.is_relative_to(self.skill_info.path):
+            raise ValueError(f"Path {self.file_path} escapes skill directory")
+
+        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()
+        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()
+        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/src/fastmcp/server/providers/skills/vendor_providers.py b/src/fastmcp/server/providers/skills/vendor_providers.py
new file mode 100644
index 000000000..df870f161
--- /dev/null
+++ b/src/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/src/fastmcp/server/providers/wrapped_provider.py b/src/fastmcp/server/providers/wrapped_provider.py
new file mode 100644
index 000000000..4f5c0df92
--- /dev/null
+++ b/src/fastmcp/server/providers/wrapped_provider.py
@@ -0,0 +1,140 @@
+"""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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.transforms import Transform
+    from fastmcp.tools.tool 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 _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.prompt import Prompt
+        from fastmcp.resources.resource import Resource
+        from fastmcp.resources.template import ResourceTemplate
+        from fastmcp.tools.tool 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/src/fastmcp/server/proxy.py b/src/fastmcp/server/proxy.py
new file mode 100644
index 000000000..45190c0f8
--- /dev/null
+++ b/src/fastmcp/server/proxy.py
@@ -0,0 +1,41 @@
+"""Backwards compatibility - import from fastmcp.server.providers.proxy instead.
+
+This module re-exports all proxy-related classes from their new location
+at fastmcp.server.providers.proxy. Direct imports from this module are
+deprecated and will be removed in a future version.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+warnings.warn(
+    "fastmcp.server.proxy is deprecated. Use fastmcp.server.providers.proxy instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Re-export everything from the new location
+from fastmcp.server.providers.proxy import (  # noqa: E402
+    ClientFactoryT,
+    FastMCPProxy,
+    ProxyClient,
+    ProxyPrompt,
+    ProxyProvider,
+    ProxyResource,
+    ProxyTemplate,
+    ProxyTool,
+    StatefulProxyClient,
+)
+
+__all__ = [
+    "ClientFactoryT",
+    "FastMCPProxy",
+    "ProxyClient",
+    "ProxyPrompt",
+    "ProxyProvider",
+    "ProxyResource",
+    "ProxyTemplate",
+    "ProxyTool",
+    "StatefulProxyClient",
+]
diff --git a/src/fastmcp/server/sampling/__init__.py b/src/fastmcp/server/sampling/__init__.py
new file mode 100644
index 000000000..392326d35
--- /dev/null
+++ b/src/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/src/fastmcp/server/sampling/run.py b/src/fastmcp/server/sampling/run.py
new file mode 100644
index 000000000..4ea31f0b6
--- /dev/null
+++ b/src/fastmcp/server/sampling/run.py
@@ -0,0 +1,703 @@
+"""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 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.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")
+
+# Simplified tool choice type - just the mode string instead of the full MCP object
+ToolChoiceOption = Literal["auto", "required", "none"]
+
+
+@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.stopReason == "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) -> 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.
+
+    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
+    has_sampling = session.check_client_capability(
+        capability=ClientCapabilities(sampling=SamplingCapability())
+    )
+    has_tools_capability = 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(
+            systemPrompt=system_prompt,
+            messages=messages,
+            temperature=temperature,
+            maxTokens=max_tokens,
+            modelPreferences=_parse_model_preferences(model_preferences),
+            tools=sdk_tools,
+            toolChoice=tool_choice,
+        ),
+        context.request_context,
+    )
+
+    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",
+            stopReason="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",
+                toolUseId=tool_use.id,
+                content=[
+                    TextContent(
+                        type="text",
+                        text=f"Error: Unknown tool '{tool_use.name}'",
+                    )
+                ],
+                isError=True,
+            )
+
+        try:
+            result_value = await tool.run(tool_use.input)
+            return ToolResultContent(
+                type="tool_result",
+                toolUseId=tool_use.id,
+                content=[TextContent(type="text", text=str(result_value))],
+            )
+        except ToolError as e:
+            # ToolError is the escape hatch - always pass message through
+            logger.exception(f"Error calling sampling tool '{tool_use.name}'")
+            return ToolResultContent(
+                type="tool_result",
+                toolUseId=tool_use.id,
+                content=[TextContent(type="text", text=str(e))],
+                isError=True,
+            )
+        except Exception as e:
+            # Generic exceptions - mask based on setting
+            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",
+                toolUseId=tool_use.id,
+                content=[TextContent(type="text", text=error_text)],
+                isError=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,
+) -> 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.
+    """
+    # 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))
+
+    # 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
+    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:
+        response = await context.session.create_message(
+            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.request_id,
+        )
+
+    # Check if this is a tool use response
+    is_tool_use_response = (
+        isinstance(response, CreateMessageResultWithTools)
+        and response.stopReason == "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,
+) -> 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.
+    """
+    # 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
+
+    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,
+        )
+
+        # Check for final_response tool call for structured output
+        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":
+                    # 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:
+                        # Validation failed - add error as tool result
+                        step.history.append(
+                            SamplingMessage(
+                                role="user",
+                                content=[
+                                    ToolResultContent(
+                                        type="tool_result",
+                                        toolUseId=tool_call.id,
+                                        content=[
+                                            TextContent(
+                                                type="text",
+                                                text=(
+                                                    f"Validation error: {e}. "
+                                                    "Please try again with valid data."
+                                                ),
+                                            )
+                                        ],
+                                        isError=True,
+                                    )
+                                ],
+                            )
+                        )
+
+        # 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:
+                raise RuntimeError(
+                    f"Expected structured output of type {result_type.__name__}, "
+                    "but the LLM returned a text response instead of calling "
+                    "the final_response tool."
+                )
+            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/src/fastmcp/server/sampling/sampling_tool.py b/src/fastmcp/server/sampling/sampling_tool.py
new file mode 100644
index 000000000..1781eb651
--- /dev/null
+++ b/src/fastmcp/server/sampling/sampling_tool.py
@@ -0,0 +1,183 @@
+"""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.tools.function_parsing import ParsedFunction
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool import ToolResult
+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,
+            inputSchema=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 or 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:
+            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/src/fastmcp/server/server.py b/src/fastmcp/server/server.py
new file mode 100644
index 000000000..92e7afe36
--- /dev/null
+++ b/src/fastmcp/server/server.py
@@ -0,0 +1,2245 @@
+"""FastMCP - A more ergonomic interface for MCP servers."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import secrets
+import warnings
+from collections.abc import (
+    AsyncIterator,
+    Awaitable,
+    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,
+    AnyFunction,
+    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.exceptions import (
+    AuthorizationError,
+    FastMCPError,
+    NotFoundError,
+    PromptError,
+    ResourceError,
+    ToolError,
+    ValidationError,
+)
+from fastmcp.mcp_config import MCPConfig
+from fastmcp.prompts import Prompt
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.prompts.prompt import PromptResult
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.apps import (
+    AppConfig,
+    app_config_to_meta_dict,
+    resolve_ui_mime_type,
+)
+from fastmcp.server.auth import AuthCheck, AuthContext, AuthProvider, run_auth_checks
+from fastmcp.server.lifespan import Lifespan
+from fastmcp.server.low_level import LowLevelServer
+from fastmcp.server.middleware import 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.function_tool import FunctionTool
+from fastmcp.tools.tool import Tool, ToolResult
+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 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 FastMCP1Server
+    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__)
+
+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"]
+
+# Compiled URI parsing regex to split a URI into protocol and path components
+URI_PATTERN = re.compile(r"^([^:]+://)(.*?)$")
+
+
+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())
+
+
+@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]:
+        if fastmcp_server._lifespan is default_lifespan:
+            yield {}
+            return
+
+        if not fastmcp_server._lifespan_result_set:
+            raise RuntimeError(
+                "FastMCP server has a lifespan defined but no lifespan result is set, which means the server's context manager was not entered. "
+                + " Are you running the server in a way that supports lifespans? If so, please file an issue at https://github.com/PrefectHQ/fastmcp/issues."
+            )
+
+        yield fastmcp_server._lifespan_result
+
+    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,
+        tasks: bool | None = None,
+        session_state_store: AsyncKeyValue | None = None,
+        sampling_handler: SamplingHandler | None = None,
+        sampling_handler_behavior: Literal["always", "fallback"] | 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
+
+        # 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
+        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, Any] = 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),
+        )
+
+        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.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: Callable[[MiddlewareContext[Any]], Awaitable[Any]],
+    ) -> Any:
+        """Builds and executes the middleware chain."""
+        chain = call_next
+        for mw in reversed(self.middleware):
+            chain = partial(mw, call_next=chain)
+        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)
+
+    # -------------------------------------------------------------------------
+    # 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)
+
+    def add_tool_transformation(
+        self, tool_name: str, transformation: ToolTransformConfig
+    ) -> None:
+        """Add a tool transformation.
+
+        .. deprecated::
+            Use ``add_transform(ToolTransform({...}))`` instead.
+        """
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "add_tool_transformation is deprecated. Use "
+                "server.add_transform(ToolTransform({tool_name: config})) instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        self.add_transform(ToolTransform({tool_name: transformation}))
+
+    def remove_tool_transformation(self, _tool_name: str) -> None:
+        """Remove a tool transformation.
+
+        .. deprecated::
+            Tool transformations are now immutable. Use enable/disable controls instead.
+        """
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "remove_tool_transformation is deprecated and has no effect. "
+                "Transforms are immutable once added. Use server.disable(keys=[...]) "
+                "to hide tools instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+    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),
+                )
+
+            # Get all tools, apply session transforms, then filter enabled
+            tools = list(await super().list_tools())
+            tools = await apply_session_transforms(tools)
+            tools = [t for t in tools if is_enabled(t)]
+
+            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]):
+            return tools[0]
+
+        # The highest version is disabled. If an explicit version was requested,
+        # respect the disable. Otherwise fall back to the next-highest enabled 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)]
+
+        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 cast(Tool, 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),
+                )
+
+            # 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)]
+
+            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 cast(Resource, 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
+                    ),
+                )
+
+            # 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 cast(ResourceTemplate, 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),
+                )
+
+            # 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 cast(Prompt, 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.
+
+        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 {}
+                    ),
+                    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 (providers queried in parallel)
+            # Use get_tool to apply transforms and filter disabled
+            with server_span(
+                f"tools/call {name}", "tools/call", self.name, "tool", name
+            ) as span:
+                tool = await self.get_tool(name, version=version)
+                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 FastMCPError:
+                    logger.exception(f"Error calling tool {name!r}")
+                    raise
+                except (ValidationError, PydanticValidationError):
+                    logger.exception(f"Error validating tool {name!r}")
+                    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:
+                uri_param = AnyUrl(uri)
+                mw_context = MiddlewareContext(
+                    message=mcp.types.ReadResourceRequestParams(uri=uri_param),
+                    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(
+                f"resources/read {uri}",
+                "resources/read",
+                self.name,
+                "resource",
+                uri,
+                resource_uri=uri,
+            ) as span:
+                # 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, 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, 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
+                    ),
+                    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
+            ) 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, 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)
+
+    def remove_tool(self, name: str, version: str | None = None) -> None:
+        """Remove tool(s) from the server.
+
+        .. deprecated::
+            Use ``mcp.local_provider.remove_tool(name)`` instead.
+
+        Args:
+            name: The name of the tool to remove.
+            version: If None, removes ALL versions. If specified, removes only that version.
+
+        Raises:
+            NotFoundError: If no matching tool is found.
+        """
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "remove_tool() is deprecated. Use "
+                "mcp.local_provider.remove_tool(name) instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        try:
+            self._local_provider.remove_tool(name, version)
+        except KeyError:
+            if version is None:
+                raise NotFoundError(f"Tool {name!r} not found") from None
+            raise NotFoundError(
+                f"Tool {name!r} version {version!r} not found"
+            ) from None
+
+    @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,
+        exclude_args: list[str] | 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,
+    ) -> 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,
+        exclude_args: list[str] | 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,
+    ) -> 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,
+        exclude_args: list[str] | 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,
+    ) -> (
+        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
+            exclude_args: Optional list of argument names to exclude from the tool schema.
+                Deprecated: Use `Depends()` for dependency injection instead.
+            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,
+            exclude_args=exclude_args,
+            meta=meta,
+            task=task if task is not None else self._support_tasks_by_default,
+            timeout=timeout,
+            auth=auth,
+        )
+
+        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,
+        as_proxy: bool | None = None,
+        tool_names: dict[str, str] | None = None,
+        prefix: str | None = None,  # deprecated, use namespace
+    ) -> None:
+        """Mount another FastMCP server on this server with an optional namespace.
+
+        Unlike importing (with import_server), 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.
+            as_proxy: Deprecated. Mounted servers now always have their lifespan and
+                middleware invoked. To create a proxy server, use create_proxy()
+                explicitly before mounting.
+            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.
+            prefix: Deprecated. Use namespace instead.
+        """
+        import warnings
+
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+
+        # Handle deprecated prefix parameter
+        if prefix is not None:
+            warnings.warn(
+                "The 'prefix' parameter is deprecated, use 'namespace' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if namespace is None:
+                namespace = prefix
+            else:
+                raise ValueError("Cannot specify both 'prefix' and 'namespace'")
+
+        if as_proxy is not None:
+            warnings.warn(
+                "as_proxy is deprecated and will be removed in a future version. "
+                "Mounted servers now always have their lifespan and middleware invoked. "
+                "To create a proxy server, use create_proxy() explicitly.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            # Still honor the flag for backward compatibility
+            if as_proxy:
+                from fastmcp.server.providers.proxy import FastMCPProxy
+
+                if not isinstance(server, FastMCPProxy):
+                    server = FastMCP.as_proxy(server)
+
+        # 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 "")
+
+    async def import_server(
+        self,
+        server: FastMCP[LifespanResultT],
+        prefix: str | None = None,
+    ) -> None:
+        """
+        Import the MCP objects from another FastMCP server into this one,
+        optionally with a given prefix.
+
+        .. deprecated::
+            Use :meth:`mount` instead. ``import_server`` will be removed in a
+            future version.
+
+        Note that when a server is *imported*, its objects are immediately
+        registered to the importing server. This is a one-time operation and
+        future changes to the imported server will not be reflected in the
+        importing server. Server-level configurations and lifespans are not imported.
+
+        When a server is imported with a prefix:
+        - The tools are imported with prefixed names
+          Example: If server has a tool named "get_weather", it will be
+          available as "prefix_get_weather"
+        - The resources are imported with prefixed URIs using the new format
+          Example: If server has a resource with URI "weather://forecast", it will
+          be available as "weather://prefix/forecast"
+        - The templates are imported with prefixed URI templates using the new format
+          Example: If server has a template with URI "weather://location/{id}", it will
+          be available as "weather://prefix/location/{id}"
+        - The prompts are imported with prefixed names
+          Example: If server has a prompt named "weather_prompt", it will be available as
+          "prefix_weather_prompt"
+
+        When a server is imported without a prefix (prefix=None), its tools, resources,
+        templates, and prompts are imported with their original names.
+
+        Args:
+            server: The FastMCP server to import
+            prefix: Optional prefix to use for the imported server's objects. If None,
+                objects are imported with their original names.
+        """
+        import warnings
+
+        warnings.warn(
+            "import_server is deprecated, use mount() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        def add_resource_prefix(uri: str, prefix: str) -> str:
+            """Add prefix to resource URI: protocol://path → protocol://prefix/path."""
+            match = URI_PATTERN.match(uri)
+            if match:
+                protocol, path = match.groups()
+                return f"{protocol}{prefix}/{path}"
+            return uri
+
+        # Import tools from the server
+        for tool in await server.list_tools():
+            if prefix:
+                tool = tool.model_copy(update={"name": f"{prefix}_{tool.name}"})
+            self.add_tool(tool)
+
+        # Import resources and templates from the server
+        for resource in await server.list_resources():
+            if prefix:
+                new_uri = add_resource_prefix(str(resource.uri), prefix)
+                resource = resource.model_copy(update={"uri": new_uri})
+            self.add_resource(resource)
+
+        for template in await server.list_resource_templates():
+            if prefix:
+                new_uri_template = add_resource_prefix(template.uri_template, prefix)
+                template = template.model_copy(
+                    update={"uri_template": new_uri_template}
+                )
+            self.add_template(template)
+
+        # Import prompts from the server
+        for prompt in await server.list_prompts():
+            if prefix:
+                prompt = prompt.model_copy(update={"name": f"{prefix}_{prompt.name}"})
+            self.add_prompt(prompt)
+
+        if server._lifespan != default_lifespan:
+            from warnings import warn
+
+            warn(
+                message="When importing from a server with a lifespan, the lifespan from the imported server will not be used.",
+                category=RuntimeWarning,
+                stacklevel=2,
+            )
+
+        if prefix:
+            logger.debug(
+                f"[{self.name}] Imported server {server.name} with prefix '{prefix}'"
+            )
+        else:
+            logger.debug(f"[{self.name}] Imported server {server.name}")
+
+    @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 as_proxy(
+        cls,
+        backend: (
+            Client[ClientTransportT]
+            | ClientTransport
+            | FastMCP[Any]
+            | FastMCP1Server
+            | AnyUrl
+            | Path
+            | MCPConfig
+            | dict[str, Any]
+            | str
+        ),
+        **settings: Any,
+    ) -> FastMCPProxy:
+        """Create a FastMCP proxy server for the given backend.
+
+        .. deprecated::
+            Use :func:`fastmcp.server.create_proxy` instead.
+            This method will be removed in a future version.
+
+        The `backend` argument can be either an existing `fastmcp.client.Client`
+        instance or any value accepted as the `transport` argument of
+        `fastmcp.client.Client`. This mirrors the convenience of the
+        `fastmcp.client.Client` constructor.
+        """
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "FastMCP.as_proxy() is deprecated. Use create_proxy() from "
+                "fastmcp.server instead: `from fastmcp.server import create_proxy`",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        # Call the module-level create_proxy function directly
+        return create_proxy(backend, **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]
+        | FastMCP1Server
+        | 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/src/fastmcp/server/tasks/__init__.py b/src/fastmcp/server/tasks/__init__.py
new file mode 100644
index 000000000..008332db5
--- /dev/null
+++ b/src/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/src/fastmcp/server/tasks/capabilities.py b/src/fastmcp/server/tasks/capabilities.py
new file mode 100644
index 000000000..9f7d4b4f9
--- /dev/null
+++ b/src/fastmcp/server/tasks/capabilities.py
@@ -0,0 +1,42 @@
+"""SEP-1686 task capabilities declaration."""
+
+from importlib.util import find_spec
+
+from mcp.types import (
+    ServerTasksCapability,
+    ServerTasksRequestsCapability,
+    TasksCallCapability,
+    TasksCancelCapability,
+    TasksListCapability,
+    TasksToolsCapability,
+)
+
+
+def _is_docket_available() -> bool:
+    """Check if pydocket is installed (local to avoid circular import)."""
+    return find_spec("docket") is not None
+
+
+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 pydocket is not installed (no task support).
+
+    Note: prompts/resources are passed via extra_data since the SDK types
+    don't include them yet (FastMCP supports them ahead of the spec).
+    """
+    if not _is_docket_available():
+        return None
+
+    return ServerTasksCapability(
+        list=TasksListCapability(),
+        cancel=TasksCancelCapability(),
+        requests=ServerTasksRequestsCapability(
+            tools=TasksToolsCapability(call=TasksCallCapability()),
+            prompts={"get": {}},  # type: ignore[call-arg]  # extra_data for forward compat
+            resources={"read": {}},  # type: ignore[call-arg]  # extra_data for forward compat
+        ),
+    )
diff --git a/src/fastmcp/server/tasks/config.py b/src/fastmcp/server/tasks/config.py
new file mode 100644
index 000000000..1d5befa2a
--- /dev/null
+++ b/src/fastmcp/server/tasks/config.py
@@ -0,0 +1,147 @@
+"""TaskConfig for MCP SEP-1686 background task execution modes.
+
+This module defines the configuration for how tools, resources, and prompts
+handle task-augmented execution as specified in SEP-1686.
+"""
+
+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
+
+# Task execution modes per SEP-1686 / MCP ToolExecution.taskSupport
+TaskMode = Literal["forbidden", "optional", "required"]
+
+# Default values for task metadata (single source of truth)
+DEFAULT_POLL_INTERVAL = timedelta(seconds=5)  # Default poll interval
+DEFAULT_POLL_INTERVAL_MS = int(DEFAULT_POLL_INTERVAL.total_seconds() * 1000)
+DEFAULT_TTL_MS = 60_000  # Default TTL in milliseconds
+
+
+@dataclass
+class TaskMeta:
+    """Metadata for task-augmented execution requests.
+
+    When passed to call_tool/read_resource/get_prompt, signals that
+    the operation should be submitted as a background task.
+
+    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 (SEP-1686).
+
+    Controls how a component handles task-augmented requests:
+
+    - "forbidden": Component does not support task execution. Clients must not
+      request task augmentation; server returns -32601 if they do.
+    - "optional": Component supports both synchronous and task execution.
+      Client may request task augmentation or call normally.
+    - "required": Component requires task execution. Clients must request task
+      augmentation; server returns -32601 if they don't.
+
+    Important:
+        Task-enabled components must be available at server startup to be
+        registered with all Docket workers. Components added dynamically after
+        startup will not be registered for background execution.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.tasks import TaskConfig
+
+        mcp = FastMCP("MyServer")
+
+        # Background execution required
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def long_running_task(): ...
+
+        # Supports both modes (default when task=True)
+        @mcp.tool(task=TaskConfig(mode="optional"))
+        async def flexible_task(): ...
+        ```
+    """
+
+    mode: TaskMode = "optional"
+    poll_interval: timedelta = DEFAULT_POLL_INTERVAL
+
+    @classmethod
+    def from_bool(cls, value: bool) -> TaskConfig:
+        """Convert boolean task flag to TaskConfig.
+
+        Args:
+            value: True for "optional" mode, False for "forbidden" mode.
+
+        Returns:
+            TaskConfig with appropriate mode.
+        """
+        return cls(mode="optional" if value else "forbidden")
+
+    def supports_tasks(self) -> bool:
+        """Check if this component supports task execution.
+
+        Returns:
+            True if mode is "optional" or "required", False if "forbidden".
+        """
+        return self.mode != "forbidden"
+
+    def validate_function(self, fn: Callable[..., Any], name: str) -> None:
+        """Validate that function is compatible with this task config.
+
+        Task execution requires:
+        1. fastmcp[tasks] to be installed (pydocket)
+        2. Async functions
+
+        Raises ImportError if mode is "optional" or "required" but pydocket
+        is not installed. Raises ValueError if function is synchronous.
+
+        Args:
+            fn: The function to validate (handles callable classes and staticmethods).
+            name: Name for error messages.
+
+        Raises:
+            ImportError: If task execution is enabled but pydocket not installed.
+            ValueError: If task execution is enabled but function is sync.
+        """
+        if not self.supports_tasks():
+            return
+
+        # Check that docket is available for task execution
+        # Lazy import to avoid circular: dependencies.py → http.py → tasks/__init__.py → config.py
+        from fastmcp.server.dependencies import require_docket
+
+        require_docket(f"`task=True` on function '{name}'")
+
+        # Unwrap callable classes and staticmethods
+        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."
+            )
+
+        # Note: Context IS now available in background task workers (SEP-1686)
+        # The wiring in _CurrentContext creates a task-aware Context with task_id
+        # and session from the registry. No warning needed.
diff --git a/src/fastmcp/server/tasks/elicitation.py b/src/fastmcp/server/tasks/elicitation.py
new file mode 100644
index 000000000..cb148cfc7
--- /dev/null
+++ b/src/fastmcp/server/tasks/elicitation.py
@@ -0,0 +1,346 @@
+"""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, cast
+
+import mcp.types
+from mcp import ServerSession
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+# Redis key patterns for task elicitation state
+ELICIT_REQUEST_KEY = "fastmcp:task:{session_id}:{task_id}:elicit:request"
+ELICIT_RESPONSE_KEY = "fastmcp:task:{session_id}:{task_id}:elicit:response"
+ELICIT_STATUS_KEY = "fastmcp:task:{session_id}:{task_id}:elicit:status"
+
+# TTL for elicitation state (1 hour)
+ELICIT_TTL_SECONDS = 3600
+
+
+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())
+
+    # Get session ID from task context (authoritative source for background tasks)
+    # This is extracted from the Docket execution key: {session_id}:{task_id}:...
+    from fastmcp.server.dependencies import get_task_context
+
+    task_context = get_task_context()
+    if task_context is not None:
+        session_id = task_context.session_id
+    else:
+        # Fallback: try to get from session attribute (shouldn't happen in background)
+        session_id = getattr(session, "_fastmcp_state_prefix", None)
+        if session_id is None:
+            raise RuntimeError(
+                "Cannot determine session_id for elicitation. "
+                "This typically means elicit_for_task() was called outside a Docket worker context."
+            )
+
+    # Store elicitation request in Redis
+    request_key = ELICIT_REQUEST_KEY.format(session_id=session_id, task_id=task_id)
+    response_key = ELICIT_RESPONSE_KEY.format(session_id=session_id, task_id=task_id)
+    status_key = ELICIT_STATUS_KEY.format(session_id=session_id, task_id=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,
+                "elicitation": {
+                    "requestId": request_id,
+                    "message": message,
+                    "requestedSchema": schema,
+                },
+            }
+        },
+    }
+
+    # Push notification to Redis queue (works from any process)
+    # Server's subscriber loop will forward to client
+    from fastmcp.server.tasks.notifications import push_notification
+
+    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 cast(
+                Any,
+                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,
+    session_id: str,
+    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
+        session_id: Session identifier
+        task_id: Background task ID
+        elicitation: Elicitation metadata (message, requestedSchema)
+        fastmcp: FastMCP server instance
+    """
+    try:
+        result = await session.elicit(
+            message=elicitation["message"],
+            requestedSchema=elicitation["requestedSchema"],
+        )
+        await handle_task_input(
+            task_id=task_id,
+            session_id=session_id,
+            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,
+            session_id=session_id,
+            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,
+    session_id: str,
+    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
+        session_id: The MCP session ID
+        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 = ELICIT_RESPONSE_KEY.format(session_id=session_id, task_id=task_id)
+    status_key = ELICIT_STATUS_KEY.format(session_id=session_id, task_id=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(  # type: ignore[invalid-await]  # redis-py union type (sync/async)
+            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/src/fastmcp/server/tasks/handlers.py b/src/fastmcp/server/tasks/handlers.py
new file mode 100644
index 000000000..10bf18b6d
--- /dev/null
+++ b/src/fastmcp/server/tasks/handlers.py
@@ -0,0 +1,225 @@
+"""SEP-1686 task execution handlers.
+
+Handles queuing tool/prompt/resource executions to Docket as background tasks.
+"""
+
+from __future__ import annotations
+
+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, ErrorData
+
+from fastmcp.server.dependencies import _current_docket, get_access_token, get_context
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.tasks.keys import build_task_key
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool 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
+    """
+    # 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)
+    created_at = datetime.now(timezone.utc)
+
+    # Get session ID - use "internal" for programmatic calls without MCP session
+    ctx = get_context()
+    try:
+        session_id = ctx.session_id
+    except RuntimeError:
+        session_id = "internal"
+
+    docket = _current_docket.get()
+    if docket is None:
+        raise McpError(
+            ErrorData(
+                code=INTERNAL_ERROR,
+                message="Background tasks require a running FastMCP server context",
+            )
+        )
+
+    # Build full task key with embedded metadata
+    task_key = build_task_key(session_id, 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
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
+    poll_interval_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:poll_interval"
+    )
+    origin_request_id_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:origin_request_id"
+    )
+    poll_interval_ms = int(component.task_config.poll_interval.total_seconds() * 1000)
+    origin_request_id = (
+        str(ctx.request_context.request_id) if ctx.request_context is not None else None
+    )
+
+    # Snapshot the current access token (if any) for background task access (#3095)
+    access_token = get_access_token()
+    access_token_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:access_token"
+    )
+
+    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)
+        if origin_request_id is not None:
+            await redis.set(origin_request_id_key, origin_request_id, ex=ttl_seconds)
+        if access_token is not None:
+            await redis.set(
+                access_token_key, access_token.model_dump_json(), ex=ttl_seconds
+            )
+
+    # Register session for Context access in background workers (SEP-1686)
+    # This enables elicitation/sampling from background tasks via weakref
+    # Skip for "internal" sessions (programmatic calls without MCP session)
+    if session_id != "internal":
+        from fastmcp.server.dependencies import register_task_session
+
+        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,
+                "lastUpdatedAt": created_at,
+                "ttl": ttl_ms,
+                "pollInterval": poll_interval_ms,
+            },
+            "_meta": {
+                "io.modelcontextprotocol/related-task": {
+                    "taskId": server_task_id,
+                }
+            },
+        }
+    )
+    server_notification = mcp.types.ServerNotification(notification)
+    with suppress(Exception):
+        # Don't let notification failures break task creation
+        await ctx.session.send_notification(server_notification)
+
+    # 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:{session}:{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]
+    else:
+        await component.add_to_docket(docket, arguments, fn_key=key, task_key=task_key)  # type: ignore[call-arg]
+
+    # Spawn subscription task to send status notifications (SEP-1686 optional feature)
+    from fastmcp.server.tasks.subscriptions import subscribe_to_task_updates
+
+    # Start subscription in session's task group (persists for connection lifetime)
+    if hasattr(ctx.session, "_subscription_task_group"):
+        tg = ctx.session._subscription_task_group
+        if tg:
+            tg.start_soon(  # type: ignore[union-attr]
+                subscribe_to_task_updates,
+                server_task_id,
+                task_key,
+                ctx.session,
+                docket,
+                poll_interval_ms,
+            )
+
+    # Start notification subscriber for distributed elicitation (idempotent)
+    # This enables ctx.elicit() to work when workers run in separate processes
+    # Subscriber forwards notifications from Redis queue to client session
+    from fastmcp.server.tasks.notifications import (
+        ensure_subscriber_running,
+        stop_subscriber,
+    )
+
+    try:
+        await ensure_subscriber_running(session_id, ctx.session, docket, ctx.fastmcp)
+
+        # Register cleanup callback on session exit (once per session)
+        # This ensures subscriber is stopped when the session disconnects
+        if (
+            hasattr(ctx.session, "_exit_stack")
+            and ctx.session._exit_stack is not None
+            and not getattr(ctx.session, "_notification_cleanup_registered", False)
+        ):
+
+            async def _cleanup_subscriber() -> None:
+                await stop_subscriber(session_id)
+
+            ctx.session._exit_stack.push_async_callback(_cleanup_subscriber)
+            ctx.session._notification_cleanup_registered = True  # type: ignore[attr-defined]
+    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(
+            taskId=server_task_id,
+            status="working",
+            createdAt=created_at,
+            lastUpdatedAt=created_at,
+            ttl=ttl_ms,
+            pollInterval=poll_interval_ms,
+        )
+    )
diff --git a/src/fastmcp/server/tasks/keys.py b/src/fastmcp/server/tasks/keys.py
new file mode 100644
index 000000000..0e28cf592
--- /dev/null
+++ b/src/fastmcp/server/tasks/keys.py
@@ -0,0 +1,91 @@
+"""Task key management for SEP-1686 background tasks.
+
+Task keys encode security scoping and metadata in the Docket key format:
+    `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
+
+This format provides:
+- Session-based security scoping (prevents cross-session access)
+- Task type identification (tool/prompt/resource)
+- Component identification (name or URI for result conversion)
+"""
+
+from urllib.parse import quote, unquote
+
+
+def build_task_key(
+    session_id: str,
+    client_task_id: str,
+    task_type: str,
+    component_identifier: str,
+) -> str:
+    """Build Docket task key with embedded metadata.
+
+    Format: `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
+
+    The component_identifier is URI-encoded to handle special characters (colons, slashes, etc.).
+
+    Args:
+        session_id: Session ID for security scoping
+        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("session123", "task456", "tool", "my_tool")
+        'session123:task456:tool:my_tool'
+
+        >>> build_task_key("session123", "task456", "resource", "file://data.txt")
+        'session123:task456:resource:file%3A%2F%2Fdata.txt'
+    """
+    encoded_identifier = quote(component_identifier, safe="")
+    return f"{session_id}:{client_task_id}:{task_type}:{encoded_identifier}"
+
+
+def parse_task_key(task_key: str) -> dict[str, str]:
+    """Parse Docket task key to extract metadata.
+
+    Args:
+        task_key: Encoded task key from Docket
+
+    Returns:
+        Dict with keys: session_id, client_task_id, task_type, component_identifier
+
+    Examples:
+        >>> parse_task_key("session123:task456:tool:my_tool")
+        `{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
+
+        >>> parse_task_key("session123:task456:resource:file%3A%2F%2Fdata.txt")
+        `{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'resource', 'component_identifier': 'file://data.txt'}`
+    """
+    parts = task_key.split(":", 3)
+    if len(parts) != 4:
+        raise ValueError(
+            f"Invalid task key format: {task_key}. "
+            f"Expected: {{session_id}}:{{client_task_id}}:{{task_type}}:{{component_identifier}}"
+        )
+
+    return {
+        "session_id": parts[0],
+        "client_task_id": parts[1],
+        "task_type": parts[2],
+        "component_identifier": unquote(parts[3]),
+    }
+
+
+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 (second segment)
+
+    Example:
+        >>> get_client_task_id_from_key("session123:task456:tool:my_tool")
+        'task456'
+    """
+    return task_key.split(":", 3)[1]
diff --git a/src/fastmcp/server/tasks/notifications.py b/src/fastmcp/server/tasks/notifications.py
new file mode 100644
index 000000000..67417bd62
--- /dev/null
+++ b/src/fastmcp/server/tasks/notifications.py
@@ -0,0 +1,300 @@
+"""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, cast
+
+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)  # type: ignore[invalid-await]  # redis-py union type (sync/async)
+        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 cast(
+                    Any, 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))  # type: ignore[invalid-await]
+                        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}")
+
+    notification = mcp.types.TaskStatusNotification.model_validate(
+        {
+            "method": "notifications/tasks/status",
+            "params": notification_dict.get("params", {}),
+            "_meta": notification_dict.get("_meta"),
+        }
+    )
+    server_notification = mcp.types.ServerNotification(notification)
+
+    await session.send_notification(server_notification)
+
+    # 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
+            from fastmcp.server.tasks.elicitation import relay_elicitation
+
+            task = asyncio.create_task(
+                relay_elicitation(session, session_id, 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/src/fastmcp/server/tasks/requests.py b/src/fastmcp/server/tasks/requests.py
new file mode 100644
index 000000000..fae63c08d
--- /dev/null
+++ b/src/fastmcp/server/tasks/requests.py
@@ -0,0 +1,474 @@
+"""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,
+    ErrorData,
+    GetTaskResult,
+    ListTasksResult,
+)
+
+import fastmcp.server.context
+from fastmcp.exceptions import NotFoundError
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource 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.keys import parse_task_key
+from fastmcp.tools.tool 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 _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,
+    session_id: str,
+    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
+        session_id: Session ID
+        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
+    """
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+    )
+    poll_interval_key = docket.key(
+        f"fastmcp:task:{session_id}:{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(
+            ErrorData(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(
+            ErrorData(
+                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) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        # Get Docket instance
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    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, session_id, 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]
+
+        # 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
+        # Parse ISO string to datetime, or use current time as fallback
+        if created_at:
+            try:
+                created_at_dt = datetime.fromisoformat(
+                    created_at.replace("Z", "+00:00")
+                )
+            except (ValueError, AttributeError):
+                created_at_dt = datetime.now(timezone.utc)
+        else:
+            created_at_dt = datetime.now(timezone.utc)
+
+        return GetTaskResult(
+            taskId=client_task_id,
+            status=mcp_state,
+            createdAt=created_at_dt,
+            lastUpdatedAt=datetime.now(timezone.utc),
+            ttl=DEFAULT_TTL_MS,
+            pollInterval=poll_interval_ms,
+            statusMessage=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) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        # Get execution from Docket (use instance attribute for cross-task access)
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    code=INTERNAL_ERROR,
+                    message="Background tasks require Docket",
+                )
+            )
+
+        # Look up full task key from Redis
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{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(
+                ErrorData(
+                    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(
+                ErrorData(
+                    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(
+                ErrorData(
+                    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))],
+                isError=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(
+                ErrorData(
+                    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
+        if isinstance(component, Tool):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result()
+            # Ensure we have a CallToolResult and add metadata
+            if isinstance(mcp_result, mcp.types.CallToolResult):
+                mcp_result._meta = related_task_meta  # type: ignore[attr-defined]
+            elif isinstance(mcp_result, tuple):
+                content, structured_content = mcp_result
+                mcp_result = mcp.types.CallToolResult(
+                    content=content,
+                    structuredContent=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()
+            mcp_result._meta = related_task_meta  # type: ignore[attr-defined]
+            return mcp_result
+
+        elif isinstance(component, ResourceTemplate):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result(component.uri_template)
+            mcp_result._meta = related_task_meta  # type: ignore[attr-defined]
+            return mcp_result
+
+        elif isinstance(component, Resource):
+            fastmcp_result = component.convert_result(raw_value)
+            mcp_result = fastmcp_result.to_mcp_result(str(component.uri))
+            mcp_result._meta = related_task_meta  # type: ignore[attr-defined]
+            return mcp_result
+
+        else:
+            raise McpError(
+                ErrorData(
+                    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=[], nextCursor=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) as ctx:
+        client_task_id = params.get("taskId")
+        if not client_task_id:
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
+                )
+            )
+
+        # Get session ID from Context
+        session_id = ctx.session_id
+
+        # Get Docket instance
+        docket = server._docket
+        if docket is None:
+            raise McpError(
+                ErrorData(
+                    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, session_id, 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(
+            taskId=client_task_id,
+            status="cancelled",
+            createdAt=datetime.fromisoformat(created_at)
+            if created_at
+            else datetime.now(timezone.utc),
+            lastUpdatedAt=datetime.now(timezone.utc),
+            ttl=DEFAULT_TTL_MS,
+            pollInterval=poll_interval_ms,
+            statusMessage="Task cancelled",
+        )
diff --git a/src/fastmcp/server/tasks/routing.py b/src/fastmcp/server/tasks/routing.py
new file mode 100644
index 000000000..ab9e240c8
--- /dev/null
+++ b/src/fastmcp/server/tasks/routing.py
@@ -0,0 +1,76 @@
+"""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, ErrorData
+
+from fastmcp.server.tasks.config import TaskMeta
+from fastmcp.server.tasks.handlers import submit_to_docket
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool 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(
+            ErrorData(
+                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(
+            ErrorData(
+                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/src/fastmcp/server/tasks/subscriptions.py b/src/fastmcp/server/tasks/subscriptions.py
new file mode 100644
index 000000000..9c6c8d59e
--- /dev/null
+++ b/src/fastmcp/server/tasks/subscriptions.py
@@ -0,0 +1,213 @@
+"""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
+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
+        async for event in execution.subscribe():
+            if event["type"] == "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=ExecutionState(event["state"]),
+                    poll_interval_ms=poll_interval_ms,
+                )
+            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 session_id from task_key for Redis lookup
+    key_parts = parse_task_key(task_key)
+    session_id = key_parts["session_id"]
+
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{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]
+
+
+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 session_id from task_key for Redis lookup
+    key_parts = parse_task_key(task_key)
+    session_id = key_parts["session_id"]
+
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{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]
diff --git a/src/fastmcp/server/telemetry.py b/src/fastmcp/server/telemetry.py
new file mode 100644
index 000000000..6c263225d
--- /dev/null
+++ b/src/fastmcp/server/telemetry.py
@@ -0,0 +1,131 @@
+"""Server-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from mcp.server.lowlevel.server import request_ctx
+from opentelemetry.context import Context
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from fastmcp.telemetry import extract_trace_context, get_tracer
+
+
+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."""
+    try:
+        req_ctx = request_ctx.get()
+        if req_ctx and hasattr(req_ctx, "meta") and req_ctx.meta:
+            return extract_trace_context(dict(req_ctx.meta))
+    except LookupError:
+        pass
+    return None
+
+
+@contextmanager
+def server_span(
+    name: str,
+    method: str,
+    server_name: str,
+    component_type: str,
+    component_key: str,
+    resource_uri: str | None = None,
+) -> Generator[Span, None, None]:
+    """Create a SERVER span with standard MCP attributes and auth context.
+
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(
+        name,
+        context=_get_parent_trace_context(),
+        kind=SpanKind.SERVER,
+    ) as span:
+        attrs: dict[str, str] = {
+            # RPC semantic conventions
+            "rpc.system": "mcp",
+            "rpc.service": server_name,
+            "rpc.method": method,
+            # 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
+        span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+@contextmanager
+def delegate_span(
+    name: str,
+    provider_type: str,
+    component_key: str,
+) -> 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:
+        span.set_attributes(
+            {
+                "fastmcp.provider.type": provider_type,
+                "fastmcp.component.key": component_key,
+            }
+        )
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+__all__ = [
+    "delegate_span",
+    "get_auth_span_attributes",
+    "get_session_span_attributes",
+    "server_span",
+]
diff --git a/src/fastmcp/server/transforms/__init__.py b/src/fastmcp/server/transforms/__init__.py
new file mode 100644
index 000000000..cdda16d82
--- /dev/null
+++ b/src/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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool 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/src/fastmcp/server/transforms/catalog.py b/src/fastmcp/server/transforms/catalog.py
new file mode 100644
index 000000000..748e12645
--- /dev/null
+++ b/src/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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.context import Context
+    from fastmcp.tools.tool 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/src/fastmcp/server/transforms/namespace.py b/src/fastmcp/server/transforms/namespace.py
new file mode 100644
index 000000000..152d493e5
--- /dev/null
+++ b/src/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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool 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/src/fastmcp/server/transforms/prompts_as_tools.py b/src/fastmcp/server/transforms/prompts_as_tools.py
new file mode 100644
index 000000000..83ef30815
--- /dev/null
+++ b/src/fastmcp/server/transforms/prompts_as_tools.py
@@ -0,0 +1,175 @@
+"""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.
+
+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.transforms import GetToolNext, Transform
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.base import Provider
+
+# Note: FastMCP imported inside tools to avoid circular import
+
+
+class PromptsAsTools(Transform):
+    """Transform that adds tools for listing and getting prompts.
+
+    Generates two tools:
+    - `list_prompts`: Lists all prompts from the provider
+    - `get_prompt`: Gets a specific prompt with optional arguments
+
+    The transform captures a provider reference at construction and queries it
+    for prompts when the generated tools are called. When used with FastMCP,
+    the provider's auth and visibility filtering is automatically applied.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(PromptsAsTools(mcp))
+        # Now has list_prompts and get_prompt tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        """Initialize the transform with a provider reference.
+
+        Args:
+            provider: The provider to query for prompts. Typically this is
+                the same FastMCP server the transform is added to.
+        """
+        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."""
+        # Check if it's one of our generated tools
+        if name == "list_prompts":
+            return self._make_list_prompts_tool()
+        if name == "get_prompt":
+            return self._make_get_prompt_tool()
+
+        # Otherwise delegate to downstream
+        return await call_next(name, version=version)
+
+    def _make_list_prompts_tool(self) -> Tool:
+        """Create the list_prompts tool."""
+        provider = self._provider
+
+        async def list_prompts() -> str:
+            """List all available prompts.
+
+            Returns JSON with prompt metadata including name, description,
+            and optional arguments.
+            """
+            prompts = await provider.list_prompts()
+
+            result: list[dict[str, Any]] = []
+            for p in prompts:
+                result.append(
+                    {
+                        "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."""
+        provider = self._provider
+
+        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.
+            """
+            from fastmcp.server.server import FastMCP
+
+            # Use FastMCP.render_prompt() if available - runs middleware chain
+            if isinstance(provider, FastMCP):
+                result = await provider.render_prompt(name, arguments=arguments or {})
+                return _format_prompt_result(result)
+
+            # Fallback for plain providers - no middleware
+            prompt = await provider.get_prompt(name)
+            if prompt is None:
+                raise ValueError(f"Prompt not found: {name}")
+
+            result = await prompt._render(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:
+            # Preserve structured content (e.g., EmbeddedResource) as dict
+            content = msg.content.model_dump(mode="json", exclude_none=True)
+
+        messages.append(
+            {
+                "role": msg.role,
+                "content": content,
+            }
+        )
+
+    return json.dumps({"messages": messages}, indent=2)
diff --git a/src/fastmcp/server/transforms/resources_as_tools.py b/src/fastmcp/server/transforms/resources_as_tools.py
new file mode 100644
index 000000000..00fc43822
--- /dev/null
+++ b/src/fastmcp/server/transforms/resources_as_tools.py
@@ -0,0 +1,190 @@
+"""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.
+
+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 fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+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 from the provider
+    - `read_resource`: Reads a resource by URI
+
+    The transform captures a provider reference at construction and queries it
+    for resources when the generated tools are called. When used with FastMCP,
+    the provider's auth and visibility filtering is automatically applied.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(ResourcesAsTools(mcp))
+        # Now has list_resources and read_resource tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        """Initialize the transform with a provider reference.
+
+        Args:
+            provider: The provider to query for resources. Typically this is
+                the same FastMCP server the transform is added to.
+        """
+        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."""
+        # Check if it's one of our generated tools
+        if name == "list_resources":
+            return self._make_list_resources_tool()
+        if name == "read_resource":
+            return self._make_read_resource_tool()
+
+        # Otherwise delegate to downstream
+        return await call_next(name, version=version)
+
+    def _make_list_resources_tool(self) -> Tool:
+        """Create the list_resources tool."""
+        provider = self._provider
+
+        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}.
+            """
+            resources = await provider.list_resources()
+            templates = await provider.list_resource_templates()
+
+            result: list[dict[str, Any]] = []
+
+            # Static resources
+            for r in resources:
+                result.append(
+                    {
+                        "uri": str(r.uri),
+                        "name": r.name,
+                        "description": r.description,
+                        "mime_type": r.mime_type,
+                    }
+                )
+
+            # Resource templates (URI contains placeholders like {name})
+            for t in templates:
+                result.append(
+                    {
+                        "uri_template": t.uri_template,
+                        "name": t.name,
+                        "description": t.description,
+                    }
+                )
+
+            return json.dumps(result, indent=2)
+
+        return Tool.from_function(fn=list_resources)
+
+    def _make_read_resource_tool(self) -> Tool:
+        """Create the read_resource tool."""
+        provider = self._provider
+
+        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.
+            """
+            from fastmcp import FastMCP
+
+            # Use FastMCP.read_resource() if available - runs middleware chain
+            if isinstance(provider, FastMCP):
+                result = await provider.read_resource(uri)
+                return _format_result(result)
+
+            # Fallback for plain providers - no middleware
+            resource = await provider.get_resource(uri)
+            if resource is not None:
+                result = await resource._read()
+                return _format_result(result)
+
+            template = await provider.get_resource_template(uri)
+            if template is not None:
+                params = template.matches(uri)
+                if params is not None:
+                    result = await template._read(uri, params)
+                    return _format_result(result)
+
+            raise ValueError(f"Resource not found: {uri}")
+
+        return Tool.from_function(fn=read_resource)
+
+
+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 with each item containing content and mime_type.
+    """
+    # result is a ResourceResult with .contents list
+    if len(result.contents) == 1:
+        content = result.contents[0].content
+        if isinstance(content, bytes):
+            return base64.b64encode(content).decode()
+        return content
+
+    # Multiple contents - JSON encode
+    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/src/fastmcp/server/transforms/search/__init__.py b/src/fastmcp/server/transforms/search/__init__.py
new file mode 100644
index 000000000..756244f23
--- /dev/null
+++ b/src/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/src/fastmcp/server/transforms/search/base.py b/src/fastmcp/server/transforms/search/base.py
new file mode 100644
index 000000000..24743b5d9
--- /dev/null
+++ b/src/fastmcp/server/transforms/search/base.py
@@ -0,0 +1,269 @@
+"""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.tool 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", 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]
+        ) -> 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/src/fastmcp/server/transforms/search/bm25.py b/src/fastmcp/server/transforms/search/bm25.py
new file mode 100644
index 000000000..8e06ac4be
--- /dev/null
+++ b/src/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.tool 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]
+        ) -> 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/src/fastmcp/server/transforms/search/regex.py b/src/fastmcp/server/transforms/search/regex.py
new file mode 100644
index 000000000..8f00bdce6
--- /dev/null
+++ b/src/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.tool 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]
+        ) -> 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/src/fastmcp/server/transforms/tool_transform.py b/src/fastmcp/server/transforms/tool_transform.py
new file mode 100644
index 000000000..ed58788da
--- /dev/null
+++ b/src/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.tool 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/src/fastmcp/server/transforms/version_filter.py b/src/fastmcp/server/transforms/version_filter.py
new file mode 100644
index 000000000..1b1d0270c
--- /dev/null
+++ b/src/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.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool 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/src/fastmcp/server/transforms/visibility.py b/src/fastmcp/server/transforms/visibility.py
new file mode 100644
index 000000000..5a3588886
--- /dev/null
+++ b/src/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.resource 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.prompt import Prompt
+    from fastmcp.server.context import Context
+    from fastmcp.tools.tool 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/src/fastmcp/settings.py b/src/fastmcp/settings.py
new file mode 100644
index 000000000..bc6d22065
--- /dev/null
+++ b/src/fastmcp/settings.py
@@ -0,0 +1,341 @@
+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"]
+
+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)
+
+
+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
+
+    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
+
+    # 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
+
+    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)
+    )
+
+    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"
+
+    decorator_mode: Annotated[
+        Literal["function", "object"],
+        Field(
+            description=inspect.cleandoc(
+                """
+                Controls what decorators (@tool, @resource, @prompt) return.
+
+                - "function" (default): Decorators return the original function unchanged.
+                  The function remains callable and is registered with the server normally.
+                - "object" (deprecated): Decorators return component objects (FunctionTool,
+                  FunctionResource, FunctionPrompt). This was the default behavior in v2 and
+                  will be removed in a future version.
+                """
+            ),
+        ),
+    ] = "function"
diff --git a/src/fastmcp/telemetry.py b/src/fastmcp/telemetry.py
new file mode 100644
index 000000000..0965b8b71
--- /dev/null
+++ b/src/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/src/fastmcp/tools.py b/src/fastmcp/tools.py
deleted file mode 100644
index 7f0c55a3e..000000000
--- a/src/fastmcp/tools.py
+++ /dev/null
@@ -1,150 +0,0 @@
-"""Tool management for FastMCP."""
-
-import base64
-import inspect
-from pathlib import Path
-from typing import Any, Callable, Dict, Optional, Union
-
-from mcp.types import ImageContent
-from pydantic import BaseModel, Field, TypeAdapter, validate_call
-
-from .exceptions import ToolError
-from .utilities.logging import get_logger
-
-logger = get_logger(__name__)
-
-
-class Image:
-    """Helper class for returning images from tools."""
-
-    def __init__(
-        self,
-        path: Optional[Union[str, Path]] = None,
-        data: Optional[bytes] = None,
-        format: Optional[str] = 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(path) if path else None
-        self.data = data
-        self._format = format
-        self._mime_type = self._get_mime_type()
-
-    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:
-            suffix = self.path.suffix.lower()
-            return {
-                ".png": "image/png",
-                ".jpg": "image/jpeg",
-                ".jpeg": "image/jpeg",
-                ".gif": "image/gif",
-                ".webp": "image/webp",
-            }.get(suffix, "application/octet-stream")
-        return "image/png"  # default for raw binary data
-
-    def to_image_content(self) -> ImageContent:
-        """Convert to MCP ImageContent."""
-        if self.path:
-            with open(self.path, "rb") as f:
-                data = base64.b64encode(f.read()).decode()
-        else:
-            data = base64.b64encode(self.data).decode()
-
-        return ImageContent(type="image", data=data, mimeType=self._mime_type)
-
-
-class Tool(BaseModel):
-    """Internal tool registration info."""
-
-    func: Callable = Field(exclude=True)
-    name: str = Field(description="Name of the tool")
-    description: str = Field(description="Description of what the tool does")
-    parameters: dict = Field(description="JSON schema for tool parameters")
-    is_async: bool = Field(description="Whether the tool is async")
-
-    @classmethod
-    def from_function(
-        cls,
-        func: Callable,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-    ) -> "Tool":
-        """Create a Tool from a function."""
-        func_name = name or func.__name__
-
-        if func_name == "<lambda>":
-            raise ValueError("You must provide a name for lambda functions")
-
-        func_doc = description or func.__doc__ or ""
-        is_async = inspect.iscoroutinefunction(func)
-
-        # Get schema from TypeAdapter - will fail if function isn't properly typed
-        parameters = TypeAdapter(func).json_schema()
-
-        # ensure the arguments are properly cast
-        func = validate_call(func)
-
-        return cls(
-            func=func,
-            name=func_name,
-            description=func_doc,
-            parameters=parameters,
-            is_async=is_async,
-        )
-
-    async def run(self, arguments: dict) -> Any:
-        """Run the tool with arguments."""
-        try:
-            # Call function with proper async handling
-            if self.is_async:
-                return await self.func(**arguments)
-            return self.func(**arguments)
-        except Exception as e:
-            raise ToolError(f"Error executing tool {self.name}: {e}") from e
-
-
-class ToolManager:
-    """Manages FastMCP tools."""
-
-    def __init__(self, warn_on_duplicate_tools: bool = True):
-        self._tools: Dict[str, Tool] = {}
-        self.warn_on_duplicate_tools = warn_on_duplicate_tools
-
-    def get_tool(self, name: str) -> Optional[Tool]:
-        """Get tool by name."""
-        return self._tools.get(name)
-
-    def list_tools(self) -> list[Tool]:
-        """List all registered tools."""
-        return list(self._tools.values())
-
-    def add_tool(
-        self,
-        func: Callable,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-    ) -> Tool:
-        """Add a tool to the server."""
-        tool = Tool.from_function(func, name=name, description=description)
-        existing = self._tools.get(tool.name)
-        if existing:
-            if self.warn_on_duplicate_tools:
-                logger.warning(f"Tool already exists: {tool.name}")
-            return existing
-        self._tools[tool.name] = tool
-        return tool
-
-    async def call_tool(self, name: str, arguments: dict) -> Any:
-        """Call a tool by name with arguments."""
-        tool = self.get_tool(name)
-        if not tool:
-            raise ToolError(f"Unknown tool: {name}")
-
-        return await tool.run(arguments)
diff --git a/src/fastmcp/tools/__init__.py b/src/fastmcp/tools/__init__.py
new file mode 100644
index 000000000..9aff985ba
--- /dev/null
+++ b/src/fastmcp/tools/__init__.py
@@ -0,0 +1,12 @@
+from .function_tool import FunctionTool, tool
+from .tool import Tool, ToolResult
+from .tool_transform import forward, forward_raw
+
+__all__ = [
+    "FunctionTool",
+    "Tool",
+    "ToolResult",
+    "forward",
+    "forward_raw",
+    "tool",
+]
diff --git a/src/fastmcp/tools/function_parsing.py b/src/fastmcp/tools/function_parsing.py
new file mode 100644
index 000000000..ce519f79e
--- /dev/null
+++ b/src/fastmcp/tools/function_parsing.py
@@ -0,0 +1,269 @@
+"""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 PydanticSchemaGenerationError
+from typing_extensions import TypeVar as TypeVarExt
+
+from fastmcp.server.dependencies import (
+    transform_context_annotations,
+    without_injected_parameters,
+)
+from fastmcp.tools.tool import ToolResult
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import (
+    Audio,
+    File,
+    Image,
+    create_function_without_params,
+    get_cached_typeadapter,
+    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_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
+
+
+T = TypeVarExt("T", default=Any)
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class _WrappedResult(Generic[T]):
+    """Generic wrapper for non-object return types."""
+
+    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],
+        exclude_args: list[str] | None = None,
+        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"
+                    )
+
+            # Reject exclude_args that don't exist in the function or don't have a default value
+            if exclude_args:
+                for arg_name in exclude_args:
+                    if arg_name not in sig.parameters:
+                        raise ValueError(
+                            f"Parameter '{arg_name}' in exclude_args does not exist in function."
+                        )
+                    param = sig.parameters[arg_name]
+                    if param.default == inspect.Parameter.empty:
+                        raise ValueError(
+                            f"Parameter '{arg_name}' in exclude_args must have a default value."
+                        )
+
+        # collect name and doc before we potentially modify the function
+        fn_name = getattr(fn, "__name__", None) or fn.__class__.__name__
+        fn_doc = inspect.getdoc(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__
+
+        # Transform Context type annotations to Depends() for unified DI
+        fn = transform_context_annotations(fn)
+
+        # Handle injected parameters (Context, Docket dependencies)
+        wrapper_fn = without_injected_parameters(fn)
+
+        # Also handle exclude_args with non-serializable types (issue #2431)
+        # This must happen before Pydantic tries to serialize the parameters
+        if exclude_args:
+            wrapper_fn = create_function_without_params(wrapper_fn, list(exclude_args))
+
+        input_type_adapter = get_cached_typeadapter(wrapper_fn)
+        input_schema = input_type_adapter.json_schema()
+
+        # Compress and handle exclude_args
+        prune_params = list(exclude_args) if exclude_args else None
+        input_schema = compress_schema(
+            input_schema, prune_params=prune_params, prune_titles=True
+        )
+
+        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, ...):
+            # 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
+
+            # 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:
+                type_adapter = get_cached_typeadapter(clean_output_type)
+                base_schema = type_adapter.json_schema(mode="serialization")
+
+                # 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")
+                    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=fn_doc,
+            input_schema=input_schema,
+            output_schema=output_schema or None,
+            return_type=original_output_type,
+        )
diff --git a/src/fastmcp/tools/function_tool.py b/src/fastmcp/tools/function_tool.py
new file mode 100644
index 000000000..140a2975b
--- /dev/null
+++ b/src/fastmcp/tools/function_tool.py
@@ -0,0 +1,476 @@
+"""Standalone @tool decorator for FastMCP."""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Literal,
+    Protocol,
+    TypeVar,
+    overload,
+    runtime_checkable,
+)
+
+import anyio
+import mcp.types
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData, Icon, ToolAnnotations, ToolExecution
+from pydantic import Field
+from pydantic.json_schema import SkipJsonSchema
+
+import fastmcp
+from fastmcp.decorators import resolve_task_config
+from fastmcp.server.auth.authorization import AuthCheck
+from fastmcp.server.dependencies import without_injected_parameters
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.tools.function_parsing import ParsedFunction, _is_object_schema
+from fastmcp.tools.tool import (
+    Tool,
+    ToolResult,
+    ToolResultSerializerType,
+)
+from fastmcp.utilities.async_utils import (
+    call_sync_fn_in_threadpool,
+    is_coroutine_function,
+)
+from fastmcp.utilities.logging import get_logger
+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
+
+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
+    exclude_args: list[str] | None = None
+    serializer: Any | None = None
+    timeout: float | None = None
+    auth: AuthCheck | list[AuthCheck] | None = None
+    enabled: bool = True
+
+
+class FunctionTool(Tool):
+    fn: SkipJsonSchema[Callable[..., Any]]
+    return_type: Annotated[SkipJsonSchema[Any], Field(exclude=True)] = None
+
+    def to_mcp_tool(
+        self,
+        **overrides: Any,
+    ) -> mcp.types.Tool:
+        """Convert the FastMCP tool to an MCP tool.
+
+        Extends the base implementation to add task execution mode if enabled.
+        """
+        # Get base MCP tool from parent
+        mcp_tool = super().to_mcp_tool(**overrides)
+
+        # Add task execution mode per SEP-1686
+        # Only set execution if not overridden and task execution is supported
+        if self.task_config.supports_tasks() and "execution" not in overrides:
+            mcp_tool.execution = ToolExecution(taskSupport=self.task_config.mode)
+
+        return mcp_tool
+
+    @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,
+        exclude_args: list[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        serializer: ToolResultSerializerType | None = None,
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | 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,
+                    serializer,
+                    timeout,
+                    auth,
+                ]
+            )
+            or output_schema is not NotSet
+            or exclude_args 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:
+            metadata = ToolMeta(
+                name=name,
+                version=version,
+                title=title,
+                description=description,
+                icons=icons,
+                tags=tags,
+                output_schema=output_schema,
+                annotations=annotations,
+                meta=meta,
+                task=task,
+                exclude_args=exclude_args,
+                serializer=serializer,
+                timeout=timeout,
+                auth=auth,
+            )
+
+        if metadata.serializer is not None and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The `serializer` parameter is deprecated. "
+                "Return ToolResult from your tools for full control over serialization. "
+                "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if metadata.exclude_args and fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                "The `exclude_args` parameter is deprecated as of FastMCP 2.14. "
+                "Use dependency injection with `Depends()` instead for better lifecycle management. "
+                "See https://gofastmcp.com/servers/dependency-injection#using-depends for examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        parsed_fn = ParsedFunction.from_function(fn, exclude_args=metadata.exclude_args)
+        func_name = metadata.name or parsed_fn.name
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        # 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 or parsed_fn.description,
+            icons=metadata.icons,
+            parameters=parsed_fn.input_schema,
+            output_schema=final_output_schema,
+            annotations=metadata.annotations,
+            tags=metadata.tags or set(),
+            serializer=metadata.serializer,
+            meta=metadata.meta,
+            task_config=task_config,
+            timeout=metadata.timeout,
+            auth=metadata.auth,
+        )
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Run the tool with arguments."""
+        wrapper_fn = without_injected_parameters(self.fn)
+        type_adapter = get_cached_typeadapter(wrapper_fn)
+
+        # Apply timeout if configured
+        if self.timeout is not None:
+            try:
+                with anyio.fail_after(self.timeout):
+                    # Thread pool execution for sync functions, direct await for async
+                    if is_coroutine_function(wrapper_fn):
+                        result = await type_adapter.validate_python(arguments)
+                    else:
+                        # Sync function: run in threadpool to avoid blocking
+                        result = await call_sync_fn_in_threadpool(
+                            type_adapter.validate_python, arguments
+                        )
+                        # Handle sync wrappers that return awaitables
+                        if inspect.isawaitable(result):
+                            result = await result
+            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(
+                    ErrorData(
+                        code=-32000,
+                        message=f"Tool '{self.name}' execution timed out after {self.timeout}s",
+                    )
+                ) from None
+        else:
+            # No timeout: use existing execution path
+            if is_coroutine_function(wrapper_fn):
+                result = await type_adapter.validate_python(arguments)
+            else:
+                result = await call_sync_fn_in_threadpool(
+                    type_adapter.validate_python, arguments
+                )
+                if inspect.isawaitable(result):
+                    result = await result
+
+        return self.convert_result(result)
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this tool with docket for background execution.
+
+        FunctionTool registers the underlying function, which has the user's
+        Depends parameters for docket to resolve.
+        """
+        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)
+
+
+@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,
+    exclude_args: list[str] | None = None,
+    serializer: Any | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> 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,
+    exclude_args: list[str] | None = None,
+    serializer: Any | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> 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,
+    exclude_args: list[str] | None = None,
+    serializer: Any | None = None,
+    timeout: float | None = None,
+    auth: AuthCheck | list[AuthCheck] | None = None,
+) -> 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().
+    """
+    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 create_tool(fn: Callable[..., Any], tool_name: str | None) -> FunctionTool:
+        # Create metadata first, then pass it
+        tool_meta = ToolMeta(
+            name=tool_name,
+            version=version,
+            title=title,
+            description=description,
+            icons=icons,
+            tags=tags,
+            output_schema=output_schema,
+            annotations=annotations,
+            meta=meta,
+            task=resolve_task_config(task),
+            exclude_args=exclude_args,
+            serializer=serializer,
+            timeout=timeout,
+            auth=auth,
+        )
+        return FunctionTool.from_function(fn, metadata=tool_meta)
+
+    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,
+            exclude_args=exclude_args,
+            serializer=serializer,
+            timeout=timeout,
+            auth=auth,
+        )
+        target = fn.__func__ if hasattr(fn, "__func__") else fn
+        target.__fastmcp__ = metadata
+        return fn
+
+    def decorator(fn: F, tool_name: str | None) -> F:
+        if fastmcp.settings.decorator_mode == "object":
+            warnings.warn(
+                "decorator_mode='object' is deprecated and will be removed in a future version. "
+                "Decorators now return the original function with metadata attached.",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            return create_tool(fn, tool_name)  # type: ignore[return-value]
+        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/src/fastmcp/tools/tool.py b/src/fastmcp/tools/tool.py
new file mode 100644
index 000000000..b23ebfc8b
--- /dev/null
+++ b/src/fastmcp/tools/tool.py
@@ -0,0 +1,544 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    ClassVar,
+    TypeAlias,
+    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.server.auth.authorization import AuthCheck
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+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__)
+
+
+ToolResultSerializerType: TypeAlias = Callable[[Any], str]
+
+
+def default_serializer(data: Any) -> str:
+    return pydantic_core.to_json(data, fallback=str).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"
+    )
+
+    def __init__(
+        self,
+        content: list[ContentBlock] | Any | None = None,
+        structured_content: dict[str, Any] | Any | None = None,
+        meta: dict[str, Any] | None = None,
+    ):
+        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 = structured_content.to_json()
+                elif isinstance(structured_content, _PrefabComponent):
+                    structured_content = _PrefabApp(view=structured_content).to_json()
+
+            try:
+                structured_content = pydantic_core.to_jsonable_python(
+                    value=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
+        )
+
+    def to_mcp_result(
+        self,
+    ) -> (
+        list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult
+    ):
+        if self.meta is not None:
+            return CallToolResult(
+                structuredContent=self.structured_content,
+                content=self.content,
+                _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
+    serializer: Annotated[
+        SkipJsonSchema[ToolResultSerializerType | None],
+        Field(
+            description="Deprecated. Return ToolResult from your tools for full control over serialization."
+        ),
+    ] = 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
+
+        return MCPTool(
+            name=overrides.get("name", self.name),
+            title=overrides.get("title", title),
+            description=overrides.get("description", self.description),
+            inputSchema=overrides.get("inputSchema", self.parameters),
+            outputSchema=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()
+            ),
+        )
+
+    @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,
+        exclude_args: list[str] | None = None,
+        output_schema: dict[str, Any] | NotSetT | None = NotSet,
+        serializer: ToolResultSerializerType | None = None,  # Deprecated
+        meta: dict[str, Any] | None = None,
+        task: bool | TaskConfig | None = None,
+        timeout: float | None = None,
+        auth: AuthCheck | list[AuthCheck] | 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,
+            exclude_args=exclude_args,
+            output_schema=output_schema,
+            serializer=serializer,
+            meta=meta,
+            task=task,
+            timeout=timeout,
+            auth=auth,
+        )
+
+    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 (serializer, 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)
+            if isinstance(raw_value, _PrefabComponent):
+                return _prefab_to_tool_result(_PrefabApp(view=raw_value))
+
+        content = _convert_to_content(raw_value, serializer=self.serializer)
+
+        # 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)
+        except pydantic_core.PydanticSerializationError:
+            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,
+        )
+
+    @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,
+        serializer: ToolResultSerializerType | None = None,  # Deprecated
+        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,
+            serializer=serializer,
+            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 _serialize_with_fallback(
+    result: Any, serializer: ToolResultSerializerType | None = None
+) -> str:
+    if serializer is not None:
+        try:
+            return serializer(result)
+        except Exception as e:
+            logger.warning(
+                "Error serializing tool result: %s",
+                e,
+                exc_info=True,
+            )
+
+    return default_serializer(result)
+
+
+def _convert_to_single_content_block(
+    item: Any,
+    serializer: ToolResultSerializerType | None = None,
+) -> 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)
+
+    return TextContent(type="text", text=_serialize_with_fallback(item, serializer))
+
+
+_PREFAB_TEXT_FALLBACK = "[Rendered Prefab UI]"
+
+
+def _prefab_to_tool_result(app: Any) -> ToolResult:
+    """Convert a PrefabApp to a FastMCP ToolResult."""
+    return ToolResult(
+        content=[TextContent(type="text", text=_PREFAB_TEXT_FALLBACK)],
+        structured_content=app.to_json(),
+    )
+
+
+def _convert_to_content(
+    result: Any,
+    serializer: ToolResultSerializerType | None = None,
+) -> 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, serializer)]
+
+    # 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, serializer)
+            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=_serialize_with_fallback(result, serializer))]
+
+
+__all__ = ["Tool", "ToolResult"]
+
+
+def __getattr__(name: str) -> Any:
+    """Deprecated re-exports for backwards compatibility."""
+    deprecated_exports = {
+        "FunctionTool": "FunctionTool",
+        "ParsedFunction": "ParsedFunction",
+        "tool": "tool",
+    }
+
+    if name in deprecated_exports:
+        import fastmcp
+
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                f"Importing {name} from fastmcp.tools.tool is deprecated. "
+                f"Import from fastmcp.tools.function_tool instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        from fastmcp.tools import function_tool
+
+        return getattr(function_tool, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/src/fastmcp/tools/tool_transform.py b/src/fastmcp/tools/tool_transform.py
new file mode 100644
index 000000000..251bc9229
--- /dev/null
+++ b/src/fastmcp/tools/tool_transform.py
@@ -0,0 +1,1005 @@
+from __future__ import annotations
+
+import inspect
+import warnings
+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
+
+import fastmcp
+from fastmcp.tools.function_parsing import ParsedFunction
+from fastmcp.tools.tool import Tool, ToolResult, _convert_to_content
+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,
+)
+
+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:
+            result = await self.fn(**arguments)
+
+            # If transform function returns ToolResult, respect our output_schema setting
+            if isinstance(result, ToolResult):
+                if self.output_schema is None:
+                    # Check if this is from a custom function that returns ToolResult
+
+                    return_annotation = inspect.signature(self.fn).return_annotation
+                    if return_annotation is ToolResult:
+                        # Custom function returns ToolResult - preserve its content
+                        return result
+                    else:
+                        # Forwarded call with no explicit schema - preserve parent's structured content
+                        # The parent tool may have generated structured content via its own fallback logic
+                        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, serializer=self.serializer
+            )
+
+            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 - always wrap in result key
+                    structured_output = {"result": 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)
+                    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,
+        serializer: Callable[[Any], str] | NotSetT | None = NotSet,  # Deprecated
+        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:
+                - Simple rename (str)
+                - Complex transformation (rename/description/default/drop) (ArgTransform)
+                - Drop the argument (None)
+            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
+                - False: Disable output schema and structured outputs
+            serializer: Deprecated. Return ToolResult from your tools for full control over serialization.
+            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)
+
+        if (
+            serializer is not NotSet
+            and serializer is not None
+            and fastmcp.settings.deprecation_warnings
+        ):
+            warnings.warn(
+                "The `serializer` parameter is deprecated. "
+                "Return ToolResult from your tools for full control over serialization. "
+                "See https://gofastmcp.com/servers/tools#custom-serialization for migration examples.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        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 - if so, don't fall back to parent
+                    return_annotation = inspect.signature(
+                        transform_fn
+                    ).return_annotation
+                    if return_annotation is 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
+        )
+        final_serializer = (
+            serializer if not isinstance(serializer, NotSetT) else tool.serializer
+        )
+
+        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,
+            serializer=final_serializer,
+            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 compress_schema from mutating parent tool's $defs
+        parent_defs = deepcopy(parent_tool.parameters.get("$defs", {}))
+        parent_props = parent_tool.parameters.get("properties", {}).copy()
+        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 = transform_result
+                new_props[new_name] = new_schema
+                new_to_old[new_name] = old_name
+                if is_required:
+                    new_required.add(new_name)
+
+        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] | 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) if parameter should be kept,
+            None if parameter should be dropped.
+        """
+        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
+        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()
+            # 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
+
+    @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/src/fastmcp/utilities/async_utils.py b/src/fastmcp/utilities/async_utils.py
new file mode 100644
index 000000000..634d9cfe3
--- /dev/null
+++ b/src/fastmcp/utilities/async_utils.py
@@ -0,0 +1,83 @@
+"""Async utilities for FastMCP."""
+
+import asyncio
+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) or asyncio.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]
+
+    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/src/fastmcp/utilities/auth.py b/src/fastmcp/utilities/auth.py
new file mode 100644
index 000000000..03eb59bb3
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/cli.py b/src/fastmcp/utilities/cli.py
new file mode 100644
index 000000000..070931fa6
--- /dev/null
+++ b/src/fastmcp/utilities/cli.py
@@ -0,0 +1,269 @@
+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://fastmcp.cloud")
+
+    # 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),
+        # expand=False,
+        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/src/fastmcp/utilities/components.py b/src/fastmcp/utilities/components.py
new file mode 100644
index 000000000..ad12f926f
--- /dev/null
+++ b/src/fastmcp/utilities/components.py
@@ -0,0 +1,255 @@
+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.server.tasks.config 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.
+        """
+        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]
+        """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)
+
+    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/src/fastmcp/utilities/exceptions.py b/src/fastmcp/utilities/exceptions.py
new file mode 100644
index 000000000..a85bbafa7
--- /dev/null
+++ b/src/fastmcp/utilities/exceptions.py
@@ -0,0 +1,49 @@
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+import httpx
+import mcp.types
+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(
+                error=mcp.types.ErrorData(
+                    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/src/fastmcp/utilities/http.py b/src/fastmcp/utilities/http.py
new file mode 100644
index 000000000..c1237d62e
--- /dev/null
+++ b/src/fastmcp/utilities/http.py
@@ -0,0 +1,8 @@
+import socket
+
+
+def find_available_port() -> int:
+    """Find an available port by letting the OS assign one."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
diff --git a/src/fastmcp/utilities/inspect.py b/src/fastmcp/utilities/inspect.py
new file mode 100644
index 000000000..369351ba5
--- /dev/null
+++ b/src/fastmcp/utilities/inspect.py
@@ -0,0 +1,494 @@
+"""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.fastmcp import FastMCP as FastMCP1x
+
+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.inputSchema if mcp_tool.inputSchema 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() 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(
+            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() 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(
+            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() 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(
+            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() 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() 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: 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
+    """
+    # Use a client to interact with the FastMCP1x server
+    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(
+                ToolInfo(
+                    key=mcp_tool.name,
+                    name=mcp_tool.name,
+                    description=mcp_tool.description,
+                    input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema 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() 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() 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(
+                ResourceInfo(
+                    key=str(mcp_resource.uri),
+                    uri=str(mcp_resource.uri),
+                    name=mcp_resource.name,
+                    description=mcp_resource.description,
+                    mime_type=mcp_resource.mimeType,
+                    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() 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(
+                TemplateInfo(
+                    key=str(mcp_template.uriTemplate),
+                    uri_template=str(mcp_template.uriTemplate),
+                    name=mcp_template.name,
+                    description=mcp_template.description,
+                    mime_type=mcp_template.mimeType,
+                    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() 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.serverInfo
+        server_icons = (
+            [icon.model_dump() for icon in server_info.icons]
+            if hasattr(server_info, "icons") and server_info.icons
+            else None
+        )
+        server_website_url = (
+            server_info.websiteUrl if hasattr(server_info, "websiteUrl") else None
+        )
+
+        return FastMCPInfo(
+            name=mcp._mcp_server.name,
+            instructions=mcp._mcp_server.instructions,
+            version=mcp._mcp_server.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] | 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
+    """
+    if isinstance(mcp, FastMCP1x):
+        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] | 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.
+    """
+    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.serverInfo
+
+        # 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.resourceTemplates,
+        }
+
+        return pydantic_core.to_json(result, indent=2)
+
+
+async def 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
+    """
+    # 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/src/fastmcp/utilities/json_schema.py b/src/fastmcp/utilities/json_schema.py
new file mode 100644
index 000000000..fc0a0d759
--- /dev/null
+++ b/src/fastmcp/utilities/json_schema.py
@@ -0,0 +1,458 @@
+from __future__ import annotations
+
+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 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.
+
+    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"}}}
+    """
+    # 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"}
+
+        return dereferenced
+
+    except JsonRefError:
+        # Self-referencing/circular schemas can't be fully dereferenced
+        # 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 $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`.
+    """
+
+    # ── 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
+
+
+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,
+    ) -> None:
+        """Traverse schema tree, collecting $ref info and applying cleanups."""
+        if depth > 50:  # Prevent infinite recursion
+            return
+
+        if isinstance(node, dict):
+            # Collect $ref references for unused definition removal
+            if prune_defs:
+                ref = node.get("$ref")  # type: ignore
+                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)
+
+            # Apply cleanups
+            # Only remove "title" if it's a schema metadata field
+            # Schema objects have keywords like "type", "properties", "$ref", etc.
+            # If we see these, then "title" is metadata, not a property name
+            if prune_titles and "title" in node:
+                # Check if this looks like a schema node
+                if any(
+                    k in node
+                    for k in [
+                        "type",
+                        "properties",
+                        "$ref",
+                        "items",
+                        "allOf",
+                        "oneOf",
+                        "anyOf",
+                        "required",
+                    ]
+                ):
+                    node.pop("title")  # type: ignore
+
+            if (
+                prune_additional_properties
+                and node.get("additionalProperties") is False  # type: ignore
+            ):
+                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
+
+                # Handle schema composition keywords with special traversal
+                if key in ["allOf", "oneOf", "anyOf"] and isinstance(value, list):
+                    for item in value:
+                        traverse_and_clean(item, current_def_name, depth=depth + 1)
+                else:
+                    traverse_and_clean(value, current_def_name, depth=depth + 1)
+
+        elif isinstance(node, list):
+            for item in node:
+                traverse_and_clean(item, current_def_name, depth=depth + 1)
+
+    # Phase 2: Traverse main schema (excluding $defs section)
+    traverse_and_clean(schema, skip_defs_section=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)
+
+        # 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/src/fastmcp/utilities/json_schema_type.py b/src/fastmcp/utilities/json_schema_type.py
new file mode 100644
index 000000000..3f1470f6f
--- /dev/null
+++ b/src/fastmcp/utilities/json_schema_type.py
@@ -0,0 +1,650 @@
+"""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
+
+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 re
+from collections.abc import Callable, Mapping
+from copy import deepcopy
+from dataclasses import MISSING, field, make_dataclass
+from datetime import datetime
+from typing import (
+    Annotated,
+    Any,
+    ForwardRef,
+    Literal,
+    Union,
+    cast,
+)
+
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    EmailStr,
+    Field,
+    Json,
+    StringConstraints,
+    model_validator,
+)
+from typing_extensions import NotRequired, TypedDict
+
+__all__ = ["JSONSchema", "json_schema_to_type"]
+
+
+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],
+    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
+        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
+        ```
+    """
+    # Always use the top-level schema for references
+    if schema.get("type") == "object":
+        # If no properties defined but has additionalProperties, return typed dict
+        if not schema.get("properties") and schema.get("additionalProperties"):
+            additional_props = schema["additionalProperties"]
+            if additional_props is True:
+                return dict[str, Any]
+            else:
+                # Handle typed dictionaries like dict[str, str]
+                value_type = _schema_to_type(additional_props, schemas=schema)
+                # value_type might be ForwardRef or type - cast to Any for dynamic type construction
+                return cast(type[Any], dict[str, value_type])  # type: ignore[valid-type]
+        # If no properties and no additionalProperties, default to dict[str, Any] for safety
+        elif not schema.get("properties") and not schema.get("additionalProperties"):
+            return dict[str, Any]
+        # If has properties AND additionalProperties is True, use Pydantic BaseModel
+        elif schema.get("properties") and schema.get("additionalProperties") is True:
+            return _create_pydantic_model(schema, name, schemas=schema)
+        # Otherwise use fast dataclass
+        return _create_dataclass(schema, name, schemas=schema)
+    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]
+
+
+def _hash_schema(schema: Mapping[str, Any]) -> str:
+    """Generate a deterministic hash for schema caching."""
+    return hashlib.sha256(json.dumps(schema, sort_keys=True).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
+    }
+
+    return Annotated[str, StringConstraints(**constraints)] if constraints else str
+
+
+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]
+
+
+def _create_enum(name: str, values: list[Any]) -> type:
+    """Create enum type from list of values."""
+    # Always return Literal for enum fields to preserve the literal nature
+    return Literal[tuple(values)]  # type: ignore[return-value]
+
+
+def _create_array_type(
+    schema: Mapping[str, Any], schemas: Mapping[str, Any]
+) -> 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) for s in items]
+        combined = Union[tuple(item_types)]  # noqa: UP007
+        base = list[combined]  # type: ignore[valid-type]
+    else:
+        # Handle single item schema
+        item_type = _schema_to_type(items, schemas)
+        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]
+
+
+def _return_Any() -> Any:
+    return Any
+
+
+def _get_from_type_handler(
+    schema: Mapping[str, Any], schemas: Mapping[str, Any]
+) -> Callable[..., Any]:
+    """Get the appropriate type handler for the schema."""
+
+    type_handlers: dict[str, Callable[..., Any]] = {  # TODO
+        "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),
+        "object": lambda s: (
+            _create_pydantic_model(s, s.get("title"), schemas)
+            if s.get("properties") and s.get("additionalProperties") is True
+            else _create_dataclass(s, s.get("title"), schemas)
+        ),
+    }
+    return type_handlers.get(schema.get("type", None), _return_Any)
+
+
+def _schema_to_type(
+    schema: Mapping[str, Any],
+    schemas: Mapping[str, Any],
+) -> type | ForwardRef:
+    """Convert schema to appropriate Python 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"))
+        return _schema_to_type(_resolve_ref(ref, schemas), schemas)
+
+    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] = []
+        for subschema in schema["anyOf"]:
+            # Special handling for dict-like objects in unions
+            if (
+                subschema.get("type") == "object"
+                and not subschema.get("properties")
+                and subschema.get("additionalProperties")
+            ):
+                # This is a dict type, handle it directly
+                additional_props = subschema["additionalProperties"]
+                if additional_props is True:
+                    types.append(dict[str, Any])
+                else:
+                    value_type = _schema_to_type(additional_props, schemas)
+                    types.append(dict[str, value_type])  # type: ignore
+            else:
+                types.append(_schema_to_type(subschema, schemas))
+
+        # 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))
+        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)(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("_")
+    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,
+) -> 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]
+        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():
+        field_type = _schema_to_type(prop_schema, schemas or {})
+
+        # 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
+            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,
+) -> 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]
+        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]
+        schema = _resolve_ref(ref, schemas or {})
+
+    properties = schema.get("properties", {})
+    required = schema.get("required", [])
+
+    fields: list[tuple[Any, ...]] = []
+    for prop_name, prop_schema in properties.items():
+        field_name = _sanitize_name(prop_name)
+
+        # Check for self-reference in property
+        if prop_schema.get("$ref") == "#":
+            field_type = ForwardRef(sanitized_name)
+        else:
+            field_type = _schema_to_type(prop_schema, schemas or {})
+
+        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
+
+    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]
+
+    # 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():
+        # 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/src/fastmcp/utilities/lifespan.py b/src/fastmcp/utilities/lifespan.py
new file mode 100644
index 000000000..f7f00b895
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/logging.py b/src/fastmcp/utilities/logging.py
index 604b24e21..0c2907b48 100644
--- a/src/fastmcp/utilities/logging.py
+++ b/src/fastmcp/utilities/logging.py
@@ -1,30 +1,238 @@
 """Logging utilities for FastMCP."""
 
+import contextlib
 import logging
-from typing import Literal
+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.'
+        name: the name of the logger, which will be prefixed with 'FastMCP.'
 
     Returns:
-        A configured logger instance
+        a configured logger instance
     """
-    return logging.getLogger(f"FastMCP.{name}")
+    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"] = "INFO",
+    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.
+    """
+    Configure logging for FastMCP.
 
     Args:
-        level: The log level to use
+        logger: the logger to configure
+        level: the log level to use
+        rich_kwargs: the parameters to use for creating RichHandler
     """
-    logging.basicConfig(
-        level=level,
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    # 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 mcp
+    import 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": [fastmcp, mcp, pydantic],
+    }
+    # Override defaults with user-provided values
+    traceback_kwargs.update(rich_kwargs)
+
+    traceback_handler = RichHandler(**traceback_kwargs)  # type: ignore[arg-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/src/fastmcp/utilities/mcp_server_config/__init__.py b/src/fastmcp/utilities/mcp_server_config/__init__.py
new file mode 100644
index 000000000..6cdfadcc5
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/__init__.py b/src/fastmcp/utilities/mcp_server_config/v1/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/utilities/mcp_server_config/v1/environments/__init__.py b/src/fastmcp/utilities/mcp_server_config/v1/environments/__init__.py
new file mode 100644
index 000000000..3cccf548f
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/environments/base.py b/src/fastmcp/utilities/mcp_server_config/v1/environments/base.py
new file mode 100644
index 000000000..0d1b1f8b1
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/environments/uv.py b/src/fastmcp/utilities/mcp_server_config/v1/environments/uv.py
new file mode 100644
index 000000000..a88965435
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py b/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py
new file mode 100644
index 000000000..5858680cc
--- /dev/null
+++ b/src/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]
+
+    @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]
+
+    @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/src/fastmcp/utilities/mcp_server_config/v1/schema.json b/src/fastmcp/utilities/mcp_server_config/v1/schema.json
new file mode 100644
index 000000000..aa1f59ce4
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/sources/__init__.py b/src/fastmcp/utilities/mcp_server_config/v1/sources/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/fastmcp/utilities/mcp_server_config/v1/sources/base.py b/src/fastmcp/utilities/mcp_server_config/v1/sources/base.py
new file mode 100644
index 000000000..cc1e9412b
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py b/src/fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py
new file mode 100644
index 000000000..f94dc7c97
--- /dev/null
+++ b/src/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.fastmcp import FastMCP as FastMCP1x
+
+        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 | FastMCP1x):
+                    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.fastmcp import FastMCP as FastMCP1x
+
+        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 | FastMCP1x):
+                    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/src/fastmcp/utilities/openapi/README.md b/src/fastmcp/utilities/openapi/README.md
new file mode 100644
index 000000000..2f2a5f45f
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/openapi/__init__.py b/src/fastmcp/utilities/openapi/__init__.py
new file mode 100644
index 000000000..eb25666d1
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/openapi/director.py b/src/fastmcp/utilities/openapi/director.py
new file mode 100644
index 000000000..58e941ba7
--- /dev/null
+++ b/src/fastmcp/utilities/openapi/director.py
@@ -0,0 +1,220 @@
+"""Request director using openapi-core for stateless HTTP request building."""
+
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+from jsonschema_path import SchemaPath
+
+from fastmcp.utilities.logging import get_logger
+
+from .models import HTTPRoute
+
+logger = get_logger(__name__)
+
+
+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, body = self._unflatten_arguments(
+            route, flat_args
+        )
+
+        logger.debug(
+            f"Unflattened - path: {path_params}, query: {query_params}, headers: {header_params}, body: {body}"
+        )
+
+        # Step 2: Build base URL with path parameters
+        url = self._build_url(route.path, path_params, base_url)
+
+        # Step 3: 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 4: Handle request body
+        if body is not None:
+            if isinstance(body, dict | list):
+                json_body = body
+            else:
+                content = body
+
+        # Step 5: Create httpx.Request
+        return httpx.Request(
+            method=method,
+            url=url,
+            params=params,
+            headers=headers,
+            json=json_body,
+            content=content,
+        )
+
+    def _unflatten_arguments(
+        self, route: HTTPRoute, flat_args: dict[str, Any]
+    ) -> tuple[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, body)
+        """
+        path_params = {}
+        query_params = {}
+        header_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 == "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"]:
+                        if location == "path":
+                            path_params[base_name] = value
+                        elif location == "query":
+                            query_params[base_name] = value
+                        elif location == "header":
+                            header_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
+                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, body
+
+    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
+        url_path = path_template
+        for param_name, param_value in path_params.items():
+            placeholder = f"{{{param_name}}}"
+            if placeholder in url_path:
+                url_path = url_path.replace(placeholder, str(param_value))
+
+        # Combine with base URL
+        return urljoin(base_url.rstrip("/") + "/", url_path.lstrip("/"))
+
+
+# Export public symbols
+__all__ = ["RequestDirector"]
diff --git a/src/fastmcp/utilities/openapi/formatters.py b/src/fastmcp/utilities/openapi/formatters.py
new file mode 100644
index 000000000..a0bd75bef
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/openapi/json_schema_converter.py b/src/fastmcp/utilities/openapi/json_schema_converter.py
new file mode 100644
index 000000000..c92b2f394
--- /dev/null
+++ b/src/fastmcp/utilities/openapi/json_schema_converter.py
@@ -0,0 +1,344 @@
+"""
+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.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,
+    "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: Remove OpenAPI-specific fields
+    for field in OPENAPI_SPECIFIC_FIELDS:
+        result.pop(field, None)
+
+    # Step 4: 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 5: 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 == "properties":
+                    # Handle properties specially - each property is a schema
+                    result[field_name] = {
+                        prop_name: convert_openapi_schema_to_json_schema(
+                            prop_schema,
+                            openapi_version,
+                            remove_read_only,
+                            remove_write_only,
+                            convert_one_of_to_any_of,
+                        )
+                        if isinstance(prop_schema, dict)
+                        else prop_schema
+                        for prop_name, prop_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"].append({"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 == "properties":
+                    # Check if any property needs conversion
+                    for prop_schema in schema[field_name].values():
+                        if isinstance(prop_schema, dict):
+                            nested_needs_conversion = (
+                                any(
+                                    field in prop_schema
+                                    for field in OPENAPI_SPECIFIC_FIELDS
+                                )
+                                or (remove_read_only and prop_schema.get("readOnly"))
+                                or (remove_write_only and prop_schema.get("writeOnly"))
+                                or (convert_one_of_to_any_of and "oneOf" in prop_schema)
+                                or _needs_recursive_processing(
+                                    prop_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/src/fastmcp/utilities/openapi/models.py b/src/fastmcp/utilities/openapi/models.py
new file mode 100644
index 000000000..03d2eb68d
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/openapi/parser.py b/src/fastmcp/utilities/openapi/parser.py
new file mode 100644
index 000000000..40adf8d27
--- /dev/null
+++ b/src/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
+                            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/src/fastmcp/utilities/openapi/schemas.py b/src/fastmcp/utilities/openapi/schemas.py
new file mode 100644
index 000000000..fa93b6c8d
--- /dev/null
+++ b/src/fastmcp/utilities/openapi/schemas.py
@@ -0,0 +1,606 @@
+"""Schema manipulation utilities for OpenAPI operations."""
+
+from typing import Any
+
+from fastmcp.utilities.logging import get_logger
+
+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_props = {}
+
+    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 both body and path/query/header
+    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())
+    colliding_params = all_non_body_params & body_param_names
+
+    # 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
+
+    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
+        from .json_schema_converter import convert_openapi_schema_to_json_schema
+
+        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"):
+            from .json_schema_converter import convert_openapi_schema_to_json_schema
+
+            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/src/fastmcp/utilities/pagination.py b/src/fastmcp/utilities/pagination.py
new file mode 100644
index 000000000..48e2e45bb
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/skills.py b/src/fastmcp/utilities/skills.py
new file mode 100644
index 000000000..a84728fe3
--- /dev/null
+++ b/src/fastmcp/utilities/skills.py
@@ -0,0 +1,253 @@
+"""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
+
+    # 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/src/fastmcp/utilities/tests.py b/src/fastmcp/utilities/tests.py
new file mode 100644
index 000000000..e25bb38b5
--- /dev/null
+++ b/src/fastmcp/utilities/tests.py
@@ -0,0 +1,270 @@
+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 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) -> tuple[str, str | None]:
+        """Parse stored response and return (auth_code, state)."""
+        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)
+            query_params = parse_qs(parsed.query)
+
+            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 auth_code, state
+        else:
+            raise RuntimeError(f"Authorization failed: {response.status_code}")
diff --git a/src/fastmcp/utilities/timeout.py b/src/fastmcp/utilities/timeout.py
new file mode 100644
index 000000000..b12997807
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/types.py b/src/fastmcp/utilities/types.py
new file mode 100644
index 000000000..f8e4f91af
--- /dev/null
+++ b/src/fastmcp/utilities/types.py
@@ -0,0 +1,499 @@
+"""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)
+
+# 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]
+
+    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,
+            mimeType=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,
+            mimeType=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
+        UriType = Annotated[AnyUrl, UrlConstraints(host_required=False)]
+        uri = 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,
+                mimeType=mime,
+                uri=uri,
+            )
+        else:
+            data = base64.b64encode(raw_data).decode()
+            resource = mcp.types.BlobResourceContents(
+                blob=data,
+                mimeType=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 old_type with new_type.
+
+    This is useful for transforming types when creating tools.
+
+    Args:
+        type_: The type to replace instances of old_type with new_type.
+        old_type: The type to replace.
+        new_type: The type to replace old_type with.
+
+    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/src/fastmcp/utilities/ui.py b/src/fastmcp/utilities/ui.py
new file mode 100644
index 000000000..8baacddf2
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/version_check.py b/src/fastmcp/utilities/version_check.py
new file mode 100644
index 000000000..5c3aba634
--- /dev/null
+++ b/src/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/src/fastmcp/utilities/versions.py b/src/fastmcp/utilities/versions.py
new file mode 100644
index 000000000..a16389fe3
--- /dev/null
+++ b/src/fastmcp/utilities/versions.py
@@ -0,0 +1,333 @@
+"""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, cast
+
+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).
+    """
+
+    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 version == 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) -> VersionKey:
+    """Get a sort key for a component based on its version.
+
+    Use with sorted() or max() to order components by version.
+
+    Args:
+        component: The component to get a sort key for.
+
+    Returns:
+        A sortable VersionKey.
+
+    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)
+
+
+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 = cast(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/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 000000000..6bfb427aa
--- /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 000000000..301c440ed
--- /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 000000000..f7b9e47a8
--- /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 2.0" 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]
+        # 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]
+        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 000000000..a0d0745d7
--- /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,
+            inputSchema=input_schema,
+            outputSchema=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 000000000..cb4dd00a0
--- /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 000000000..3996aee34
--- /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 000000000..716694353
--- /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_generate_cli.py b/tests/cli/test_generate_cli.py
new file mode 100644
index 000000000..8f567c846
--- /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",
+            inputSchema={
+                "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",
+            inputSchema={
+                "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",
+            inputSchema={
+                "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",
+            inputSchema={"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",
+            inputSchema={
+                "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",
+            inputSchema={"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",
+            inputSchema={
+                "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.",
+            inputSchema={
+                "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.",
+            inputSchema={
+                "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.",
+            inputSchema={
+                "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.",
+            inputSchema={
+                "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.",
+            inputSchema={
+                "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",
+            inputSchema={
+                "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",
+            inputSchema={
+                "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",
+                inputSchema={
+                    "properties": {
+                        "name": {"type": "string", "description": "Who to greet"},
+                    },
+                    "required": ["name"],
+                },
+            ),
+            mcp.types.Tool(
+                name="add_numbers",
+                description="Add two numbers",
+                inputSchema={
+                    "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",
+                inputSchema={
+                    "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",
+                inputSchema={
+                    "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",
+                inputSchema={"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",
+                inputSchema={
+                    "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",
+                inputSchema={
+                    "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",
+                inputSchema={"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",
+                inputSchema={
+                    "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",
+                inputSchema={
+                    "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",
+                inputSchema={
+                    "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 000000000..6108eeff6
--- /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 000000000..6b354c9b7
--- /dev/null
+++ b/tests/cli/test_install.py
@@ -0,0 +1,457 @@
+from pathlib import Path
+
+from fastmcp.cli.install import install_app
+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"))
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 000000000..279ba49e9
--- /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]
+
+    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 000000000..2be2c6938
--- /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 000000000..93e37cb7e
--- /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 000000000..462bd7734
--- /dev/null
+++ b/tests/cli/test_run.py
@@ -0,0 +1,893 @@
+import inspect
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from pydantic import ValidationError
+
+from fastmcp.cli.cli import inspector, run
+from fastmcp.cli.run import (
+    create_mcp_config_server,
+    is_url,
+    run_module_command,
+)
+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."""
+
+    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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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.fastmcp import FastMCP as FastMCP1x
+
+        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.fastmcp import 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(
+            FastMCP1x, "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 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
diff --git a/tests/cli/test_run_config.py b/tests/cli/test_run_config.py
new file mode 100644
index 000000000..4d1036ae5
--- /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 000000000..32832e70c
--- /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 000000000..b01ad2cfd
--- /dev/null
+++ b/tests/cli/test_shared.py
@@ -0,0 +1,29 @@
+from fastmcp.cli.cli 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 == ""
diff --git a/tests/cli/test_tasks.py b/tests/cli/test_tasks.py
new file mode 100644
index 000000000..202b0e7c7
--- /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]
+        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 000000000..ee9d378d4
--- /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 000000000..e69de29bb
diff --git a/tests/client/auth/__init__.py b/tests/client/auth/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/client/auth/test_oauth_cimd.py b/tests/client/auth/test_oauth_cimd.py
new file mode 100644
index 000000000..04818af60
--- /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 000000000..20a335e8d
--- /dev/null
+++ b/tests/client/auth/test_oauth_client.py
@@ -0,0 +1,358 @@
+from unittest.mock import patch
+from urllib.parse import urlparse
+
+import httpx
+import pytest
+from mcp.types import TextResourceContents
+
+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."""
+    with pytest.raises(httpx.HTTPStatusError, match="401 Unauthorized"):
+        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
+
+
+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"
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 000000000..c9f17cdbe
--- /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 000000000..e69de29bb
diff --git a/tests/client/client/test_auth.py b/tests/client/client/test_auth.py
new file mode 100644
index 000000000..f6b9dc089
--- /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 000000000..8210eb94b
--- /dev/null
+++ b/tests/client/client/test_client.py
@@ -0,0 +1,719 @@
+"""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.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.isError 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
+        if meta is not None:
+            return {
+                "has_meta": True,
+                "user_id": getattr(meta, "user_id", None),
+                "trace_id": getattr(meta, "trace_id", None),
+            }
+        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="Error rendering prompt"):
+            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.serverInfo 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.serverInfo.name == "TestServer"
+        assert result.serverInfo.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.serverInfo.name == "CustomVersionServer"
+        assert result.serverInfo.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.serverInfo.name == "DefaultVersionServer"
+        # Should fall back to FastMCP version
+        assert result.serverInfo.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()
+
+
+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_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].uriTemplate
+
+        # 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.resourceTemplates) == 1
+        assert "data://user/{user_id}" in result.resourceTemplates[0].uriTemplate
+
+
+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.uriTemplate
+
+
+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.uriTemplate
+        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
diff --git a/tests/client/client/test_error_handling.py b/tests/client/client/test_error_handling.py
new file mode 100644
index 000000000..5f5c22175
--- /dev/null
+++ b/tests/client/client/test_error_handling.py
@@ -0,0 +1,166 @@
+"""Client error handling tests."""
+
+import pytest
+from mcp.types import TextContent
+from pydantic import AnyUrl
+
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.exceptions import ResourceError, ToolError
+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.isError
+            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.isError
+            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.isError
+            # 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.isError
+            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)
diff --git a/tests/client/client/test_initialize.py b/tests/client/client/test_initialize.py
new file mode 100644
index 000000000..2c0ccfdf4
--- /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.serverInfo.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.serverInfo.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.serverInfo.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.serverInfo.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_session.py b/tests/client/client/test_session.py
new file mode 100644
index 000000000..66b38d773
--- /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 000000000..0b3b0fd3a
--- /dev/null
+++ b/tests/client/client/test_timeout.py
@@ -0,0 +1,50 @@
+"""Client timeout tests."""
+
+import sys
+
+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 while waiting for response to ClientRequest. Waited 0.05 seconds",
+            ):
+                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)
+
+    @pytest.mark.skipif(
+        sys.platform == "win32",
+        reason="This test is flaky on Windows. Sometimes the client timeout is respected and sometimes it is not.",
+    )
+    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.01,
+        ) as client:
+            await client.call_tool("sleep", {"seconds": 0.1}, timeout=2)
diff --git a/tests/client/client/test_transport.py b/tests/client/client/test_transport.py
new file mode 100644
index 000000000..b7ee5330c
--- /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.fastmcp import FastMCP 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 000000000..e69de29bb
diff --git a/tests/client/sampling/handlers/__init__.py b/tests/client/sampling/handlers/__init__.py
new file mode 100644
index 000000000..e69de29bb
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 000000000..57a464ada
--- /dev/null
+++ b/tests/client/sampling/handlers/test_anthropic_handler.py
@@ -0,0 +1,247 @@
+from unittest.mock import MagicMock
+
+import pytest
+from anthropic import AsyncAnthropic
+from anthropic.types import Message, TextBlock, ToolUseBlock, Usage
+from mcp.types import (
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+    ToolUseContent,
+)
+
+from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
+
+
+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_convert_to_anthropic_messages_raises_on_non_text():
+    from fastmcp.utilities.types import Image
+
+    with pytest.raises(ValueError):
+        AnthropicSamplingHandler._convert_to_anthropic_messages(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=Image(data=b"abc").to_image_content(),
+                )
+            ],
+        )
+
+
+@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, expected):
+    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.stopReason == "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",
+            inputSchema={
+                "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."""
+    from mcp.types import ToolResultContent
+
+    msgs = AnthropicSamplingHandler._convert_to_anthropic_messages(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ToolResultContent(
+                    type="tool_result",
+                    toolUseId="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,
+        }
+    ]
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 000000000..92403461e
--- /dev/null
+++ b/tests/client/sampling/handlers/test_google_genai_handler.py
@@ -0,0 +1,360 @@
+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 (
+        CreateMessageResult,
+        ModelHint,
+        ModelPreferences,
+        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():
+    from mcp.types import SamplingMessage, TextContent
+
+    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_to_google_genai_messages_raises_on_non_text():
+    from mcp.types import SamplingMessage
+
+    from fastmcp.utilities.types import Image
+
+    with pytest.raises(ValueError):
+        _convert_messages_to_google_genai_content(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=Image(data=b"abc").to_image_content(),
+                )
+            ],
+        )
+
+
+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",
+        toolUseId="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",
+        toolUseId="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",
+        toolUseId="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."""
+    from mcp.types import SamplingMessage
+
+    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."""
+    from mcp.types import SamplingMessage
+
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=ToolResultContent(
+                    type="tool_result",
+                    toolUseId="get_weather_123",
+                    content=[TextContent(type="text", text="Sunny, 72°F")],
+                ),
+            ),
+        ],
+    )
+
+    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)."""
+    from mcp.types import SamplingMessage
+
+    msgs = _convert_messages_to_google_genai_content(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=[
+                    TextContent(type="text", text="I need weather info."),
+                    ToolResultContent(
+                        type="tool_result",
+                        toolUseId="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.stopReason == "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.stopReason == "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.stopReason == "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"
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 000000000..29f12d749
--- /dev/null
+++ b/tests/client/sampling/handlers/test_openai_handler.py
@@ -0,0 +1,134 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from mcp.types import (
+    CreateMessageRequestParams,
+    CreateMessageResult,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+)
+from openai import AsyncOpenAI
+from openai.types.chat import (
+    ChatCompletion,
+    ChatCompletionAssistantMessageParam,
+    ChatCompletionMessage,
+    ChatCompletionSystemMessageParam,
+    ChatCompletionUserMessageParam,
+)
+from openai.types.chat.chat_completion import Choice
+
+from fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler
+
+
+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_convert_to_openai_messages_raises_on_non_text():
+    from fastmcp.utilities.types import Image
+
+    with pytest.raises(ValueError):
+        OpenAISamplingHandler._convert_to_openai_messages(
+            system_prompt=None,
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=Image(data=b"abc").to_image_content(),
+                )
+            ],
+        )
+
+
+@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, expected):
+    mock_client = MagicMock(spec=AsyncOpenAI)
+    handler = OpenAISamplingHandler(default_model="fallback-model", client=mock_client)  # type: ignore[arg-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, maxTokens=300)
+    await handler(messages, params, context=None)  # type: ignore[arg-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]
+    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",
+    )
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 000000000..fd8445c40
--- /dev/null
+++ b/tests/client/tasks/test_client_prompt_tasks.py
@@ -0,0 +1,102 @@
+"""
+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
+
+
+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 000000000..be7c4ddd3
--- /dev/null
+++ b/tests/client/tasks/test_client_resource_tasks.py
@@ -0,0 +1,107 @@
+"""
+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
+
+
+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"
+
+
+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 000000000..8fba3aad2
--- /dev/null
+++ b/tests/client/tasks/test_client_task_notifications.py
@@ -0,0 +1,209 @@
+"""
+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
+
+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.statusMessage is not None
+        )  # Error details in statusMessage per spec
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 000000000..e8b29afd9
--- /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 000000000..e5f3c8174
--- /dev/null
+++ b/tests/client/tasks/test_client_tool_tasks.py
@@ -0,0 +1,87 @@
+"""
+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
+
+
+@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.taskId == 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"
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 000000000..ea236f286
--- /dev/null
+++ b/tests/client/tasks/test_task_context_validation.py
@@ -0,0 +1,210 @@
+"""
+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"
+
+
+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."
+
+
+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 000000000..e4c5c83d8
--- /dev/null
+++ b/tests/client/tasks/test_task_result_caching.py
@@ -0,0 +1,325 @@
+"""
+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.
+"""
+
+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)
+
+        # 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
+
+
+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)
+
+
+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 000000000..e69de29bb
diff --git a/tests/client/telemetry/test_client_tracing.py b/tests/client/telemetry/test_client_tracing.py
new file mode 100644
index 000000000..309ec3af1
--- /dev/null
+++ b/tests/client/telemetry/test_client_tracing.py
@@ -0,0 +1,633 @@
+"""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
+            ),
+            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"
+        # Standard RPC semantic conventions
+        assert client_span.attributes["rpc.system"] == "mcp"
+        assert client_span.attributes["rpc.method"] == "tools/call"
+        # FastMCP-specific attributes
+        assert client_span.attributes["fastmcp.component.key"] == "add"
+
+
+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 data://config" span
+        assert "resources/read data://config" 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.startswith("resources/read data://")
+                and s.attributes is not None
+                and "fastmcp.server.name" not 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"])
+        # Standard RPC semantic conventions
+        assert client_span.attributes["rpc.system"] == "mcp"
+        assert client_span.attributes["rpc.method"] == "resources/read"
+        # 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
+            ),
+            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"
+        # Standard RPC semantic conventions
+        assert client_span.attributes["rpc.system"] == "mcp"
+        assert client_span.attributes["rpc.method"] == "prompts/get"
+        # 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
+            ),
+            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["rpc.method"] == "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
+            ),
+            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 child of client span
+        # Both should share the same trace_id
+        assert server_span.context.trace_id == client_span.context.trace_id, (
+            "Server and client spans should share the same trace_id"
+        )
+
+        # Server span's parent should be the client span
+        assert server_span.parent is not None, "Server span should have a parent"
+        assert server_span.parent.span_id == client_span.context.span_id, (
+            "Server span's parent should be 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
+            ),
+            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.startswith("resources/read data://fail")
+                and s.attributes is not None
+                and "fastmcp.server.name" not in s.attributes
+            ),
+            None,
+        )
+        # Find server-side span
+        server_span = next(
+            (
+                s
+                for s in spans
+                if s.name.startswith("resources/read data://fail")
+                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
+            ),
+            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
+            ),
+            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 client-side span
+        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
+            ),
+            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
+        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
+            ),
+            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 000000000..ff00def14
--- /dev/null
+++ b/tests/client/test_elicitation.py
@@ -0,0 +1,660 @@
+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"].requestedSchema == {
+            "properties": {"value": {"title": "Value", "type": "integer"}},
+            "required": ["value"],
+            "title": "ScalarElicitationType",
+            "type": "object",
+        }
+        assert captured_params["ctx"] is not None
+
+
+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_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.requestedSchema == {"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 = cast(AcceptedElicitation[dict[str, Any]], 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 = cast(AcceptedElicitation[dict[str, Any]], 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]
+            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.requestedSchema
+        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 000000000..d67e2b4f1
--- /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.requestedSchema
+        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.requestedSchema
+        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.requestedSchema
+        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.requestedSchema
+        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 000000000..f04af4338
--- /dev/null
+++ b/tests/client/test_logs.py
@@ -0,0 +1,242 @@
+import logging
+
+import pytest
+from mcp import LoggingLevel
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.logging import LogMessage
+
+
+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 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]
+                    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"
+            )
diff --git a/tests/client/test_notifications.py b/tests/client/test_notifications.py
new file mode 100644
index 000000000..574abcb1b
--- /dev/null
+++ b/tests/client/test_notifications.py
@@ -0,0 +1,124 @@
+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."""
+        self.notifications.append(
+            NotificationRecording(method=message.root.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 000000000..7ebcb4534
--- /dev/null
+++ b/tests/client/test_oauth_callback_race.py
@@ -0,0 +1,44 @@
+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()
diff --git a/tests/client/test_oauth_callback_xss.py b/tests/client/test_oauth_callback_xss.py
new file mode 100644
index 000000000..626fc7798
--- /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 000000000..91bd1466a
--- /dev/null
+++ b/tests/client/test_openapi.py
@@ -0,0 +1,202 @@
+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.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 = FastMCP.as_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 000000000..946c5b65c
--- /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 000000000..d3bc7d5ca
--- /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 000000000..b23276778
--- /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.systemPrompt is not None
+        return params.systemPrompt
+
+    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 as 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 as 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 as 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 as 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 000000000..73d6fbddc
--- /dev/null
+++ b/tests/client/test_sampling_result_types.py
@@ -0,0 +1,442 @@
+from mcp.types import TextContent
+
+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",
+                stopReason="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",
+                    stopReason="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",
+                    stopReason="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",
+                    stopReason="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",
+                    stopReason="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.isError 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",
+                stopReason="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",
+                stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done")],
+                    model="test-model",
+                    stopReason="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",
+                stopReason="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",
+                stopReason="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"
diff --git a/tests/client/test_sampling_tool_loop.py b/tests/client/test_sampling_tool_loop.py
new file mode 100644
index 000000000..7b3c2e9ad
--- /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",
+                    stopReason="toolUse",
+                )
+            else:
+                # Second call: return final response
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="The weather is sunny!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled error")],
+                    model="test-model",
+                    stopReason="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.isError 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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled error")],
+                    model="test-model",
+                    stopReason="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.isError 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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Handled errors")],
+                    model="test-model",
+                    stopReason="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.isError for r in tool_results)
+        assert any(r.isError 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",
+                    stopReason="toolUse",
+                )
+            else:
+                return CreateMessageResultWithTools(
+                    role="assistant",
+                    content=[TextContent(type="text", text="Done!")],
+                    model="test-model",
+                    stopReason="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].toolUseId == "call_1"
+        assert tool_results[1].toolUseId == "call_2"
+        assert tool_results[2].toolUseId == "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_sse.py b/tests/client/test_sse.py
new file mode 100644
index 000000000..4f9e51f04
--- /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 while waiting for response to ClientRequest. Waited 0.03 seconds",
+        ):
+            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 000000000..058d41ea2
--- /dev/null
+++ b/tests/client/test_stdio.py
@@ -0,0 +1,364 @@
+import asyncio
+import gc
+import inspect
+import os
+import weakref
+
+import psutil
+import pytest
+
+from fastmcp import Client, FastMCP
+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):
+        backend_transport = PythonStdioTransport(script_path=stdio_script)
+        backend_client = Client(transport=backend_transport)
+
+        proxy = FastMCP.as_proxy(backend=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
+
+
+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
+
+
+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 000000000..388eaaa9b
--- /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}!"  # ty: ignore[unresolved-attribute]
+        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 000000000..e69de29bb
diff --git a/tests/client/transports/test_transports.py b/tests/client/transports/test_transports.py
new file mode 100644
index 000000000..acf6001cb
--- /dev/null
+++ b/tests/client/transports/test_transports.py
@@ -0,0 +1,42 @@
+from ssl import VerifyMode
+
+import httpx
+
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+
+
+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]
+            == 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]
+            == VerifyMode.CERT_NONE
+        )
diff --git a/tests/client/transports/test_uv_transport.py b/tests/client/transports/test_uv_transport.py
new file mode 100644
index 000000000..8c2a500fd
--- /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",
+                    str(_fastmcp_src_dir),
+                    "--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/conftest.py b/tests/conftest.py
new file mode 100644
index 000000000..1401d4141
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,301 @@
+import asyncio
+import logging
+import socket
+import sys
+from collections.abc import Callable, Generator
+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 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".
+    """
+    test_home = tmp_path / "fastmcp-test-home"
+    test_home.mkdir(exist_ok=True)
+
+    with temporary_settings(home=test_home):
+        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 pydantic import AnyUrl
+
+    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", mimeType="application/octet-stream"),
+            EmbeddedResource(
+                type="resource",
+                resource=BlobResourceContents(
+                    blob=base64.b64encode(b"abc").decode(),
+                    mimeType="application/octet-stream",
+                    uri=AnyUrl("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 000000000..32113d184
--- /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 000000000..36b98bb7d
--- /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.tool 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(
+        isError=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(
+        isError=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(
+        isError=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",
+                    )
+                ],
+                isError=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",
+                    )
+                ],
+                isError=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",
+                    )
+                ],
+                isError=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",
+                    )
+                ],
+                isError=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."
+                        ),
+                    )
+                ],
+                isError=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."
+                        ),
+                    )
+                ],
+                isError=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 000000000..8acae9aec
--- /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 000000000..22bf02ceb
--- /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.tool 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.resource 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.prompt 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 000000000..b7d7878ba
--- /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 000000000..b9f8cf40c
--- /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/openapi/test_openapi.py b/tests/deprecated/openapi/test_openapi.py
new file mode 100644
index 000000000..36ad0b6bf
--- /dev/null
+++ b/tests/deprecated/openapi/test_openapi.py
@@ -0,0 +1,170 @@
+"""Tests for deprecated OpenAPI imports.
+
+These tests verify that the old import paths still work and emit
+deprecation warnings, ensuring backwards compatibility.
+"""
+
+import warnings
+
+import httpx
+
+
+class TestDeprecatedServerOpenAPIImports:
+    """Test deprecated imports from fastmcp.server.openapi."""
+
+    def test_import_fastmcp_openapi_emits_warning(self):
+        """Importing from fastmcp.server.openapi should emit deprecation warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            # Force reimport
+            import importlib
+
+            import fastmcp.server.openapi
+
+            importlib.reload(fastmcp.server.openapi)
+
+            deprecation_warnings = [
+                x for x in w if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            assert "providers.openapi" in str(deprecation_warnings[0].message)
+
+    def test_import_routing_emits_warning(self):
+        """Importing from fastmcp.server.openapi.routing should emit deprecation warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            import importlib
+
+            import fastmcp.server.openapi.routing
+
+            importlib.reload(fastmcp.server.openapi.routing)
+
+            deprecation_warnings = [
+                x for x in w if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            assert "providers.openapi" in str(deprecation_warnings[0].message)
+
+    def test_fastmcp_openapi_class_emits_warning(self):
+        """Using FastMCPOpenAPI should emit deprecation warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from fastmcp.server.openapi.server import FastMCPOpenAPI
+
+            spec = {
+                "openapi": "3.0.0",
+                "info": {"title": "Test", "version": "1.0.0"},
+                "paths": {},
+            }
+            client = httpx.AsyncClient(base_url="https://example.com")
+            FastMCPOpenAPI(openapi_spec=spec, client=client)
+
+            deprecation_warnings = [
+                x for x in w if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            assert "FastMCPOpenAPI" in str(deprecation_warnings[-1].message)
+
+    def test_deprecated_imports_still_work(self):
+        """All expected symbols should be importable from deprecated locations."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+
+            from fastmcp.server.openapi import (
+                FastMCPOpenAPI,
+                MCPType,
+                OpenAPIProvider,
+                RouteMap,
+            )
+
+            # Verify they're the right types
+            assert FastMCPOpenAPI is not None
+            assert OpenAPIProvider is not None
+            assert MCPType.TOOL.value == "TOOL"
+            assert RouteMap is not None
+
+    def test_deprecated_routing_imports_still_work(self):
+        """Routing symbols should be importable from deprecated location."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+
+            from fastmcp.server.openapi.routing import (
+                DEFAULT_ROUTE_MAPPINGS,
+                MCPType,
+                _determine_route_type,
+            )
+
+            assert DEFAULT_ROUTE_MAPPINGS is not None
+            assert len(DEFAULT_ROUTE_MAPPINGS) > 0
+            assert MCPType.TOOL.value == "TOOL"
+            assert _determine_route_type is not None
+
+
+class TestDeprecatedExperimentalOpenAPIImports:
+    """Test deprecated imports from fastmcp.experimental.server.openapi."""
+
+    def test_experimental_import_emits_warning(self):
+        """Importing from experimental should emit deprecation warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            import importlib
+
+            import fastmcp.experimental.server.openapi
+
+            importlib.reload(fastmcp.experimental.server.openapi)
+
+            deprecation_warnings = [
+                x for x in w if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            assert "providers.openapi" in str(deprecation_warnings[0].message)
+
+    def test_experimental_imports_still_work(self):
+        """All expected symbols should be importable from experimental."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+
+            from fastmcp.experimental.server.openapi import (
+                DEFAULT_ROUTE_MAPPINGS,
+                FastMCPOpenAPI,
+                MCPType,
+            )
+
+            assert FastMCPOpenAPI is not None
+            assert DEFAULT_ROUTE_MAPPINGS is not None
+            assert MCPType.TOOL.value == "TOOL"
+
+
+class TestDeprecatedComponentsImports:
+    """Test deprecated imports from fastmcp.server.openapi.components."""
+
+    def test_components_import_emits_warning(self):
+        """Importing from components should emit deprecation warning."""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            import importlib
+
+            import fastmcp.server.openapi.components
+
+            importlib.reload(fastmcp.server.openapi.components)
+
+            deprecation_warnings = [
+                x for x in w if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            assert "providers.openapi" in str(deprecation_warnings[0].message)
+
+    def test_components_imports_still_work(self):
+        """Component classes should be importable from deprecated location."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+
+            from fastmcp.server.openapi.components import (
+                OpenAPIResource,
+                OpenAPIResourceTemplate,
+                OpenAPITool,
+            )
+
+            assert OpenAPITool is not None
+            assert OpenAPIResource is not None
+            assert OpenAPIResourceTemplate is not None
diff --git a/tests/deprecated/server/__init__.py b/tests/deprecated/server/__init__.py
new file mode 100644
index 000000000..9a5eaa908
--- /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 000000000..70312b412
--- /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_add_tool_transformation.py b/tests/deprecated/test_add_tool_transformation.py
new file mode 100644
index 000000000..0228b8b60
--- /dev/null
+++ b/tests/deprecated/test_add_tool_transformation.py
@@ -0,0 +1,79 @@
+"""Tests for deprecated add_tool_transformation API."""
+
+import warnings
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.tools.tool_transform import ToolTransformConfig
+
+
+class TestAddToolTransformationDeprecated:
+    """Test that add_tool_transformation still works but emits deprecation warning."""
+
+    async def test_add_tool_transformation_emits_warning(self):
+        """add_tool_transformation should emit deprecation warning."""
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "hello"
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            mcp.add_tool_transformation(
+                "my_tool", ToolTransformConfig(name="renamed_tool")
+            )
+
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "add_tool_transformation is deprecated" in str(w[0].message)
+
+    async def test_add_tool_transformation_still_works(self):
+        """add_tool_transformation should still apply the transformation."""
+        mcp = FastMCP("test")
+
+        @mcp.tool
+        def verbose_tool_name() -> str:
+            return "result"
+
+        # Suppress warning for this test - we just want to verify it works
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            mcp.add_tool_transformation(
+                "verbose_tool_name", ToolTransformConfig(name="short")
+            )
+
+        async with Client(mcp) as client:
+            tools = await client.list_tools()
+            tool_names = [t.name for t in tools]
+
+            # Original name should be gone, renamed version should exist
+            assert "verbose_tool_name" not in tool_names
+            assert "short" in tool_names
+
+            # Should be callable by new name
+            result = await client.call_tool("short", {})
+            assert result.content[0].text == "result"
+
+    async def test_remove_tool_transformation_emits_warning(self):
+        """remove_tool_transformation should emit deprecation warning."""
+        mcp = FastMCP("test")
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            mcp.remove_tool_transformation("any_tool")
+
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "remove_tool_transformation is deprecated" in str(w[0].message)
+            assert "no effect" in str(w[0].message)
+
+    async def test_tool_transformations_constructor_raises_type_error(self):
+        """tool_transformations constructor param should raise TypeError."""
+        import pytest
+
+        with pytest.raises(TypeError, match="no longer accepts `tool_transformations`"):
+            FastMCP(
+                "test",
+                tool_transformations={"my_tool": ToolTransformConfig(name="renamed")},
+            )
diff --git a/tests/deprecated/test_deprecated.py b/tests/deprecated/test_deprecated.py
new file mode 100644
index 000000000..37f33cf27
--- /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_exclude_args.py b/tests/deprecated/test_exclude_args.py
new file mode 100644
index 000000000..d6ed9d9d3
--- /dev/null
+++ b/tests/deprecated/test_exclude_args.py
@@ -0,0 +1,122 @@
+from typing import Any
+
+import pytest
+from mcp.server.session import ServerSession
+
+from fastmcp import Client, FastMCP
+from fastmcp.tools.tool import Tool
+
+
+async def test_tool_exclude_args():
+    """Test that tool args are excluded."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(exclude_args=["state"])
+    def echo(message: str, state: dict[str, Any] | None = None) -> str:
+        """Echo back the message provided."""
+        if state:
+            # State was read
+            pass
+        return message
+
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert "state" not in tools[0].parameters["properties"]
+
+
+async def test_tool_exclude_args_without_default_value_raises_error():
+    """Test that excluding args without default values raises ValueError"""
+    mcp = FastMCP("Test Server")
+
+    with pytest.raises(ValueError):
+
+        @mcp.tool(exclude_args=["state"])
+        def echo(message: str, state: dict[str, Any] | None) -> str:
+            """Echo back the message provided."""
+            if state:
+                # State was read
+                pass
+            return message
+
+
+async def test_add_tool_method_exclude_args():
+    """Test that tool exclude_args work with the add_tool method."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(
+        name: str, value: int, state: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Create a new item."""
+        if state:
+            # State was read
+            pass
+        return {"name": name, "value": value}
+
+    tool = Tool.from_function(
+        create_item,
+        name="create_item",
+        exclude_args=["state"],
+    )
+    mcp.add_tool(tool)
+
+    # Check tool via public API
+    tools = await mcp.list_tools()
+    assert len(tools) == 1
+    assert "state" not in tools[0].parameters["properties"]
+
+
+async def test_tool_functionality_with_exclude_args():
+    """Test that tool functionality is preserved when using exclude_args."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(
+        name: str, value: int, state: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Create a new item."""
+        if state:
+            # state was read
+            pass
+        return {"name": name, "value": value}
+
+    tool = Tool.from_function(
+        create_item,
+        name="create_item",
+        exclude_args=["state"],
+    )
+    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_exclude_args_with_non_serializable_type():
+    """Test that exclude_args works even when the excluded parameter type can't be serialized.
+
+    This test ensures that exclude_args works correctly when the excluded parameter
+    has a type that Pydantic cannot serialize (like ServerSession). The bug was that
+    get_cached_typeadapter would try to serialize all parameters before compress_schema
+    could exclude them, causing a PydanticSchemaGenerationError.
+    """
+
+    def my_tool(message: str, session: ServerSession | None = None) -> str:
+        """A tool that takes a non-serializable Session parameter."""
+        return message
+
+    # This should not raise an error even though ServerSession can't be serialized
+    tool = Tool.from_function(
+        my_tool,
+        name="my_tool",
+        exclude_args=["session"],
+    )
+
+    # Verify the tool was created successfully
+    assert tool is not None
+    assert tool.name == "my_tool"
+
+    # Verify the session parameter is excluded from the schema
+    assert "session" not in tool.parameters["properties"]
+    assert "message" in tool.parameters["properties"]
diff --git a/tests/deprecated/test_function_component_imports.py b/tests/deprecated/test_function_component_imports.py
new file mode 100644
index 000000000..77166b28d
--- /dev/null
+++ b/tests/deprecated/test_function_component_imports.py
@@ -0,0 +1,121 @@
+"""Test that deprecated import paths for function components still work."""
+
+import warnings
+
+import pytest
+
+from fastmcp.utilities.tests import temporary_settings
+
+
+class TestDeprecatedFunctionToolImports:
+    def test_function_tool_from_tool_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning, match="Import from fastmcp.tools.function_tool"
+            ):
+                from fastmcp.tools.tool import FunctionTool
+
+            # Verify it's the real class
+            from fastmcp.tools.function_tool import (
+                FunctionTool as CanonicalFunctionTool,
+            )
+
+            assert FunctionTool is CanonicalFunctionTool
+
+    def test_parsed_function_from_tool_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning, match="Import from fastmcp.tools.function_tool"
+            ):
+                from fastmcp.tools.tool import ParsedFunction
+
+            from fastmcp.tools.function_tool import (
+                ParsedFunction as CanonicalParsedFunction,
+            )
+
+            assert ParsedFunction is CanonicalParsedFunction
+
+    def test_tool_decorator_from_tool_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning, match="Import from fastmcp.tools.function_tool"
+            ):
+                from fastmcp.tools.tool import tool
+
+            from fastmcp.tools.function_tool import tool as canonical_tool
+
+            assert tool is canonical_tool
+
+    def test_no_warning_when_disabled(self):
+        with temporary_settings(deprecation_warnings=False):
+            with warnings.catch_warnings():
+                warnings.simplefilter("error")
+                from fastmcp.tools.tool import FunctionTool  # noqa: F401
+
+
+class TestDeprecatedFunctionResourceImports:
+    def test_function_resource_from_resource_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning,
+                match="Import from fastmcp.resources.function_resource",
+            ):
+                from fastmcp.resources.resource import FunctionResource
+
+            from fastmcp.resources.function_resource import (
+                FunctionResource as CanonicalFunctionResource,
+            )
+
+            assert FunctionResource is CanonicalFunctionResource
+
+    def test_resource_decorator_from_resource_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning,
+                match="Import from fastmcp.resources.function_resource",
+            ):
+                from fastmcp.resources.resource import resource
+
+            from fastmcp.resources.function_resource import (
+                resource as canonical_resource,
+            )
+
+            assert resource is canonical_resource
+
+    def test_no_warning_when_disabled(self):
+        with temporary_settings(deprecation_warnings=False):
+            with warnings.catch_warnings():
+                warnings.simplefilter("error")
+                from fastmcp.resources.resource import FunctionResource  # noqa: F401
+
+
+class TestDeprecatedFunctionPromptImports:
+    def test_function_prompt_from_prompt_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning, match="Import from fastmcp.prompts.function_prompt"
+            ):
+                from fastmcp.prompts.prompt import FunctionPrompt
+
+            from fastmcp.prompts.function_prompt import (
+                FunctionPrompt as CanonicalFunctionPrompt,
+            )
+
+            assert FunctionPrompt is CanonicalFunctionPrompt
+
+    def test_prompt_decorator_from_prompt_module(self):
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(
+                DeprecationWarning, match="Import from fastmcp.prompts.function_prompt"
+            ):
+                from fastmcp.prompts.prompt import prompt
+
+            from fastmcp.prompts.function_prompt import prompt as canonical_prompt
+
+            assert prompt is canonical_prompt
+
+    def test_no_warning_when_disabled(self):
+        with temporary_settings(deprecation_warnings=False):
+            with warnings.catch_warnings():
+                warnings.simplefilter("error")
+                from fastmcp.prompts.prompt import FunctionPrompt  # noqa: F401
diff --git a/tests/deprecated/test_import_server.py b/tests/deprecated/test_import_server.py
new file mode 100644
index 000000000..403617bbe
--- /dev/null
+++ b/tests/deprecated/test_import_server.py
@@ -0,0 +1,714 @@
+import json
+from urllib.parse import quote
+
+from mcp.types import TextContent, TextResourceContents
+
+from fastmcp.client.client import Client
+from fastmcp.server.server import FastMCP
+from fastmcp.tools.function_tool import FunctionTool
+from fastmcp.tools.tool import Tool
+from tests.conftest import get_fn_name
+
+
+async def test_import_basic_functionality():
+    """Test that the import method properly imports tools and other resources."""
+    # Create main app and sub-app
+    main_app = FastMCP("MainApp")
+    sub_app = FastMCP("SubApp")
+
+    # Add a tool to the sub-app
+    @sub_app.tool
+    def sub_tool() -> str:
+        return "This is from the sub app"
+
+    # Import the sub-app to the main app
+    await main_app.import_server(sub_app, "sub")
+
+    # Verify the tool was imported with the prefix
+    main_tools = await main_app.list_tools()
+    sub_tools = await sub_app.list_tools()
+    assert any(t.name == "sub_sub_tool" for t in main_tools)
+    assert any(t.name == "sub_tool" for t in sub_tools)
+
+    # Verify the original tool still exists in the sub-app
+    tool = await main_app.get_tool("sub_sub_tool")
+    assert tool is not None
+    # import_server creates copies with prefixed names (unlike mount which proxies)
+    assert tool.name == "sub_sub_tool"
+    assert isinstance(tool, FunctionTool)
+    assert callable(tool.fn)
+
+
+async def test_import_multiple_apps():
+    """Test importing multiple apps to a main app."""
+    # Create main app and multiple sub-apps
+    main_app = FastMCP("MainApp")
+    weather_app = FastMCP("WeatherApp")
+    news_app = FastMCP("NewsApp")
+
+    # Add tools to each sub-app
+    @weather_app.tool
+    def get_forecast() -> str:
+        return "Weather forecast"
+
+    @news_app.tool
+    def get_headlines() -> str:
+        return "News headlines"
+
+    # Import both sub-apps to the main app
+    await main_app.import_server(weather_app, "weather")
+    await main_app.import_server(news_app, "news")
+
+    # Verify tools were imported with the correct prefixes
+    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)
+
+
+async def test_import_combines_tools():
+    """Test that importing preserves existing tools with the same prefix."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    first_app = FastMCP("FirstApp")
+    second_app = FastMCP("SecondApp")
+
+    # Add tools to each sub-app
+    @first_app.tool
+    def first_tool() -> str:
+        return "First app tool"
+
+    @second_app.tool
+    def second_tool() -> str:
+        return "Second app tool"
+
+    # Import first app
+    await main_app.import_server(first_app, "api")
+    tools = await main_app.list_tools()
+    assert any(t.name == "api_first_tool" for t in tools)
+
+    # Import second app to same prefix
+    await main_app.import_server(second_app, "api")
+
+    # Verify second tool is there
+    tools = await main_app.list_tools()
+    assert any(t.name == "api_second_tool" for t in tools)
+
+    # Tools from both imports are combined
+    assert any(t.name == "api_first_tool" for t in tools)
+
+
+async def test_import_with_resources():
+    """Test importing with resources."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    data_app = FastMCP("DataApp")
+
+    # Add a resource to the data app
+    @data_app.resource(uri="data://users")
+    async def get_users() -> str:
+        return "user1, user2"
+
+    # Import the data app
+    await main_app.import_server(data_app, "data")
+
+    # Verify the resource was imported with the prefix
+    resources = await main_app.list_resources()
+    assert any(str(r.uri) == "data://data/users" for r in resources)
+
+
+async def test_import_with_resource_templates():
+    """Test importing with resource templates."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    user_app = FastMCP("UserApp")
+
+    # Add a resource template to the user app
+    @user_app.resource(uri="users://{user_id}/profile")
+    def get_user_profile(user_id: str) -> str:
+        import json
+
+        return json.dumps(
+            {"id": user_id, "name": f"User {user_id}"}, separators=(",", ":")
+        )
+
+    # Import the user app
+    await main_app.import_server(user_app, "api")
+
+    # Verify the template was imported with the prefix
+    templates = await main_app.list_resource_templates()
+    assert any(t.uri_template == "users://api/{user_id}/profile" for t in templates)
+
+
+async def test_import_with_prompts():
+    """Test importing with prompts."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    assistant_app = FastMCP("AssistantApp")
+
+    # Add a prompt to the assistant app
+    @assistant_app.prompt
+    def greeting(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # Import the assistant app
+    await main_app.import_server(assistant_app, "assistant")
+
+    # Verify the prompt was imported with the prefix
+    prompts = await main_app.list_prompts()
+    assert any(p.name == "assistant_greeting" for p in prompts)
+
+
+async def test_import_multiple_resource_templates():
+    """Test importing multiple apps with resource templates."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    weather_app = FastMCP("WeatherApp")
+    news_app = FastMCP("NewsApp")
+
+    # Add templates to each app
+    @weather_app.resource(uri="weather://{city}")
+    def get_weather(city: str) -> str:
+        return f"Weather for {city}"
+
+    @news_app.resource(uri="news://{category}")
+    def get_news(category: str) -> str:
+        return f"News for {category}"
+
+    # Import both apps
+    await main_app.import_server(weather_app, "data")
+    await main_app.import_server(news_app, "content")
+
+    # Verify templates were imported with correct prefixes
+    templates = await main_app.list_resource_templates()
+    assert any(t.uri_template == "weather://data/{city}" for t in templates)
+    assert any(t.uri_template == "news://content/{category}" for t in templates)
+
+
+async def test_import_multiple_prompts():
+    """Test importing multiple apps with prompts."""
+    # Create apps
+    main_app = FastMCP("MainApp")
+    python_app = FastMCP("PythonApp")
+    sql_app = FastMCP("SQLApp")
+
+    # Add prompts to each app
+    @python_app.prompt
+    def review_python(code: str) -> str:
+        return f"Reviewing Python code:\n{code}"
+
+    @sql_app.prompt
+    def explain_sql(query: str) -> str:
+        return f"Explaining SQL query:\n{query}"
+
+    # Import both apps
+    await main_app.import_server(python_app, "python")
+    await main_app.import_server(sql_app, "sql")
+
+    # Verify prompts were imported with correct prefixes
+    prompts = await main_app.list_prompts()
+    assert any(p.name == "python_review_python" for p in prompts)
+    assert any(p.name == "sql_explain_sql" for p in prompts)
+
+
+async def test_tool_custom_name_preserved_when_imported():
+    """Test that a tool's custom name is preserved when imported."""
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    def fetch_data(query: str) -> str:
+        return f"Data for query: {query}"
+
+    api_app.add_tool(Tool.from_function(fetch_data, name="get_data"))
+    await main_app.import_server(api_app, "api")
+
+    # Check that the tool is accessible by its prefixed name
+    tool = await main_app.get_tool("api_get_data")
+    assert tool is not None
+
+    # Check that the function name is preserved
+    assert isinstance(tool, FunctionTool)
+    assert get_fn_name(tool.fn) == "fetch_data"
+
+
+async def test_call_imported_custom_named_tool():
+    """Test calling an imported tool with a custom name."""
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    def fetch_data(query: str) -> str:
+        return f"Data for query: {query}"
+
+    api_app.add_tool(Tool.from_function(fetch_data, name="get_data"))
+    await main_app.import_server(api_app, "api")
+
+    async with Client(main_app) as client:
+        result = await client.call_tool("api_get_data", {"query": "test"})
+        assert result.data == "Data for query: test"
+
+
+async def test_first_level_importing_with_custom_name():
+    """Test that a tool with a custom name is correctly imported at the first level."""
+    service_app = FastMCP("ServiceApp")
+    provider_app = FastMCP("ProviderApp")
+
+    def calculate_value(input: int) -> int:
+        return input * 2
+
+    provider_app.add_tool(Tool.from_function(calculate_value, name="compute"))
+    await service_app.import_server(provider_app, "provider")
+
+    # Tool is accessible in the service app with the first prefix
+    tool = await service_app.get_tool("provider_compute")
+    assert tool is not None
+    assert isinstance(tool, FunctionTool)
+    assert get_fn_name(tool.fn) == "calculate_value"
+
+
+async def test_nested_importing_preserves_prefixes():
+    """Test that importing a previously imported app preserves prefixes."""
+    main_app = FastMCP("MainApp")
+    service_app = FastMCP("ServiceApp")
+    provider_app = FastMCP("ProviderApp")
+
+    def calculate_value(input: int) -> int:
+        return input * 2
+
+    provider_app.add_tool(Tool.from_function(calculate_value, name="compute"))
+    await service_app.import_server(provider_app, "provider")
+    await main_app.import_server(service_app, "service")
+
+    # Tool is accessible in the main app with both prefixes
+    tool = await main_app.get_tool("service_provider_compute")
+    assert tool is not None
+
+
+async def test_call_nested_imported_tool():
+    """Test calling a tool through multiple levels of importing."""
+    main_app = FastMCP("MainApp")
+    service_app = FastMCP("ServiceApp")
+    provider_app = FastMCP("ProviderApp")
+
+    def calculate_value(input: int) -> int:
+        return input * 2
+
+    provider_app.add_tool(Tool.from_function(calculate_value, name="compute"))
+    await service_app.import_server(provider_app, "provider")
+    await main_app.import_server(service_app, "service")
+
+    async with Client(main_app) as client:
+        result = await client.call_tool("service_provider_compute", {"input": 21})
+        assert result.data == 42
+
+
+async def test_import_with_proxy_tools():
+    """
+    Test importing with tools that have custom names (proxy tools).
+
+    This tests that the tool's name doesn't change even though the registered
+    name does, which is important because we need to forward that name to the
+    proxy server correctly.
+    """
+    # Create apps
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    @api_app.tool
+    def get_data(query: str) -> str:
+        return f"Data for query: {query}"
+
+    proxy_app = FastMCP.as_proxy(api_app)
+    await main_app.import_server(proxy_app, "api")
+
+    async with Client(main_app) as client:
+        result = await client.call_tool("api_get_data", {"query": "test"})
+        assert result.data == "Data for query: test"
+
+
+async def test_import_with_proxy_prompts():
+    """
+    Test importing with prompts that have custom keys.
+
+    This tests that the prompt's name doesn't change even though the registered
+    key does, which is important for correct rendering.
+    """
+    # Create apps
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    @api_app.prompt
+    def greeting(name: str) -> str:
+        """Example greeting prompt."""
+        return f"Hello, {name} from API!"
+
+    proxy_app = FastMCP.as_proxy(api_app)
+    await main_app.import_server(proxy_app, "api")
+
+    async with Client(main_app) as client:
+        result = await client.get_prompt("api_greeting", {"name": "World"})
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Hello, World from API!"
+        assert result.description == "Example greeting prompt."
+
+
+async def test_import_with_proxy_resources():
+    """
+    Test importing with resources that have custom keys.
+
+    This tests that the resource's name doesn't change even though the registered
+    key does, which is important for correct access.
+    """
+    # Create apps
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    # Create a resource in the API app
+    @api_app.resource(uri="config://settings")
+    def get_config() -> str:
+        import json
+
+        return json.dumps(
+            {
+                "api_key": "12345",
+                "base_url": "https://api.example.com",
+            }
+        )
+
+    proxy_app = FastMCP.as_proxy(api_app)
+    await main_app.import_server(proxy_app, "api")
+
+    # Access the resource through the main app with the prefixed key
+    async with Client(main_app) as client:
+        result = await client.read_resource("config://api/settings")
+        assert isinstance(result[0], TextResourceContents)
+        content = json.loads(result[0].text)
+        assert content["api_key"] == "12345"
+        assert content["base_url"] == "https://api.example.com"
+
+
+async def test_import_with_proxy_resource_templates():
+    """
+    Test importing with resource templates that have custom keys.
+
+    This tests that the template's name doesn't change even though the registered
+    key does, which is important for correct instantiation.
+    """
+    # Create apps
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    # Create a resource template in the API app
+    @api_app.resource(uri="user://{name}/{email}")
+    def create_user(name: str, email: str) -> str:
+        import json
+
+        return json.dumps({"name": name, "email": email})
+
+    proxy_app = FastMCP.as_proxy(api_app)
+    await main_app.import_server(proxy_app, "api")
+
+    # Instantiate the template through the main app with the prefixed key
+
+    quoted_name = quote("John Doe", safe="")
+    quoted_email = quote("john@example.com", safe="")
+    async with Client(main_app) as client:
+        result = await client.read_resource(f"user://api/{quoted_name}/{quoted_email}")
+        assert isinstance(result[0], TextResourceContents)
+        content = json.loads(result[0].text)
+        assert content["name"] == "John Doe"
+        assert content["email"] == "john@example.com"
+
+
+async def test_import_with_no_prefix():
+    """Test importing a server without providing a prefix."""
+    main_app = FastMCP("MainApp")
+    sub_app = FastMCP("SubApp")
+
+    @sub_app.tool
+    def sub_tool() -> str:
+        return "Sub tool result"
+
+    @sub_app.resource(uri="data://config")
+    def sub_resource():
+        return "Sub resource data"
+
+    @sub_app.resource(uri="users://{user_id}/info")
+    def sub_template(user_id: str):
+        return f"Sub template for user {user_id}"
+
+    @sub_app.prompt
+    def sub_prompt() -> str:
+        return "Sub prompt content"
+
+    # Import without prefix
+    await main_app.import_server(sub_app)
+
+    # Verify all component types are accessible with original names
+    tools = await main_app.list_tools()
+    resources = await main_app.list_resources()
+    templates = await main_app.list_resource_templates()
+    prompts = await main_app.list_prompts()
+    assert any(t.name == "sub_tool" for t in tools)
+    assert any(str(r.uri) == "data://config" for r in resources)
+    assert any(t.uri_template == "users://{user_id}/info" for t in templates)
+    assert any(p.name == "sub_prompt" for p in prompts)
+
+    # Test actual functionality through Client
+    async with Client(main_app) as client:
+        # Test tool
+        tool_result = await client.call_tool("sub_tool", {})
+        assert tool_result.data == "Sub tool result"
+
+        # Test resource
+        resource_result = await client.read_resource("data://config")
+        assert isinstance(resource_result[0], TextResourceContents)
+        assert resource_result[0].text == "Sub resource data"
+
+        # Test template
+        template_result = await client.read_resource("users://123/info")
+        assert isinstance(template_result[0], TextResourceContents)
+        assert template_result[0].text == "Sub template for user 123"
+
+        # Test prompt
+        prompt_result = await client.get_prompt("sub_prompt", {})
+        assert prompt_result.messages is not None
+        assert isinstance(prompt_result.messages[0].content, TextContent)
+        assert prompt_result.messages[0].content.text == "Sub prompt content"
+
+
+async def test_import_conflict_resolution_tools():
+    """Test that later imported tools overwrite earlier ones when names conflict."""
+    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"
+
+    # Import both apps without prefix
+    await main_app.import_server(first_app)
+    await main_app.import_server(second_app)
+
+    async with Client(main_app) as client:
+        # The later imported server should win
+        tools = await client.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "shared_tool" in tool_names
+        assert tool_names.count("shared_tool") == 1  # Should only appear once
+
+        result = await client.call_tool("shared_tool", {})
+        assert result.data == "Second app tool"
+
+
+async def test_import_conflict_resolution_resources():
+    """Test that later imported resources overwrite earlier ones when URIs conflict."""
+    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"
+
+    # Import both apps without prefix
+    await main_app.import_server(first_app)
+    await main_app.import_server(second_app)
+
+    async with Client(main_app) as client:
+        # The later imported server should win
+        resources = await client.list_resources()
+        resource_uris = [str(r.uri) for r in resources]
+        assert "shared://data" in resource_uris
+        assert resource_uris.count("shared://data") == 1  # Should only appear once
+
+        result = await client.read_resource("shared://data")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Second app data"
+
+
+async def test_import_conflict_resolution_templates():
+    """Test that later imported templates overwrite earlier ones when URI templates conflict."""
+    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}"
+
+    # Import both apps without prefix
+    await main_app.import_server(first_app)
+    await main_app.import_server(second_app)
+
+    async with Client(main_app) as client:
+        # The later imported server should win
+        templates = await client.list_resource_templates()
+        template_uris = [t.uriTemplate for t in templates]
+        assert "users://{user_id}/profile" in template_uris
+        assert (
+            template_uris.count("users://{user_id}/profile") == 1
+        )  # Should only appear once
+
+        result = await client.read_resource("users://123/profile")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Second app user 123"
+
+
+async def test_import_conflict_resolution_prompts():
+    """Test that later imported prompts overwrite earlier ones when names conflict."""
+    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"
+
+    # Import both apps without prefix
+    await main_app.import_server(first_app)
+    await main_app.import_server(second_app)
+
+    async with Client(main_app) as client:
+        # The later imported server should win
+        prompts = await client.list_prompts()
+        prompt_names = [p.name for p in prompts]
+        assert "shared_prompt" in prompt_names
+        assert prompt_names.count("shared_prompt") == 1  # Should only appear once
+
+        result = await client.get_prompt("shared_prompt", {})
+        assert result.messages is not None
+        assert isinstance(result.messages[0].content, TextContent)
+        assert result.messages[0].content.text == "Second app prompt"
+
+
+async def test_import_conflict_resolution_with_prefix():
+    """Test that later imported components overwrite earlier ones when prefixed names conflict."""
+    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"
+
+    # Import both apps with same prefix
+    await main_app.import_server(first_app, "api")
+    await main_app.import_server(second_app, "api")
+
+    async with Client(main_app) as client:
+        # The later imported server should win
+        tools = await client.list_tools()
+        tool_names = [t.name for t in tools]
+        assert "api_shared_tool" in tool_names
+        assert tool_names.count("api_shared_tool") == 1  # Should only appear once
+
+        result = await client.call_tool("api_shared_tool", {})
+        assert result.data == "Second app tool"
+
+
+async def test_import_server_resource_uri_prefixing():
+    """Test that resource URIs are prefixed when using import_server (names are NOT prefixed)."""
+    # Create a sub-server with a resource
+    sub_server = FastMCP("SubServer")
+
+    @sub_server.resource("resource://test_resource")
+    def test_resource() -> str:
+        return "Test content"
+
+    # Create main server and import sub-server with prefix
+    main_server = FastMCP("MainServer")
+    await main_server.import_server(sub_server, prefix="imported")
+
+    # Get resources and verify URI prefixing (name should NOT be prefixed)
+    resources = await main_server.list_resources()
+    resource = next(
+        r for r in resources if str(r.uri) == "resource://imported/test_resource"
+    )
+    assert resource.name == "test_resource"
+
+
+async def test_import_server_resource_template_uri_prefixing():
+    """Test that resource template URIs are prefixed when using import_server (names are NOT prefixed)."""
+    # Create a sub-server with a resource template
+    sub_server = FastMCP("SubServer")
+
+    @sub_server.resource("resource://data/{item_id}")
+    def data_template(item_id: str) -> str:
+        return f"Data for {item_id}"
+
+    # Create main server and import sub-server with prefix
+    main_server = FastMCP("MainServer")
+    await main_server.import_server(sub_server, prefix="imported")
+
+    # Get resource templates and verify URI prefixing (name should NOT be prefixed)
+    templates = await main_server.list_resource_templates()
+    template = next(
+        t for t in templates if t.uri_template == "resource://imported/data/{item_id}"
+    )
+    assert template.name == "data_template"
+
+
+async def test_import_server_with_new_prefix_format():
+    """Test that import_server correctly uses the new prefix format."""
+    # Create a server with resources
+    source_server = FastMCP(name="SourceServer")
+
+    @source_server.resource("resource://test-resource")
+    def get_resource():
+        return "Resource content"
+
+    @source_server.resource("resource:///absolute/path")
+    def get_absolute_resource():
+        return "Absolute resource content"
+
+    @source_server.resource("resource://{param}/template")
+    def get_template_resource(param: str):
+        return f"Template resource with {param}"
+
+    # Create target server and import the source server
+    target_server = FastMCP(name="TargetServer")
+    await target_server.import_server(source_server, "imported")
+
+    # Check that the resources were imported with the correct prefixes
+    resources = await target_server.list_resources()
+    templates = await target_server.list_resource_templates()
+
+    assert any(str(r.uri) == "resource://imported/test-resource" for r in resources)
+    assert any(str(r.uri) == "resource://imported//absolute/path" for r in resources)
+    assert any(
+        t.uri_template == "resource://imported/{param}/template" for t in templates
+    )
+
+    # Verify we can access the resources
+    async with Client(target_server) as client:
+        result = await client.read_resource("resource://imported/test-resource")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Resource content"
+
+        result = await client.read_resource("resource://imported//absolute/path")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Absolute resource content"
+
+        result = await client.read_resource("resource://imported/param-value/template")
+        assert isinstance(result[0], TextResourceContents)
+        assert result[0].text == "Template resource with param-value"
diff --git a/tests/deprecated/test_openapi_deprecations.py b/tests/deprecated/test_openapi_deprecations.py
new file mode 100644
index 000000000..b57611c6f
--- /dev/null
+++ b/tests/deprecated/test_openapi_deprecations.py
@@ -0,0 +1,53 @@
+"""Tests for OpenAPI-related deprecations in 2.14."""
+
+import importlib
+import warnings
+
+import pytest
+
+pytestmark = pytest.mark.filterwarnings("default::DeprecationWarning")
+
+
+class TestExperimentalOpenAPIImportDeprecation:
+    """Test experimental OpenAPI import path deprecations."""
+
+    def test_experimental_server_openapi_import_warns(self):
+        """Importing from fastmcp.experimental.server.openapi should warn."""
+        import fastmcp.experimental.server.openapi
+
+        with pytest.warns(
+            DeprecationWarning,
+            match=r"Importing from fastmcp\.experimental\.server\.openapi is deprecated",
+        ):
+            importlib.reload(fastmcp.experimental.server.openapi)
+
+    def test_experimental_utilities_openapi_import_warns(self):
+        """Importing from fastmcp.experimental.utilities.openapi should warn."""
+        import fastmcp.experimental.utilities.openapi
+
+        with pytest.warns(
+            DeprecationWarning,
+            match=r"Importing from fastmcp\.experimental\.utilities\.openapi is deprecated",
+        ):
+            importlib.reload(fastmcp.experimental.utilities.openapi)
+
+    def test_experimental_imports_resolve_to_same_classes(self):
+        """Experimental imports should resolve to the same classes as main imports."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+
+            from fastmcp.experimental.server.openapi import (
+                FastMCPOpenAPI as ExpFastMCPOpenAPI,
+            )
+            from fastmcp.experimental.server.openapi import MCPType as ExpMCPType
+            from fastmcp.experimental.server.openapi import RouteMap as ExpRouteMap
+            from fastmcp.experimental.utilities.openapi import (
+                HTTPRoute as ExpHTTPRoute,
+            )
+            from fastmcp.server.openapi import FastMCPOpenAPI, MCPType, RouteMap
+            from fastmcp.utilities.openapi import HTTPRoute
+
+        assert FastMCPOpenAPI is ExpFastMCPOpenAPI
+        assert RouteMap is ExpRouteMap
+        assert MCPType is ExpMCPType
+        assert HTTPRoute is ExpHTTPRoute
diff --git a/tests/deprecated/test_settings.py b/tests/deprecated/test_settings.py
new file mode 100644
index 000000000..47ea6613c
--- /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/deprecated/test_tool_injection_middleware.py b/tests/deprecated/test_tool_injection_middleware.py
new file mode 100644
index 000000000..af4f5df1c
--- /dev/null
+++ b/tests/deprecated/test_tool_injection_middleware.py
@@ -0,0 +1,245 @@
+"""Tests for deprecated PromptToolMiddleware and ResourceToolMiddleware."""
+
+import pytest
+from inline_snapshot import snapshot
+from mcp.types import TextContent
+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 (
+    PromptToolMiddleware,
+    ResourceToolMiddleware,
+)
+
+
+class TestPromptToolMiddleware:
+    """Tests for PromptToolMiddleware."""
+
+    @pytest.fixture
+    def server_with_prompts(self):
+        """Create a FastMCP server with prompts."""
+        mcp = FastMCP("PromptServer")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        @mcp.prompt
+        def greeting(name: str) -> str:
+            """Generate a greeting message."""
+            return f"Hello, {name}!"
+
+        @mcp.prompt
+        def farewell(name: str) -> str:
+            """Generate a farewell message."""
+            return f"Goodbye, {name}!"
+
+        return mcp
+
+    async def test_prompt_tools_added_to_list(self, server_with_prompts: FastMCP):
+        """Test that prompt tools are added to the tool list."""
+        middleware = PromptToolMiddleware()
+        server_with_prompts.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_prompts) as client:
+            tools: list[SDKTool] = await client.list_tools()
+
+        tool_names: list[str] = [tool.name for tool in tools]
+        # Should have: add, list_prompts, get_prompt
+        assert len(tools) == 3
+        assert "add" in tool_names
+        assert "list_prompts" in tool_names
+        assert "get_prompt" in tool_names
+
+    async def test_list_prompts_tool_works(self, server_with_prompts: FastMCP):
+        """Test that the list_prompts tool can be called."""
+        middleware = PromptToolMiddleware()
+        server_with_prompts.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_prompts) as client:
+            result: CallToolResult = await client.call_tool(
+                name="list_prompts", arguments={}
+            )
+
+        assert result.content == snapshot(
+            [
+                TextContent(
+                    type="text",
+                    text='[{"name":"greeting","title":null,"description":"Generate a greeting message.","arguments":[{"name":"name","description":null,"required":true}],"icons":null,"_meta":{"fastmcp":{"tags":[]}}},{"name":"farewell","title":null,"description":"Generate a farewell message.","arguments":[{"name":"name","description":null,"required":true}],"icons":null,"_meta":{"fastmcp":{"tags":[]}}}]',
+                )
+            ]
+        )
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == snapshot(
+            [
+                {
+                    "name": "greeting",
+                    "title": None,
+                    "description": "Generate a greeting message.",
+                    "arguments": [
+                        {"name": "name", "description": None, "required": True}
+                    ],
+                    "icons": None,
+                    "_meta": {"fastmcp": {"tags": []}},
+                },
+                {
+                    "name": "farewell",
+                    "title": None,
+                    "description": "Generate a farewell message.",
+                    "arguments": [
+                        {"name": "name", "description": None, "required": True}
+                    ],
+                    "icons": None,
+                    "_meta": {"fastmcp": {"tags": []}},
+                },
+            ]
+        )
+
+    async def test_get_prompt_tool_works(self, server_with_prompts: FastMCP):
+        """Test that the get_prompt tool can be called."""
+        middleware = PromptToolMiddleware()
+        server_with_prompts.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_prompts) as client:
+            result: CallToolResult = await client.call_tool(
+                name="get_prompt",
+                arguments={"name": "greeting", "arguments": {"name": "World"}},
+            )
+
+        # The tool returns the prompt result with structured_content
+        assert result.content == snapshot(
+            [
+                TextContent(
+                    type="text",
+                    text='{"_meta":null,"description":"Generate a greeting message.","messages":[{"role":"user","content":{"type":"text","text":"Hello, World!","annotations":null,"_meta":null}}]}',
+                )
+            ]
+        )
+        assert result.structured_content is not None
+        assert result.structured_content == snapshot(
+            {
+                "_meta": None,
+                "description": "Generate a greeting message.",
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": {
+                            "type": "text",
+                            "text": "Hello, World!",
+                            "annotations": None,
+                            "_meta": None,
+                        },
+                    }
+                ],
+            }
+        )
+
+
+class TestResourceToolMiddleware:
+    """Tests for ResourceToolMiddleware."""
+
+    @pytest.fixture
+    def server_with_resources(self):
+        """Create a FastMCP server with resources."""
+        mcp = FastMCP("ResourceServer")
+
+        @mcp.tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        @mcp.resource("file://config.txt")
+        def config_resource() -> str:
+            """Get configuration."""
+            return "debug=true"
+
+        @mcp.resource("file://data.json")
+        def data_resource() -> str:
+            """Get data."""
+            return '{"count": 42}'
+
+        return mcp
+
+    async def test_resource_tools_added_to_list(self, server_with_resources: FastMCP):
+        """Test that resource tools are added to the tool list."""
+        middleware = ResourceToolMiddleware()
+        server_with_resources.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_resources) as client:
+            tools: list[SDKTool] = await client.list_tools()
+
+        tool_names: list[str] = [tool.name for tool in tools]
+        # Should have: add, list_resources, read_resource
+        assert len(tools) == 3
+        assert "add" in tool_names
+        assert "list_resources" in tool_names
+        assert "read_resource" in tool_names
+
+    async def test_list_resources_tool_works(self, server_with_resources: FastMCP):
+        """Test that the list_resources tool can be called."""
+        middleware = ResourceToolMiddleware()
+        server_with_resources.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_resources) as client:
+            result: CallToolResult = await client.call_tool(
+                name="list_resources", arguments={}
+            )
+
+        assert result.structured_content is not None
+        assert result.structured_content["result"] == snapshot(
+            [
+                {
+                    "name": "config_resource",
+                    "title": None,
+                    "uri": "file://config.txt/",
+                    "description": "Get configuration.",
+                    "mimeType": "text/plain",
+                    "size": None,
+                    "icons": None,
+                    "annotations": None,
+                    "_meta": {"fastmcp": {"tags": []}},
+                },
+                {
+                    "name": "data_resource",
+                    "title": None,
+                    "uri": "file://data.json/",
+                    "description": "Get data.",
+                    "mimeType": "text/plain",
+                    "size": None,
+                    "icons": None,
+                    "annotations": None,
+                    "_meta": {"fastmcp": {"tags": []}},
+                },
+            ]
+        )
+
+    async def test_read_resource_tool_works(self, server_with_resources: FastMCP):
+        """Test that the read_resource tool can be called."""
+        middleware = ResourceToolMiddleware()
+        server_with_resources.add_middleware(middleware)
+
+        async with Client[FastMCPTransport](server_with_resources) as client:
+            result: CallToolResult = await client.call_tool(
+                name="read_resource", arguments={"uri": "file://config.txt"}
+            )
+
+        assert result.content == snapshot(
+            [
+                TextContent(
+                    type="text",
+                    text='{"contents":[{"content":"debug=true","mime_type":"text/plain","meta":null}],"meta":null}',
+                )
+            ]
+        )
+        assert result.structured_content == snapshot(
+            {
+                "contents": [
+                    {"content": "debug=true", "mime_type": "text/plain", "meta": None}
+                ],
+                "meta": None,
+            }
+        )
diff --git a/tests/deprecated/test_tool_serializer.py b/tests/deprecated/test_tool_serializer.py
new file mode 100644
index 000000000..2b706ae74
--- /dev/null
+++ b/tests/deprecated/test_tool_serializer.py
@@ -0,0 +1,181 @@
+"""Tests for deprecated tool serializer functionality.
+
+These tests verify that serializer parameters still work but are deprecated.
+All serializer-related tests should be moved here.
+"""
+
+import warnings
+
+import pytest
+from inline_snapshot import snapshot
+from mcp.types import TextContent
+
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import mcp_tool
+from fastmcp.server.providers import LocalProvider
+from fastmcp.tools.tool import Tool, _convert_to_content
+from fastmcp.tools.tool_transform import TransformedTool
+from fastmcp.utilities.tests import temporary_settings
+
+# Reset deprecation warnings for this module
+pytestmark = pytest.mark.filterwarnings("default::DeprecationWarning")
+
+
+class TestToolSerializerDeprecated:
+    """Tests for deprecated serializer functionality."""
+
+    async def test_tool_serializer(self):
+        """Test that a tool's serializer is used to serialize the result."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom serializer: {data}"
+
+        def process_list(items: list[int]) -> int:
+            return sum(items)
+
+        tool = Tool.from_function(process_list, serializer=custom_serializer)
+
+        result = await tool.run(arguments={"items": [1, 2, 3, 4, 5]})
+        # Custom serializer affects unstructured content
+        assert isinstance(result.content[0], TextContent)
+        assert result.content[0].text == "Custom serializer: 15"
+        # Structured output should have the raw value
+        assert result.structured_content == {"result": 15}
+
+    def test_custom_serializer(self):
+        """Test that a custom serializer is used for non-MCP types."""
+
+        def custom_serializer(data):
+            return f"Serialized: {data}"
+
+        result = _convert_to_content({"a": 1}, serializer=custom_serializer)
+
+        assert result == snapshot(
+            [TextContent(type="text", text="Serialized: {'a': 1}")]
+        )
+
+    def test_custom_serializer_error_fallback(self, caplog):
+        """Test that if a custom serializer fails, it falls back to the default."""
+
+        def custom_serializer_that_fails(data):
+            raise ValueError("Serialization failed")
+
+        result = _convert_to_content({"a": 1}, serializer=custom_serializer_that_fails)
+
+        assert isinstance(result, list)
+        assert result == snapshot([TextContent(type="text", text='{"a":1}')])
+
+        assert "Error serializing tool result" in caplog.text
+
+
+class TestSerializerDeprecationWarnings:
+    """Tests that deprecation warnings are raised when serializer is used."""
+
+    def test_tool_from_function_serializer_warning(self):
+        """Test that Tool.from_function warns when serializer is provided."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+                Tool.from_function(my_tool, serializer=custom_serializer)
+
+    def test_tool_from_function_serializer_no_warning_when_disabled(self):
+        """Test that no warning is raised when deprecation_warnings is False."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        with temporary_settings(deprecation_warnings=False):
+            with warnings.catch_warnings():
+                warnings.simplefilter("error")
+                # Should not raise
+                Tool.from_function(my_tool, serializer=custom_serializer)
+
+    def test_local_provider_tool_serializer_warning(self):
+        """Test that LocalProvider.tool warns when serializer is provided."""
+        provider = LocalProvider()
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+                provider.tool(my_tool, serializer=custom_serializer)
+
+    def test_local_provider_tool_decorator_serializer_warning(self):
+        """Test that LocalProvider.tool decorator warns when serializer is provided."""
+        provider = LocalProvider()
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+
+                @provider.tool(serializer=custom_serializer)
+                def my_tool(x: int) -> int:
+                    return x * 2
+
+    def test_fastmcp_tool_serializer_warning(self):
+        """Test that FastMCP.tool warns when serializer is provided via LocalProvider."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        # FastMCP.tool doesn't accept serializer directly, it goes through LocalProvider
+        # So we test LocalProvider.tool which is what FastMCP uses internally
+        provider = LocalProvider()
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+                provider.tool(my_tool, serializer=custom_serializer)
+
+    def test_fastmcp_tool_serializer_parameter_raises_type_error(self):
+        """Test that FastMCP tool_serializer parameter raises TypeError."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        with pytest.raises(TypeError, match="no longer accepts `tool_serializer`"):
+            FastMCP("TestServer", tool_serializer=custom_serializer)
+
+    def test_transformed_tool_from_tool_serializer_warning(self):
+        """Test that TransformedTool.from_tool warns when serializer is provided."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        def my_tool(x: int) -> int:
+            return x * 2
+
+        parent_tool = Tool.from_function(my_tool)
+
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+                TransformedTool.from_tool(parent_tool, serializer=custom_serializer)
+
+    def test_mcp_mixin_tool_serializer_warning(self):
+        """Test that mcp_tool decorator warns when serializer is provided."""
+
+        def custom_serializer(data) -> str:
+            return f"Custom: {data}"
+
+        with temporary_settings(deprecation_warnings=True):
+            with pytest.warns(DeprecationWarning, match="serializer.*deprecated"):
+
+                @mcp_tool(serializer=custom_serializer)
+                def my_tool(x: int) -> int:
+                    return x * 2
diff --git a/tests/experimental/README.md b/tests/experimental/README.md
new file mode 100644
index 000000000..1912e19d6
--- /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 000000000..e69de29bb
diff --git a/tests/experimental/transforms/test_code_mode.py b/tests/experimental/transforms/test_code_mode.py
new file mode 100644
index 000000000..454a8ccfb
--- /dev/null
+++ b/tests/experimental/transforms/test_code_mode.py
@@ -0,0 +1,717 @@
+import importlib
+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 (
+    CodeMode,
+    GetSchemas,
+    GetToolCatalog,
+    MontySandboxProvider,
+    Search,
+    _ensure_async,
+)
+from fastmcp.server.context import Context
+from fastmcp.tools.tool import Tool, 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.
+
+    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]
+        ) -> 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", mimeType="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')"})
+
+
+# ---------------------------------------------------------------------------
+# 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_no_limits_by_default() -> None:
+    provider = MontySandboxProvider()
+    result = await provider.run("return 1 + 2")
+    assert result == 3
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 000000000..cdc45ba1f
--- /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.tool 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 000000000..a589ad790
--- /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 000000000..261b93401
--- /dev/null
+++ b/tests/fs/test_discovery.py
@@ -0,0 +1,353 @@
+"""Tests for filesystem discovery module."""
+
+from pathlib import Path
+
+from fastmcp.resources.template import FunctionResourceTemplate
+from fastmcp.server.providers.filesystem_discovery import (
+    discover_and_import,
+    discover_files,
+    extract_components,
+    import_module_from_file,
+)
+from fastmcp.tools import FunctionTool
+
+
+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]
diff --git a/tests/fs/test_provider.py b/tests/fs/test_provider.py
new file mode 100644
index 000000000..03518e795
--- /dev/null
+++ b/tests/fs/test_provider.py
@@ -0,0 +1,421 @@
+"""Tests for FileSystemProvider."""
+
+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 _ensure_loaded
+        (tmp_path / "tool2.py").write_text(
+            """\
+from fastmcp.tools import tool
+
+@tool
+def added() -> str:
+    return "added"
+"""
+        )
+
+        # With reload=True, _ensure_loaded re-scans
+        await provider._ensure_loaded()
+        assert len(provider._components) == 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._ensure_loaded()
+        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._ensure_loaded()
+        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._ensure_loaded()
+        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._ensure_loaded()
+        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 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"}
diff --git a/tests/integration_tests/__init__.py b/tests/integration_tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/integration_tests/auth/__init__.py b/tests/integration_tests/auth/__init__.py
new file mode 100644
index 000000000..e69de29bb
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 000000000..3563dd093
--- /dev/null
+++ b/tests/integration_tests/auth/test_github_provider_integration.py
@@ -0,0 +1,394 @@
+"""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]
+
+    # 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]
+
+    # 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."""
+    import httpx
+
+    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(httpx.HTTPStatusError, match="401 Unauthorized"):
+        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/conftest.py b/tests/integration_tests/conftest.py
new file mode 100644
index 000000000..c85b38e53
--- /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 000000000..a58b17c63
--- /dev/null
+++ b/tests/integration_tests/test_github_mcp_remote.py
@@ -0,0 +1,123 @@
+import json
+import os
+
+import pytest
+from mcp import McpError
+from mcp.types import 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.inputSchema, dict)
+                assert len(tool.inputSchema) > 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)
+            assert len(resources) == 0
+
+    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 000000000..27776c1ba
--- /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 000000000..e69de29bb
diff --git a/tests/prompts/test_prompt.py b/tests/prompts/test_prompt.py
new file mode 100644
index 000000000..65fad5444
--- /dev/null
+++ b/tests/prompts/test_prompt.py
@@ -0,0 +1,718 @@
+import pytest
+from mcp.types import EmbeddedResource, TextResourceContents
+from pydantic import FileUrl
+
+from fastmcp.prompts.prompt 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=FileUrl("file://file.txt"),
+                            text="File contents",
+                            mimeType="text/plain",
+                        ),
+                    ),
+                    role="user",
+                )
+            ]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [
+            Message(
+                content=EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=FileUrl("file://file.txt"),
+                        text="File contents",
+                        mimeType="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=FileUrl("file://file.txt"),
+                            text="File contents",
+                            mimeType="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=FileUrl("file://file.txt"),
+                        text="File contents",
+                        mimeType="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=FileUrl("file://file.txt"),
+                            text="File contents",
+                            mimeType="text/plain",
+                        ),
+                    ),
+                    role="user",
+                )
+            ]
+
+        prompt = Prompt.from_function(fn)
+        result = await prompt.render()
+        assert result.messages == [
+            Message(
+                content=EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=FileUrl("file://file.txt"),
+                        text="File contents",
+                        mimeType="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 due to exception handling in render()
+        with pytest.raises(PromptError) as exc_info:
+            await prompt.render(arguments={"numbers": "not valid json"})
+
+        assert f"Error rendering prompt {prompt.name}" 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_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", mimeType="image/png")
+        msg = Message(img, role="user")
+        assert isinstance(msg.content, ImageContent)
+        assert msg.content.data == "base64data"
+        assert msg.content.mimeType == "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", mimeType="audio/wav")
+        msg = Message(audio, role="user")
+        assert isinstance(msg.content, AudioContent)
+        assert msg.content.data == "base64audio"
+        assert msg.content.mimeType == "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", mimeType="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]
+
+    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]
+
+    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 000000000..b835303a0
--- /dev/null
+++ b/tests/prompts/test_standalone_decorator.py
@@ -0,0 +1,138 @@
+"""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"
+
+    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]
+            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/test_file_resources.py b/tests/resources/test_file_resources.py
index b9691929d..71e95ea99 100644
--- a/tests/resources/test_file_resources.py
+++ b/tests/resources/test_file_resources.py
@@ -1,8 +1,13 @@
-import pytest
+import os
 from pathlib import Path
-from tempfile import NamedTemporaryFile, TemporaryDirectory
+from tempfile import NamedTemporaryFile
+
+import pytest
+from pydantic import FileUrl
 
+from fastmcp.exceptions import ResourceError
 from fastmcp.resources import FileResource
+from fastmcp.resources.resource import ResourceResult
 
 
 @pytest.fixture
@@ -22,88 +27,95 @@ def temp_file():
         pass  # File was already deleted by the test
 
 
-@pytest.fixture
-def temp_dir_with_files():
-    """Create a temporary directory with test files."""
-    with TemporaryDirectory() as d:
-        path = Path(d).resolve()
-        # Create some test files
-        (path / "file1.txt").write_text("content1")
-        (path / "file2.txt").write_text("content2")
-        (path / "subdir").mkdir()
-        (path / "subdir/file3.txt").write_text("content3")
-        (path / "test.json").write_text('{"key": "value"}')
-        yield path
-
-
 class TestFileResource:
     """Test FileResource functionality."""
 
     def test_file_resource_creation(self, temp_file: Path):
         """Test creating a FileResource."""
         resource = FileResource(
-            uri=f"file://{temp_file}",
+            uri=FileUrl(temp_file.as_uri()),
             name="test",
             description="test file",
-            mime_type="text/plain",
             path=temp_file,
         )
-        assert str(resource.uri) == f"file://{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"
+        assert resource.mime_type == "text/plain"  # default
         assert resource.path == temp_file
-
-    def test_file_resource_relative_path_error(self):
-        """Test FileResource rejects relative paths."""
-        with pytest.raises(ValueError, match="Path must be absolute"):
-            FileResource(
-                uri="file://test.txt",
-                name="test",
-                path=Path("test.txt"),
-            )
+        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=f"file://{temp_file}",
+            uri=FileUrl(f"file://{temp_file}"),
             name="test",
-            path=str(temp_file),
+            path=Path(str(temp_file)),
         )
         assert isinstance(resource.path, Path)
         assert resource.path.is_absolute()
 
-    async def test_file_resource_read(self, temp_file: Path):
-        """Test reading a FileResource."""
+    async def test_read_text_file(self, temp_file: Path):
+        """Test reading a text file."""
         resource = FileResource(
-            uri=f"file://{temp_file}",
+            uri=FileUrl(f"file://{temp_file}"),
             name="test",
             path=temp_file,
         )
-        content = await resource.read()
-        assert content == "test content"
+        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_file_resource_read_missing_file(self, temp_file: Path):
-        """Test reading a non-existent file."""
-        temp_file.unlink()
+    async def test_read_binary_file(self, temp_file: Path):
+        """Test reading a file as binary."""
         resource = FileResource(
-            uri=f"file://{temp_file}",
+            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(FileNotFoundError):
+        with pytest.raises(ResourceError, match="Error reading file"):
             await resource.read()
 
-    async def test_file_resource_read_permission_error(self, temp_file: Path):
+    @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=f"file://{temp_file}",
+                uri=FileUrl(temp_file.as_uri()),
                 name="test",
                 path=temp_file,
             )
-            with pytest.raises(PermissionError):
+            with pytest.raises(ResourceError, match="Error reading file"):
                 await resource.read()
         finally:
             temp_file.chmod(0o644)  # Restore permissions
diff --git a/tests/resources/test_function_resources.py b/tests/resources/test_function_resources.py
index 7de95a0c6..8c44221c9 100644
--- a/tests/resources/test_function_resources.py
+++ b/tests/resources/test_function_resources.py
@@ -1,4 +1,8 @@
-from fastmcp.resources import FunctionResource
+import pytest
+from pydantic import AnyUrl, BaseModel
+
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.resources.resource import ResourceContent
 
 
 class TestFunctionResource:
@@ -7,32 +11,324 @@ class TestFunctionResource:
     def test_function_resource_creation(self):
         """Test creating a FunctionResource."""
 
-        def my_func(x: str = "") -> str:
-            return f"Content: {x}"
+        def my_func() -> str:
+            return "test content"
 
         resource = FunctionResource(
-            uri="fn://test",
+            uri=AnyUrl("fn://test"),
             name="test",
             description="test function",
-            mime_type="text/plain",
-            func=my_func,
+            fn=my_func,
         )
         assert str(resource.uri) == "fn://test"
         assert resource.name == "test"
         assert resource.description == "test function"
-        assert resource.mime_type == "text/plain"
-        assert resource.func == my_func
+        assert resource.mime_type == "text/plain"  # default
+        assert resource.fn == my_func
 
-    async def test_function_resource_read(self):
-        """Test reading a FunctionResource with no parameters."""
+    async def test_read_text(self):
+        """Test reading text from a FunctionResource."""
 
-        def my_func() -> str:
-            return "test content"
+        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_raises_type_error(self):
+        """Returning dict from read() raises TypeError - use ResourceResult."""
+
+        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() 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_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_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="fn://test",
+            uri=AnyUrl("function://test"),
             name="test",
-            func=my_func,
+            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.mimeType == "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.mimeType == "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.mimeType == "text/plain"
+
+        binary_rc = ResourceContent(content=b"binary")
+        binary_mcp = binary_rc.to_mcp_resource_contents("resource://test")
+        assert binary_mcp.mimeType == "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(),
         )
-        content = await resource.read()
-        assert content == "test content"
+        assert results == ["done", "done", "done"]
diff --git a/tests/resources/test_resource_manager.py b/tests/resources/test_resource_manager.py
deleted file mode 100644
index 3bff7c7c2..000000000
--- a/tests/resources/test_resource_manager.py
+++ /dev/null
@@ -1,242 +0,0 @@
-import logging
-import pytest
-from pathlib import Path
-from tempfile import NamedTemporaryFile, TemporaryDirectory
-
-from fastmcp.resources import FileResource, FunctionResource, ResourceManager
-
-
-@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
-
-
-@pytest.fixture
-def temp_file_no_cleanup():
-    """Create a temporary file for testing.
-
-    File is NOT automatically cleaned up - tests must handle cleanup.
-    """
-    content = "test content"
-    with NamedTemporaryFile(mode="w", delete=False) as f:
-        f.write(content)
-        path = Path(f.name).resolve()
-    return path
-
-
-@pytest.fixture
-def temp_dir():
-    """Create a temporary directory for testing."""
-    with TemporaryDirectory() as d:
-        yield Path(d).resolve()
-
-
-class TestResourceValidation:
-    def test_resource_uri_validation(self):
-        def dummy_func() -> str:
-            return "data"
-
-        # Valid URI
-        resource = FunctionResource(
-            uri="http://example.com/data",
-            name="test",
-            func=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="invalid",
-                name="test",
-                func=dummy_func,
-            )
-
-        # Missing host
-        with pytest.raises(ValueError, match="Input should be a valid URL"):
-            FunctionResource(
-                uri="http://",
-                name="test",
-                func=dummy_func,
-            )
-
-
-class TestResourceManagerAdd:
-    """Test ResourceManager add functionality."""
-
-    def test_add_file_resource(self, temp_file: Path):
-        """Test adding a file resource."""
-        manager = ResourceManager()
-        resource = FileResource(
-            uri=f"file://{temp_file}",
-            name="test",
-            description="test file",
-            mime_type="text/plain",
-            path=temp_file,
-        )
-        added = manager.add_resource(resource)
-        assert isinstance(added, FileResource)
-        assert str(added.uri) == f"file://{temp_file}"
-        assert added.name == "test"
-        assert added.description == "test file"
-        assert added.mime_type == "text/plain"
-        assert added.path == temp_file
-
-    def test_add_file_resource_relative_path_error(self):
-        """Test ResourceManager rejects relative paths."""
-        with pytest.raises(ValueError, match="Path must be absolute"):
-            FileResource(
-                uri="file:///test.txt",
-                name="test",
-                path=Path("test.txt"),
-            )
-
-    def test_warn_on_duplicate_resources(self, caplog):
-        """Test warning on duplicate resources."""
-        caplog.set_level(logging.WARNING, logger="mcp")
-        manager = ResourceManager()
-        resource = FileResource(
-            uri="file:///test.txt",
-            name="test",
-            path=Path("/test.txt"),
-        )
-        manager.add_resource(resource)
-        manager.add_resource(resource)
-        assert "Resource already exists: file:///test.txt" in caplog.text
-
-    def test_disable_warn_on_duplicate_resources(self, caplog):
-        """Test disabling warning on duplicate resources."""
-        caplog.set_level(logging.WARNING, logger="mcp")
-        manager = ResourceManager()
-        resource = FileResource(
-            uri="file:///test.txt",
-            name="test",
-            path=Path("/test.txt"),
-        )
-        manager.add_resource(resource)
-        manager.warn_on_duplicate_resources = False
-        manager.add_resource(resource)
-        assert "Resource already exists: file:///test.txt" not in caplog.text
-
-
-class TestResourceManagerRead:
-    """Test ResourceManager read functionality."""
-
-    def test_get_resource_unknown_uri(self):
-        """Test getting a non-existent resource."""
-        manager = ResourceManager()
-        with pytest.raises(ValueError, match="Unknown resource"):
-            manager.get_resource("file://unknown")
-
-    def test_get_resource(self, temp_file: Path):
-        """Test getting a resource by URI."""
-        manager = ResourceManager()
-        resource = FileResource(
-            uri=f"file://{temp_file}",
-            name="test",
-            path=temp_file,
-        )
-        added = manager.add_resource(resource)
-        retrieved = manager.get_resource(added.uri)
-        assert retrieved == added
-
-    async def test_resource_read_through_manager(self, temp_file: Path):
-        """Test reading a resource through the manager."""
-        manager = ResourceManager()
-        resource = FileResource(
-            uri=f"file://{temp_file}",
-            name="test",
-            path=temp_file,
-        )
-        added = manager.add_resource(resource)
-        retrieved = manager.get_resource(added.uri)
-        assert retrieved is not None
-        content = await retrieved.read()
-        assert content == "test content"
-
-    async def test_resource_read_error_through_manager(
-        self, temp_file_no_cleanup: Path
-    ):
-        """Test error handling when reading through manager."""
-        manager = ResourceManager()
-        # Create resource while file exists
-        resource = FileResource(
-            uri=f"file://{temp_file_no_cleanup}",
-            name="test",
-            path=temp_file_no_cleanup,
-        )
-        added = manager.add_resource(resource)
-        retrieved = manager.get_resource(added.uri)
-        assert retrieved is not None
-
-        # Delete file and verify read fails
-        temp_file_no_cleanup.unlink()
-        with pytest.raises(FileNotFoundError):
-            await retrieved.read()
-
-
-class TestResourceManagerList:
-    """Test ResourceManager list functionality."""
-
-    def test_list_resources(self, temp_file: Path):
-        """Test listing all resources."""
-        manager = ResourceManager()
-        resource = FileResource(
-            uri=f"file://{temp_file}",
-            name="test",
-            path=temp_file,
-        )
-        added = manager.add_resource(resource)
-        resources = manager.list_resources()
-        assert len(resources) == 1
-        assert resources[0] == added
-
-    def test_list_resources_duplicate(self, temp_file: Path):
-        """Test that adding the same resource twice only stores it once."""
-        manager = ResourceManager()
-        resource = FileResource(
-            uri=f"file://{temp_file}",
-            name="test",
-            path=temp_file,
-        )
-        resource1 = manager.add_resource(resource)
-        resource2 = manager.add_resource(resource)
-
-        resources = manager.list_resources()
-        assert len(resources) == 1
-        assert resources[0] == resource1
-        assert resource1 == resource2
-
-    def test_list_multiple_resources(self, temp_file: Path, temp_file_no_cleanup: Path):
-        """Test listing multiple different resources."""
-        manager = ResourceManager()
-        resource1 = FileResource(
-            uri=f"file://{temp_file}",
-            name="test1",
-            path=temp_file,
-        )
-        resource2 = FileResource(
-            uri=f"file://{temp_file_no_cleanup}",
-            name="test2",
-            path=temp_file_no_cleanup,
-        )
-        added1 = manager.add_resource(resource1)
-        added2 = manager.add_resource(resource2)
-
-        resources = manager.list_resources()
-        assert len(resources) == 2
-        assert resources[0] == added1
-        assert resources[1] == added2
-        assert added1 != added2
diff --git a/tests/resources/test_resource_template.py b/tests/resources/test_resource_template.py
new file mode 100644
index 000000000..1f43ce1d5
--- /dev/null
+++ b/tests/resources/test_resource_template.py
@@ -0,0 +1,749 @@
+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 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"
diff --git a/tests/resources/test_resource_template_meta.py b/tests/resources/test_resource_template_meta.py
new file mode 100644
index 000000000..b08ef3667
--- /dev/null
+++ b/tests/resources/test_resource_template_meta.py
@@ -0,0 +1,25 @@
+from fastmcp.resources import ResourceTemplate
+
+
+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()
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 000000000..9d7f86b57
--- /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 000000000..7936c8890
--- /dev/null
+++ b/tests/resources/test_resources.py
@@ -0,0 +1,356 @@
+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.mimeType == "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.mimeType == "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_raises_type_error(self):
+        """Dict input raises TypeError - must use ResourceContent for serialization."""
+        with pytest.raises(TypeError, match="must be str, bytes, or list"):
+            ResourceResult({"page": 1, "total": 100})  # type: ignore[arg-type]
+
+    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]
+
+    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]
+
+    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"}
diff --git a/tests/resources/test_standalone_decorator.py b/tests/resources/test_standalone_decorator.py
new file mode 100644
index 000000000..9b4218ebf
--- /dev/null
+++ b/tests/resources/test_standalone_decorator.py
@@ -0,0 +1,154 @@
+"""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]
+            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"}
+
+    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.uriTemplate == "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/server/__init__.py b/tests/server/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/server/auth/__init__.py b/tests/server/auth/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/server/auth/oauth_proxy/__init__.py b/tests/server/auth/oauth_proxy/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/server/auth/oauth_proxy/conftest.py b/tests/server/auth/oauth_proxy/conftest.py
new file mode 100644
index 000000000..802ca2348
--- /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]
+        """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 000000000..7a8a9b9e7
--- /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
+        )
+
+        # 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 000000000..b865b4336
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_client_registration.py
@@ -0,0 +1,43 @@
+"""Tests for OAuth proxy client registration (DCR)."""
+
+from mcp.shared.auth import OAuthClientInformationFull
+from pydantic import AnyUrl
+
+
+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_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
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 000000000..0b88a0ae5
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_config.py
@@ -0,0 +1,452 @@
+"""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 "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_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 000000000..39c4592e8
--- /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 000000000..b605e50fd
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_oauth_proxy.py
@@ -0,0 +1,102 @@
+"""Tests for OAuth proxy initialization and configuration."""
+
+import httpx
+from key_value.aio.stores.memory import MemoryStore
+from starlette.applications import Starlette
+
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+
+
+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.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"]
+
+    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 support when enabled."""
+        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
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 000000000..b7e16431f
--- /dev/null
+++ b/tests/server/auth/oauth_proxy/test_tokens.py
@@ -0,0 +1,503 @@
+"""Tests for OAuth proxy token endpoint and handling."""
+
+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 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,
+    ClientCode,
+)
+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,
+            )
+
+
+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 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)
+        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)
+        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
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 000000000..6f174aec2
--- /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 000000000..e69de29bb
diff --git a/tests/server/auth/providers/test_auth0.py b/tests/server/auth/providers/test_auth0.py
new file mode 100644
index 000000000..3b1b5cd8f
--- /dev/null
+++ b/tests/server/auth/providers/test_auth0.py
@@ -0,0 +1,98 @@
+"""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.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 000000000..59d51e4c8
--- /dev/null
+++ b/tests/server/auth/providers/test_aws.py
@@ -0,0 +1,137 @@
+"""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.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_defaults_audience_to_client_id(self):
+        """Test Cognito token verifier enforces the configured client ID by default."""
+        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.audience == "test_client"
+
+    def test_token_verifier_supports_audience_override(self):
+        """Test Cognito token verifier still allows explicit audience overrides."""
+        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.audience == "custom-audience"
+
+
+# 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 000000000..3d01c926d
--- /dev/null
+++ b/tests/server/auth/providers/test_azure.py
@@ -0,0 +1,736 @@
+"""Tests for Azure (Microsoft Entra) OAuth provider."""
+
+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.providers.azure import AzureProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+
+@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.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."""
+        from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+        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"
+        # Scopes are stored unprefixed for token validation
+        # (Azure returns unprefixed scopes like ".default" in JWT tokens)
+        assert verifier.required_scopes == [".default"]
+
+    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_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(
+        self, memory_storage: MemoryStore
+    ):
+        """Test behavior with empty scopes list."""
+        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,
+        )
+
+        # Empty scopes should still add OIDC scopes (not User.Read)
+        result = provider._prepare_scopes_for_upstream_refresh([])
+
+        assert "User.Read" not in result  # Not OIDC
+        assert "openid" in result
+        assert "offline_access" in result  # Auto-included
+        assert len(result) == 2  # Only OIDC scopes: openid + offline_access
+
+    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
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 000000000..9f90def35
--- /dev/null
+++ b/tests/server/auth/providers/test_azure_scopes.py
@@ -0,0 +1,690 @@
+"""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.providers.azure import (
+    OIDC_SCOPES,
+    AzureJWTVerifier,
+    AzureProvider,
+)
+from fastmcp.server.auth.providers.jwt import RSAKeyPair
+
+
+@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_results_in_no_validation(
+        self, memory_storage: MemoryStore
+    ):
+        """Test that if all required_scopes are OIDC, no scope validation occurs."""
+        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=["openid", "profile"],
+            jwt_signing_key="test-secret",
+            client_storage=memory_storage,
+        )
+
+        # Token validator should have empty required scopes (all were OIDC)
+        assert provider._token_validator.required_scopes == []
+
+    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"
+        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="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
+
+    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)
diff --git a/tests/server/auth/providers/test_descope.py b/tests/server/auth/providers/test_descope.py
new file mode 100644
index 000000000..7dcfc477f
--- /dev/null
+++ b/tests/server/auth/providers/test_descope.py
@@ -0,0 +1,238 @@
+"""Tests for Descope OAuth provider."""
+
+import os
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+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):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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 000000000..d40e180b1
--- /dev/null
+++ b/tests/server/auth/providers/test_discord.py
@@ -0,0 +1,127 @@
+"""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.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 000000000..fe2bbf031
--- /dev/null
+++ b/tests/server/auth/providers/test_github.py
@@ -0,0 +1,140 @@
+"""Unit tests for GitHub OAuth provider."""
+
+from unittest.mock import 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.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"]
+
+
+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."""
+        from unittest.mock import AsyncMock
+
+        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"
diff --git a/tests/server/auth/providers/test_google.py b/tests/server/auth/providers/test_google.py
new file mode 100644
index 000000000..0f6bd6c89
--- /dev/null
+++ b/tests/server/auth/providers/test_google.py
@@ -0,0 +1,136 @@
+"""Tests for Google OAuth provider."""
+
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+
+from fastmcp.server.auth.providers.google import GoogleProvider
+
+
+@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.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"
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 000000000..fa6126183
--- /dev/null
+++ b/tests/server/auth/providers/test_http_client.py
@@ -0,0 +1,368 @@
+"""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 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."""
+        from authlib.jose import JsonWebKey
+
+        # Build a JWKS response from the RSA key pair
+        public_key_obj = JsonWebKey.import_key(rsa_key_pair.public_key)
+        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_introspection.py b/tests/server/auth/providers/test_introspection.py
new file mode 100644
index 000000000..793570987
--- /dev/null
+++ b/tests/server/auth/providers/test_introspection.py
@@ -0,0 +1,983 @@
+"""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 verifier._cache_ttl == 0  # Disabled by default
+        assert verifier._max_cache_size == 10000
+
+    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._max_cache_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 verifier._cache_ttl == 0
+
+        # 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 verifier2._cache_ttl == 0
+
+    async def test_cache_disabled_with_zero_or_negative_max_size(
+        self, httpx_mock: HTTPXMock
+    ):
+        """Test that cache is disabled when max_cache_size is 0 or negative."""
+        # Add two responses for the two verifiers
+        for _ in range(2):
+            httpx_mock.add_response(
+                url="https://auth.example.com/oauth/introspect",
+                method="POST",
+                json={
+                    "active": True,
+                    "client_id": "user-123",
+                    "scope": "read",
+                },
+            )
+
+        # Zero max_cache_size should disable caching (not raise StopIteration)
+        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"
+
+        # Negative max_cache_size should also disable caching
+        verifier2 = 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,
+        )
+        result2 = await verifier2.verify_token("test-token")
+        assert result2 is not None
+
+    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._hash_token("test-token")
+        hash2 = verifier_with_cache._hash_token("test-token")
+        hash3 = verifier_with_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._hash_token("test-token")
+        entry = verifier_with_cache._cache[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._hash_token("test-token")
+        verifier._cache[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) == 2
+
+        # Third token should evict the oldest entry
+        await verifier.verify_token("token-2")
+        assert len(verifier._cache) == 2
+
+        # token-0 should have been evicted (FIFO)
+        hash_0 = verifier._hash_token("token-0")
+        assert hash_0 not in verifier._cache
+
+
+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_propelauth.py b/tests/server/auth/providers/test_propelauth.py
new file mode 100644
index 000000000..9d70496fc
--- /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 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._max_cache_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):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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 000000000..a47840682
--- /dev/null
+++ b/tests/server/auth/providers/test_scalekit.py
@@ -0,0 +1,220 @@
+"""Tests for Scalekit OAuth provider."""
+
+import httpx
+import pytest
+
+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):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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 000000000..daa2e4a01
--- /dev/null
+++ b/tests/server/auth/providers/test_supabase.py
@@ -0,0 +1,211 @@
+"""Tests for Supabase Auth provider."""
+
+from collections.abc import Generator
+
+import httpx
+import pytest
+
+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]
+            )
+
+    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):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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 000000000..767f9b329
--- /dev/null
+++ b/tests/server/auth/providers/test_workos.py
@@ -0,0 +1,219 @@
+"""Tests for WorkOS OAuth provider."""
+
+from urllib.parse import urlparse
+
+import httpx
+import pytest
+from key_value.aio.stores.memory import MemoryStore
+from pytest_httpx import HTTPXMock
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+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.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_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
+    ):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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 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 000000000..ab6ab36cf
--- /dev/null
+++ b/tests/server/auth/test_auth_provider.py
@@ -0,0 +1,105 @@
+import re
+
+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
+
+
+class TestAuthProviderBase:
+    """Test suite for base AuthProvider behaviors that apply to all auth providers."""
+
+    @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 000000000..f6e86aeef
--- /dev/null
+++ b/tests/server/auth/test_authorization.py
@@ -0,0 +1,812 @@
+"""Tests for authorization checks and AuthMiddleware."""
+
+from unittest.mock import Mock
+
+import mcp.types as mcp_types
+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
+
+# =============================================================================
+# 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
+
+
+# =============================================================================
+# 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 MCP handler layer.
+
+    These tests call _list_tools_mcp() which applies middleware during list,
+    simulating what happens when a 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
+        result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+        assert len(result.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:
+            result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+            assert len(result.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:
+            result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+            assert len(result.tools) == 0
+        finally:
+            auth_context_var.reset(tok)
+
+        # Token with api scope
+        token = make_token(scopes=["api"])
+        tok = set_token(token)
+        try:
+            result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+            assert len(result.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
+        result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+        assert len(result.tools) == 1
+        assert result.tools[0].name == "public_tool"
+
+        # Token with admin scope - both allowed
+        token = make_token(scopes=["admin"])
+        tok = set_token(token)
+        try:
+            result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+            assert len(result.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"
+
+        result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+        assert [tool.name for tool in result.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"
+
+        result = await mcp._list_resources_mcp(mcp_types.ListResourcesRequest())
+        assert [str(resource.uri) for resource in result.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
+
+        result = await mcp._list_resource_templates_mcp(
+            mcp_types.ListResourceTemplatesRequest()
+        )
+        assert [template.uriTemplate for template in result.resourceTemplates] == [
+            "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"
+
+        result = await mcp._list_prompts_mcp(mcp_types.ListPromptsRequest())
+        assert [prompt.name for prompt in result.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
+        result = await mcp._list_tools_mcp(__import__("mcp").types.ListToolsRequest())
+        assert len(result.tools) == 0
+
+        # With token containing "api" scope, tool is visible
+        token = make_token(scopes=["api"])
+        tok = set_token(token)
+        try:
+            result = await mcp._list_tools_mcp(
+                __import__("mcp").types.ListToolsRequest()
+            )
+            assert len(result.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."""
+        from fastmcp.tools.tool_transform import TransformedTool
+
+        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."""
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool(x: int) -> str:
+            return str(x)
+
+        # Add transformation
+        mcp.add_tool_transformation(
+            "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."""
+        from fastmcp.tools.tool_transform import ToolTransformConfig
+
+        mcp = FastMCP()
+
+        @mcp.tool(auth=require_scopes("test"))
+        def protected_tool(x: int) -> str:
+            return str(x)
+
+        # Add transformation
+        mcp.add_tool_transformation(
+            "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)
diff --git a/tests/server/auth/test_cimd.py b/tests/server/auth/test_cimd.py
new file mode 100644
index 000000000..3ed99857a
--- /dev/null
+++ b/tests/server/auth/test_cimd.py
@@ -0,0 +1,542 @@
+"""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
+            )
+        # 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
+            )
+        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
+            )
+        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")
+
+
+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 000000000..995854ba2
--- /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 000000000..4cf2c6efb
--- /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 000000000..f7463be36
--- /dev/null
+++ b/tests/server/auth/test_enhanced_error_responses.py
@@ -0,0 +1,370 @@
+"""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", mimeType="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_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 without Authorization header
+            response = client.post("/mcp")
+
+            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 WWW-Authenticate header format matches SDK."""
+        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:
+            response = client.post("/mcp")
+
+            assert response.status_code == 401
+            www_auth = response.headers["www-authenticate"]
+
+            # Should follow Bearer challenge format
+            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 000000000..79bbb02de
--- /dev/null
+++ b/tests/server/auth/test_jwt_issuer.py
@@ -0,0 +1,287 @@
+"""Unit tests for JWT issuer and token encryption."""
+
+import base64
+import time
+
+import pytest
+from authlib.jose.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)
+        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)
+        assert "upstream_claims" in payload
+        assert payload["upstream_claims"]["sub"] == "user-123"
+        assert payload["upstream_claims"]["name"] == "Test User"
+        assert payload["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 000000000..042df9af8
--- /dev/null
+++ b/tests/server/auth/test_jwt_provider.py
@@ -0,0 +1,611 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+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)
+        """
+        import time
+
+        from authlib.jose import JsonWebToken
+
+        # Create header
+        header = {"alg": algorithm}
+
+        # Create payload
+        payload = {
+            "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
+        jwt_lib = JsonWebToken([algorithm])
+        token_bytes = jwt_lib.encode(header, payload, self.secret)
+
+        return token_bytes.decode("utf-8")
+
+
+@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 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."""
+        from authlib.jose import JsonWebKey
+
+        # Create JWK from the RSA public key
+        jwk = JsonWebKey.import_key(rsa_key_pair.public_key)
+        jwk_data: JWKData = jwk.as_dict()
+        jwk_data["kid"] = "test-key-1"
+        jwk_data["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"] = [  # type: ignore[typeddict-item]
+            {
+                "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 000000000..c88665c87
--- /dev/null
+++ b/tests/server/auth/test_jwt_provider_bearer.py
@@ -0,0 +1,610 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import httpx
+import pytest
+
+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):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url, auth=BearerAuth("invalid")) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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(httpx.HTTPStatusError) as exc_info:
+            async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                tools = await client.list_tools()  # noqa: F841
+        assert isinstance(exc_info.value, httpx.HTTPStatusError)
+        assert exc_info.value.response.status_code == 401
+        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:
+            with pytest.raises(httpx.HTTPStatusError) as exc_info:
+                async with Client(mcp_server_url, auth=BearerAuth(token)) as client:
+                    tools = await client.list_tools()  # noqa: F841
+            # JWTVerifier returns 401 when verify_token returns None (invalid token)
+            # This is correct behavior - when TokenVerifier.verify_token returns None,
+            # it indicates the token is invalid (not just insufficient permissions)
+            assert isinstance(exc_info.value, httpx.HTTPStatusError)
+            assert exc_info.value.response.status_code == 401
+            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 000000000..369da86a5
--- /dev/null
+++ b/tests/server/auth/test_multi_auth.py
@@ -0,0 +1,407 @@
+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_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_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 000000000..7a65df297
--- /dev/null
+++ b/tests/server/auth/test_oauth_consent_flow.py
@@ -0,0 +1,659 @@
+"""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",
+    )
+
+
+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 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):
+        """Verify denying consent sets signed cookie and redirects with error."""
+        client_redirect = "http://localhost:5002/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https, "client-b", client_redirect)
+        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
+            # 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
+    ):
+        """Verify approving consent sets signed cookie and redirects to upstream."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-c", "http://localhost:5003/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)
+            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):
+        """Verify tampered approval cookie is ignored and consent page shown."""
+        txn_id, _ = await _start_flow(
+            oauth_proxy_https, "client-d", "http://localhost:5004/callback"
+        )
+        app = Starlette(routes=oauth_proxy_https.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}", 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):
+        """Verify valid approval cookie auto-approves and redirects to upstream."""
+        client_id = "client-e"
+        redirect = "http://localhost:5005/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https.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"
+            approved_cookie = m.group(1)
+
+            # Start a new flow for the same client and redirect
+            new_txn, _ = await _start_flow(oauth_proxy_https, client_id, redirect)
+            # Should auto-redirect to upstream when visiting consent due to cookie
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r2 = c.get(f"/consent?txn_id={new_txn}", follow_redirects=False)
+            assert r2.status_code in (302, 303)
+            assert r2.headers.get("location", "").startswith(
+                "https://github.com/login/oauth/authorize"
+            )
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 000000000..bd394db74
--- /dev/null
+++ b/tests/server/auth/test_oauth_consent_page.py
@@ -0,0 +1,696 @@
+"""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",
+    )
+
+
+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_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):
+        """Auto-approve path (previously approved client) must also set the binding cookie."""
+        client_id = "client-autobinding"
+        redirect = "http://localhost:6002/callback"
+        txn_id, _ = await _start_flow(oauth_proxy_https, client_id, redirect)
+        app = Starlette(routes=oauth_proxy_https.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
+            new_txn, _ = await _start_flow(oauth_proxy_https, client_id, redirect)
+            c.cookies.set("__Host-MCP_APPROVED_CLIENTS", approved_cookie)
+            r2 = c.get(f"/consent?txn_id={new_txn}", 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 000000000..93f4a2308
--- /dev/null
+++ b/tests/server/auth/test_oauth_mounting.py
@@ -0,0 +1,384 @@
+"""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"
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 000000000..47ecfbe8d
--- /dev/null
+++ b/tests/server/auth/test_oauth_proxy_redirect_validation.py
@@ -0,0 +1,401 @@
+"""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]
+        return {"sub": "test-user"}
+
+
+class TestProxyDCRClient:
+    """Test ProxyDCRClient redirect URI validation."""
+
+    def test_default_allows_all(self):
+        """Test that default configuration allows all URIs for DCR compatibility."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+        )
+
+        # All URIs should be allowed by default for DCR compatibility
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:3000")) == AnyUrl(
+            "http://localhost:3000"
+        )
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:8080")) == AnyUrl(
+            "http://localhost:8080"
+        )
+        assert client.validate_redirect_uri(AnyUrl("http://127.0.0.1:3000")) == AnyUrl(
+            "http://127.0.0.1:3000"
+        )
+        assert client.validate_redirect_uri(AnyUrl("http://example.com")) == AnyUrl(
+            "http://example.com"
+        )
+        assert client.validate_redirect_uri(
+            AnyUrl("https://claude.ai/api/mcp/auth_callback")
+        ) == AnyUrl("https://claude.ai/api/mcp/auth_callback")
+
+    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 - will fallback to base validation
+        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_allows_none(self):
+        """Test that empty pattern list allows no URIs."""
+        client = ProxyDCRClient(
+            client_id="test",
+            client_secret="secret",
+            redirect_uris=[AnyUrl("http://localhost:3000")],
+            allowed_redirect_uri_patterns=[],
+        )
+
+        # Nothing should be allowed (except the pre-registered redirect_uris via fallback)
+        # Pre-registered URI should work via fallback to base validation
+        assert client.validate_redirect_uri(AnyUrl("http://localhost:3000"))
+
+        # Non-registered URIs should be rejected
+        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_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_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_allows_all(self):
+        """Test that OAuth proxy defaults to allowing all URIs for DCR compatibility."""
+        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 should store None for default (allow all)
+        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 000000000..0273a368c
--- /dev/null
+++ b/tests/server/auth/test_oauth_proxy_storage.py
@@ -0,0 +1,212 @@
+"""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,
+                "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 000000000..e3dd95e1c
--- /dev/null
+++ b/tests/server/auth/test_oidc_proxy.py
@@ -0,0 +1,878 @@
+"""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.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="Missing required client secret"):
+                OIDCProxy(
+                    config_url=TEST_CONFIG_URL,
+                    client_id=TEST_CLIENT_ID,
+                    client_secret=None,  # type: ignore
+                    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",
+            }
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 000000000..57083d50d
--- /dev/null
+++ b/tests/server/auth/test_oidc_proxy_token.py
@@ -0,0 +1,331 @@
+"""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",
+            ]
diff --git a/tests/server/auth/test_redirect_validation.py b/tests/server/auth/test_redirect_validation.py
new file mode 100644
index 000000000..10945d2fb
--- /dev/null
+++ b/tests/server/auth/test_redirect_validation.py
@@ -0,0 +1,200 @@
+"""Tests for redirect URI validation in OAuth flows."""
+
+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:*"])
+
+    def test_default_allows_all(self):
+        """Test that None (default) allows all URIs for DCR compatibility."""
+        # All URIs should be allowed when None is provided (DCR compatibility)
+        assert validate_redirect_uri("http://localhost:3000", None)
+        assert validate_redirect_uri("http://127.0.0.1:8080", None)
+        assert validate_redirect_uri("http://example.com", None)
+        assert validate_redirect_uri("https://app.example.com", None)
+        assert validate_redirect_uri("https://claude.ai/api/mcp/auth_callback", None)
+
+    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 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 000000000..5d56c5b5c
--- /dev/null
+++ b/tests/server/auth/test_remote_auth_provider.py
@@ -0,0 +1,542 @@
+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"
+        )
+
+
+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 000000000..79cf926a0
--- /dev/null
+++ b/tests/server/auth/test_ssrf_protection.py
@@ -0,0 +1,447 @@
+"""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
+
+
+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")
+
+
+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 000000000..2f07a674f
--- /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 000000000..e69de29bb
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 000000000..58d103635
--- /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 000000000..d0a757be4
--- /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 000000000..cb3600527
--- /dev/null
+++ b/tests/server/http/test_http_auth_middleware.py
@@ -0,0 +1,94 @@
+import pytest
+from mcp.server.auth.middleware.bearer_auth import RequireAuthMiddleware
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from fastmcp.server import FastMCP
+from fastmcp.server.auth.providers.jwt import JWTVerifier, RSAKeyPair
+from fastmcp.server.http import create_streamable_http_app
+
+
+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
diff --git a/tests/server/http/test_http_dependencies.py b/tests/server/http/test_http_dependencies.py
new file mode 100644
index 000000000..e637af269
--- /dev/null
+++ b/tests/server/http/test_http_dependencies.py
@@ -0,0 +1,168 @@
+import json
+
+import pytest
+from mcp.types import TextContent, TextResourceContents
+
+from fastmcp.client import Client
+from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+from fastmcp.server.dependencies import 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"
diff --git a/tests/server/http/test_http_middleware.py b/tests/server/http/test_http_middleware.py
new file mode 100644
index 000000000..3d2ad1903
--- /dev/null
+++ b/tests/server/http/test_http_middleware.py
@@ -0,0 +1,234 @@
+"""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
+    # TODO(ty): remove when Starlette Middleware typing is supported
+    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
+    # TODO(ty): remove when Starlette Middleware typing is supported
+    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
+    # TODO(ty): remove when Starlette Middleware typing is supported
+    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
+    # TODO(ty): remove when Starlette Middleware typing is supported
+    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
+    # TODO(ty): remove when Starlette Middleware typing is supported
+    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_stale_access_token.py b/tests/server/http/test_stale_access_token.py
new file mode 100644
index 000000000..34f271e79
--- /dev/null
+++ b/tests/server/http/test_stale_access_token.py
@@ -0,0 +1,159 @@
+"""
+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 mcp.server.lowlevel.server import request_ctx
+from mcp.shared.context import RequestContext
+from starlette.requests import Request
+
+from fastmcp.server.auth import AccessToken
+from fastmcp.server.dependencies import get_access_token
+
+
+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)
+
+        # Create a mock RequestContext with the request
+        mock_request_context = MagicMock(spec=RequestContext)
+        mock_request_context.request = mock_request
+
+        # Set up the context vars:
+        # - auth_context_var has STALE token
+        # - request_ctx has request with FRESH token
+        auth_token = auth_context_var.set(stale_user)
+        request_token = request_ctx.set(mock_request_context)
+
+        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)
+            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)
+        mock_request_context = MagicMock(spec=RequestContext)
+        mock_request_context.request = mock_request
+
+        auth_token = auth_context_var.set(user)
+        request_token = request_ctx.set(mock_request_context)
+
+        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)
+            request_ctx.reset(request_token)
diff --git a/tests/server/middleware/__init__.py b/tests/server/middleware/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/server/middleware/test_caching.py b/tests/server/middleware/test_caching.py
new file mode 100644
index 000000000..027b29959
--- /dev/null
+++ b/tests/server/middleware/test_caching.py
@@ -0,0 +1,673 @@
+"""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.function_prompt import FunctionPrompt
+from fastmcp.prompts.prompt import Message, Prompt
+from fastmcp.resources.resource import Resource
+from fastmcp.server.middleware.caching import (
+    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.tool 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=2, hit=1, 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=2, hit=1, 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
+
+
+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=AnyUrl("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)
diff --git a/tests/server/middleware/test_dereference.py b/tests/server/middleware/test_dereference.py
new file mode 100644
index 000000000..0ababd7de
--- /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].inputSchema
+        # $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].inputSchema
+        # $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].inputSchema
+        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.inputSchema
+        if tool.outputSchema is not None:
+            assert "$defs" not in tool.outputSchema
+
+    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].inputSchema
+        # 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 000000000..3bac578d7
--- /dev/null
+++ b/tests/server/middleware/test_error_handling.py
@@ -0,0 +1,638 @@
+"""Tests for error handling middleware."""
+
+import logging
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from mcp import McpError
+
+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()
+        from mcp.types import ErrorData
+
+        error = McpError(ErrorData(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_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."""
+    from fastmcp import FastMCP
+
+    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."""
+        from fastmcp.client import Client
+
+        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."""
+        from fastmcp.client import Client
+
+        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."""
+        from fastmcp.client import Client
+
+        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."""
+        from fastmcp.client import Client
+
+        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."""
+        from fastmcp.client import Client
+
+        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_middleware_with_transient_failures(
+        self, error_handling_server, caplog
+    ):
+        """Test retry middleware with operations that have transient failures."""
+        from fastmcp.client import Client
+
+        # Configure retry middleware to retry connection errors
+        error_handling_server.add_middleware(
+            RetryMiddleware(
+                max_retries=3,
+                base_delay=0.01,  # Very short delay for testing
+                retry_exceptions=(ConnectionError,),
+            )
+        )
+
+        with caplog.at_level(logging.WARNING):
+            async with Client(error_handling_server) as client:
+                # This operation fails intermittently - try several times
+                success_count = 0
+                for _ in range(5):
+                    try:
+                        await client.call_tool(
+                            "intermittent_operation", {"fail_rate": 0.7}
+                        )
+                        success_count += 1
+                    except Exception:
+                        pass  # Some failures expected even with retries
+
+        # Should have some retry log messages
+        # Note: Retry logs might not appear if the underlying errors are wrapped by FastMCP
+        # The key is that some operations should succeed due to retries
+
+    async def test_retry_middleware_with_permanent_failures(
+        self, error_handling_server
+    ):
+        """Test that retry middleware doesn't retry non-retryable errors."""
+        from fastmcp.client import Client
+
+        # Configure retry middleware for connection errors only
+        error_handling_server.add_middleware(
+            RetryMiddleware(
+                max_retries=3, base_delay=0.01, retry_exceptions=(ConnectionError,)
+            )
+        )
+
+        async with Client(error_handling_server) as client:
+            # Value errors should not be retried
+            with pytest.raises(Exception):
+                await client.call_tool("failing_operation", {"error_type": "value"})
+
+        # 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."""
+        from fastmcp.client import Client
+
+        # 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 000000000..7441511eb
--- /dev/null
+++ b/tests/server/middleware/test_initialization_middleware.py
@@ -0,0 +1,434 @@
+"""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 ErrorData, TextContent
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool 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.clientInfo
+
+        # 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.readOnlyHint = 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.readOnlyHint 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.serverInfo.name == "TestServer"
+        assert middleware.initialize_result.protocolVersion 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(
+                ErrorData(
+                    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(
+                ErrorData(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(
+                ErrorData(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 000000000..92758dfa4
--- /dev/null
+++ b/tests/server/middleware/test_logging.py
@@ -0,0 +1,654 @@
+"""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
+import mcp.types
+import pytest
+from inline_snapshot import snapshot
+from pydantic import AnyUrl
+
+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
+    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":{"task":null,"_meta":null,"name":"test_method","arguments":{"param":"value"}}}',
+                    "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": 110,
+                }
+            )
+
+        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": 27,
+                    "payload_length": 110,
+                }
+            )
+
+    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=AnyUrl("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\\":{\\"task\\":null,\\"_meta\\":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\\":{\\"task\\":null,\\"_meta\\":null,\\"name\\":\\"test_method\\",\\"arguments\\":{\\"obj\\":\\"NON_SERIALIZABLE\\"}}}", "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={"task":null,"_meta":null,"name":"simple_operation","arguments":{"data":"payload_test"}} 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": "{\\"task\\":null,\\"_meta\\":null,\\"name\\":\\"simple_operation\\",\\"arguments\\":{\\"data\\":\\"json_test\\"}}", "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={"task":null,"_meta":null,"name":"simple_operation","arguments":{"data":"custom_test"}} 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 000000000..6b822e228
--- /dev/null
+++ b/tests/server/middleware/test_middleware.py
@@ -0,0 +1,621 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import mcp.types
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool 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 progress handler
+    @mcp._mcp_server.progress_notification()
+    async def handle_progress(
+        progress_token: str | int,
+        progress: float,
+        total: float | None,
+        message: str | None,
+    ):
+        print("HI")
+
+    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].uriTemplate) == "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]
+        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]
+        # 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]
+
+        # 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]
diff --git a/tests/server/middleware/test_middleware_nested.py b/tests/server/middleware/test_middleware_nested.py
new file mode 100644
index 000000000..e57b9a311
--- /dev/null
+++ b/tests/server/middleware/test_middleware_nested.py
@@ -0,0 +1,673 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import mcp.types
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.server.context import Context
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool 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 progress handler
+    @mcp._mcp_server.progress_notification()
+    async def handle_progress(
+        progress_token: str | int,
+        progress: float,
+        total: float | None,
+        message: str | None,
+    ):
+        print("HI")
+
+    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 = FastMCP.as_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 = FastMCP.as_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 000000000..0d2677102
--- /dev/null
+++ b/tests/server/middleware/test_ping.py
@@ -0,0 +1,241 @@
+"""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."""
+
+    async def test_starts_ping_task_on_first_message(self):
+        """Test that ping task is started on first message from a session."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session = MagicMock()
+        mock_session._subscription_task_group = MagicMock()
+        mock_session._subscription_task_group.start_soon = MagicMock()
+
+        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(mock_session) in middleware._active_sessions
+        mock_session._subscription_task_group.start_soon.assert_called_once()
+
+    async def test_does_not_start_duplicate_task(self):
+        """Test that duplicate messages from same session don't spawn duplicate tasks."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session = MagicMock()
+        mock_session._subscription_task_group = MagicMock()
+        mock_session._subscription_task_group.start_soon = MagicMock()
+
+        mock_context = MagicMock()
+        mock_context.fastmcp_context.session = mock_session
+
+        mock_call_next = AsyncMock(return_value="result")
+
+        # First message
+        await middleware.on_message(mock_context, mock_call_next)
+        # Second message from same session
+        await middleware.on_message(mock_context, mock_call_next)
+        # Third message from same session
+        await middleware.on_message(mock_context, mock_call_next)
+
+        # Should only start task once
+        assert mock_session._subscription_task_group.start_soon.call_count == 1
+
+    async def test_starts_separate_task_per_session(self):
+        """Test that different sessions get separate ping tasks."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session1 = MagicMock()
+        mock_session1._subscription_task_group = MagicMock()
+        mock_session1._subscription_task_group.start_soon = MagicMock()
+
+        mock_session2 = MagicMock()
+        mock_session2._subscription_task_group = MagicMock()
+        mock_session2._subscription_task_group.start_soon = MagicMock()
+
+        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)
+
+        mock_session1._subscription_task_group.start_soon.assert_called_once()
+        mock_session2._subscription_task_group.start_soon.assert_called_once()
+        assert len(middleware._active_sessions) == 2
+
+    async def test_skips_task_when_no_task_group(self):
+        """Test graceful handling when session has no task group."""
+        middleware = PingMiddleware(interval_ms=1000)
+
+        mock_session = MagicMock()
+        mock_session._subscription_task_group = None
+
+        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"
+        # Session should NOT be added if task group is None
+        assert id(mock_session) not in middleware._active_sessions
+
+    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 000000000..23132324f
--- /dev/null
+++ b/tests/server/middleware/test_rate_limiting.py
@@ -0,0 +1,463 @@
+"""Tests for rate limiting middleware."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.exceptions import ToolError
+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
+
+
+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
+
+    def test_get_client_identifier_default(self, mock_context):
+        """Test default client identifier."""
+        middleware = RateLimitingMiddleware()
+        assert middleware._get_client_identifier(mock_context) == "global"
+
+    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 middleware._get_client_identifier(mock_context) == "custom_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)
+
+
+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)
+
+
+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 ToolError 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."""
+        rate_limit_server.add_middleware(
+            SlidingWindowRateLimitingMiddleware(
+                max_requests=6,  # 1 init + 1 list_tools + 3 calls + 1 to fail
+                window_minutes=1,  # 1-minute window
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Should allow up to the limit
+            await client.call_tool("quick_action", {"message": "1"})
+            await client.call_tool("quick_action", {"message": "2"})
+            await client.call_tool("quick_action", {"message": "3"})
+
+            # Fourth should be blocked
+            with pytest.raises(ToolError, match="Rate limit exceeded"):
+                await client.call_tool("quick_action", {"message": "4"})
+
+    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=9.0, burst_capacity=5)
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Mix different operations
+            await client.call_tool("quick_action", {"message": "test"})
+            await client.call_tool("heavy_computation")
+
+            # Should be rate limited regardless of operation type
+            with pytest.raises(ToolError, match="Rate limit exceeded"):
+                await client.call_tool("batch_process", {"items": ["a", "b", "c"]})
+
+    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=1.0,  # Very slow refill to ensure rate limiting triggers
+                burst_capacity=4,  # init + list_tools + call + list_tools = 4, so 2nd call fails
+                get_client_id=get_client_id,
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            # First request should succeed
+            await client.call_tool("quick_action", {"message": "first"})
+
+            # Second should be rate limited for this specific client
+            with pytest.raises(ToolError) as exc_info:
+                await client.call_tool("quick_action", {"message": "second"})
+            assert "Rate limit exceeded for client: test_client_123" in str(
+                exc_info.value
+            )
+
+    async def test_global_rate_limiting(self, rate_limit_server):
+        """Test global rate limiting across all clients."""
+        rate_limit_server.add_middleware(
+            RateLimitingMiddleware(
+                max_requests_per_second=6.0,
+                burst_capacity=5,  # 1 init + 2 list_tools + 2 calls before limit
+                global_limit=True,  # Accounting for initialization and list_tools calls
+            )
+        )
+
+        async with Client(rate_limit_server) as client:
+            # Use up the global capacity
+            await client.call_tool("quick_action", {"message": "1"})
+            await client.call_tool("quick_action", {"message": "2"})
+
+            # Should be globally rate limited
+            with pytest.raises(ToolError, match="Global rate limit exceeded"):
+                await client.call_tool("quick_action", {"message": "3"})
+
+    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:
+            # Use up capacity
+            await client.call_tool("quick_action", {"message": "first"})
+
+            # Should be rate limited immediately
+            with pytest.raises(ToolError):
+                await client.call_tool("quick_action", {"message": "second"})
+
+            # 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 000000000..4e89e05de
--- /dev/null
+++ b/tests/server/middleware/test_response_limiting.py
@@ -0,0 +1,155 @@
+"""Tests for ResponseLimitingMiddleware."""
+
+import pytest
+from mcp.types import ImageContent, TextContent
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware
+from fastmcp.tools.tool import ToolResult
+
+
+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, mimeType="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)
+
+    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 000000000..f2196985b
--- /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 000000000..f16c132e6
--- /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.function_tool import FunctionTool
+from fastmcp.tools.tool import Tool
+
+
+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.inputSchema["properties"]
+        assert "b" in multiply_tool.inputSchema["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 000000000..e69de29bb
diff --git a/tests/server/mount/test_advanced.py b/tests/server/mount/test_advanced.py
new file mode 100644
index 000000000..3835ceca9
--- /dev/null
+++ b/tests/server/mount/test_advanced.py
@@ -0,0 +1,489 @@
+"""Advanced mounting scenarios."""
+
+import pytest
+from mcp.types import TextContent
+
+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 hasattr(routes[0], "path")
+        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 hasattr(route, "path")]
+        assert "/route1" in route_paths
+        assert "/route2" in route_paths
+
+
+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 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 000000000..376db4c75
--- /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 000000000..b1b8ee0c0
--- /dev/null
+++ b/tests/server/mount/test_mount.py
@@ -0,0 +1,542 @@
+"""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.tools.tool 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 = FastMCP.as_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 DEBUG level)
+        debug_messages = [
+            record.message for record in caplog.records if record.levelname == "DEBUG"
+        ]
+        assert any(
+            "Error during list_tools from provider" in msg for msg in debug_messages
+        )
+        assert any(
+            "Error during list_resources from provider" in msg for msg in debug_messages
+        )
+        assert any(
+            "Error during list_prompts from provider" in msg for msg in debug_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"
diff --git a/tests/server/mount/test_prompts.py b/tests/server/mount/test_prompts.py
new file mode 100644
index 000000000..9760cab93
--- /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 000000000..08caa36a0
--- /dev/null
+++ b/tests/server/mount/test_proxy.py
@@ -0,0 +1,306 @@
+"""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.providers import FastMCPProvider
+from fastmcp.server.providers.proxy import FastMCPProxy
+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 = FastMCP.as_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 = FastMCP.as_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 = FastMCP.as_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 = FastMCP.as_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 TestAsProxyKwarg:
+    """Test the as_proxy kwarg."""
+
+    async def test_as_proxy_defaults_false(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_as_proxy_false(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def sub_tool() -> str:
+            return "test"
+
+        mcp.mount(sub, "sub", as_proxy=False)
+
+        # 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_as_proxy_true(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        @sub.tool
+        def sub_tool() -> str:
+            return "test"
+
+        mcp.mount(sub, "sub", as_proxy=True)
+
+        # 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 wrapping a proxy
+        assert isinstance(provider._inner, FastMCPProvider)
+        assert provider._inner.server is not sub
+        assert isinstance(provider._inner.server, FastMCPProxy)
+        # 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_as_proxy_ignored_for_proxy_mounts_default(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+        sub_proxy = FastMCP.as_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_as_proxy_ignored_for_proxy_mounts_false(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+        sub_proxy = FastMCP.as_proxy(FastMCPTransport(sub))
+
+        mcp.mount(sub_proxy, "sub", as_proxy=False)
+
+        # 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_as_proxy_ignored_for_proxy_mounts_true(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+        sub_proxy = FastMCP.as_proxy(FastMCPTransport(sub))
+
+        mcp.mount(sub_proxy, "sub", as_proxy=True)
+
+        # 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_as_proxy_mounts_still_have_live_link(self):
+        mcp = FastMCP("Main")
+        sub = FastMCP("Sub")
+
+        mcp.mount(sub, "sub", as_proxy=True)
+
+        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, as_proxy=True)
+
+        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 000000000..e6c4fb502
--- /dev/null
+++ b/tests/server/mount/test_resources.py
@@ -0,0 +1,198 @@
+"""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_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 000000000..e69de29bb
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 000000000..e69de29bb
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 000000000..935a9d8af
--- /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.tool 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 000000000..92c5df44e
--- /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.tool 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 000000000..aee0c4b36
--- /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 000000000..9e1803b41
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_local_provider_tools.py
@@ -0,0 +1,274 @@
+"""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", {})
+        assert result.structured_content == {"result": "Hello, world!"}
+
+    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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "application/octet-stream"
+        assert content2.data == "abc"
+        assert isinstance(content3, EmbeddedResource)
+        assert content3.type == "resource"
+        resource = content3.resource
+        assert resource.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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 000000000..f9136492e
--- /dev/null
+++ b/tests/server/providers/local_provider_tools/test_output_schema.py
@@ -0,0 +1,381 @@
+"""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.function_parsing import _is_object_schema
+from fastmcp.tools.tool import ToolResult
+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_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 000000000..92e1af6de
--- /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].mimeType == "image/png"
+        assert result.content[0].data == base64.b64encode(b"fake png data").decode()
+
+    async def test_tool_with_invalid_input(self):
+        from pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 pydantic 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 000000000..fb32e3515
--- /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 000000000..b862f61a3
--- /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 000000000..5396767c2
--- /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.inputSchema
+                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.inputSchema
+                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.inputSchema
+                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.inputSchema
+                # 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.inputSchema
+                # 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 000000000..1d934ec32
--- /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.inputSchema
+                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.inputSchema
+                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.inputSchema
+                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.inputSchema
+                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.inputSchema is not None
+                    assert tool.inputSchema["type"] == "object"
+                    assert "properties" in tool.inputSchema
+
+                    # Should have some properties
+                    assert len(tool.inputSchema["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 000000000..0680c0d2d
--- /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.inputSchema
+                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.inputSchema
+
+                # 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 000000000..ac78f1b10
--- /dev/null
+++ b/tests/server/providers/openapi/test_openapi_features.py
@@ -0,0 +1,1029 @@
+"""Tests for OpenAPI feature support in OpenAPIProvider."""
+
+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.inputSchema
+                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.inputSchema
+                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.inputSchema
+                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].mimeType == "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].mimeType == "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].mimeType == "application/json"
+
+
+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].mimeType == "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].mimeType == "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.outputSchema is not None
+            assert get_user.outputSchema.get("additionalProperties") is True
+            # Should NOT have specific properties from the original schema
+            assert "properties" not in get_user.outputSchema
+
+
+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 000000000..c09a3ff64
--- /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 000000000..09a5a3c5d
--- /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.inputSchema
+                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.inputSchema
+                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.inputSchema is not None
+                    assert tool.inputSchema["type"] == "object"
+                    assert "properties" in tool.inputSchema
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 000000000..8a0d49e53
--- /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.1  # 100ms
+
+        print(f"Average initialization time: {avg_time:.4f}s")
+        print(f"Performance: {'✓' if avg_time < max_acceptable_time else '✗'}")
+
+        # Should initialize in under 100ms for serverless requirements
+        assert avg_time < max_acceptable_time, (
+            f"Provider should initialize in under 100ms, 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.1  # 100ms
+
+        print(f"Average server initialization time: {avg_time:.4f}s")
+
+        assert avg_time < max_acceptable_time, (
+            f"Server should initialize in under 100ms, 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 000000000..0d7447eab
--- /dev/null
+++ b/tests/server/providers/openapi/test_server.py
@@ -0,0 +1,311 @@
+"""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 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.inputSchema == 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.outputSchema == expected_output_schema
diff --git a/tests/server/providers/proxy/__init__.py b/tests/server/providers/proxy/__init__.py
new file mode 100644
index 000000000..e69de29bb
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 000000000..52db25cc6
--- /dev/null
+++ b/tests/server/providers/proxy/test_proxy_client.py
@@ -0,0 +1,438 @@
+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.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 FastMCP.as_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.systemPrompt == "You love FastMCP"
+            assert params.temperature == 0.5
+            assert params.maxTokens == 100
+            assert params.modelPreferences == 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.requestedSchema == {
+                "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 = FastMCP.as_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.requestedSchema
+            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 as_proxy convenience method and direct client_factory usage
+        proxy_via_as_proxy = FastMCP.as_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_as_proxy is not None
+        assert proxy_via_factory is not None
+
+        # Verify they have the expected client factory behavior
+        assert hasattr(proxy_via_as_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()
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 000000000..cd2514809
--- /dev/null
+++ b/tests/server/providers/proxy/test_proxy_server.py
@@ -0,0 +1,769 @@
+import inspect
+import json
+from typing import Any, cast
+
+import mcp.types as 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,
+)
+from fastmcp.tools.tool import ToolResult
+from fastmcp.tools.tool_transform import (
+    ToolTransformConfig,
+)
+
+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.prompt import Message, PromptResult
+
+        return PromptResult(
+            messages=[
+                Message("Here is an image:"),
+                Message(
+                    content=mcp_types.ImageContent(
+                        type="image",
+                        data="iVBORw0KGgoAAAANSUhEUg==",
+                        mimeType="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/"
+
+
+# --- Deprecated as_proxy tests (verify backwards compatibility) ---
+
+
+async def test_as_proxy_deprecated_with_server(fastmcp_server):
+    """FastMCP.as_proxy should work but emit deprecation warning."""
+    import warnings
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        proxy = FastMCP.as_proxy(fastmcp_server)
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "create_proxy" in str(w[0].message)
+
+    async with Client(proxy) as client:
+        result = await client.call_tool("greet", {"name": "Test"})
+        assert result.data == "Hello, Test!"
+
+
+def test_as_proxy_deprecated_with_url():
+    """FastMCP.as_proxy should work but emit deprecation warning."""
+    import warnings
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        proxy = FastMCP.as_proxy("http://example.com/mcp/")
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+
+    assert isinstance(proxy, FastMCPProxy)
+
+
+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/"
+
+
+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):
+        assert await proxy_server._list_tools_mcp(
+            mcp_types.ListToolsRequest()
+        ) == await fastmcp_server._list_tools_mcp(mcp_types.ListToolsRequest())
+
+    async def test_call_tool_result_same_as_original(
+        self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy
+    ):
+        result = await fastmcp_server._call_tool_mcp("greet", {"name": "Alice"})
+        proxy_result = await proxy_server._call_tool_mcp("greet", {"name": "Alice"})
+
+        assert result == proxy_result
+
+    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_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.inputSchema["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):
+        assert await proxy_server._list_resources_mcp(
+            mcp_types.ListResourcesRequest()
+        ) == await fastmcp_server._list_resources_mcp(mcp_types.ListResourcesRequest())
+
+    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.mimeType == proxied.mimeType, (
+                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].mimeType == "text/plain"
+        assert original_result[1].text == '{"key": "value"}'
+        assert original_result[1].mimeType == "application/json"
+        assert original_result[2].text == "# Markdown\nContent"
+        assert original_result[2].mimeType == "text/markdown"
+
+    async def test_read_resource_returns_none_if_not_found(self, proxy_server):
+        with pytest.raises(
+            McpError, match="Unknown resource: '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
+    ):
+        result = await fastmcp_server._list_resource_templates_mcp(
+            mcp_types.ListResourceTemplatesRequest()
+        )
+        proxy_result = await proxy_server._list_resource_templates_mcp(
+            mcp_types.ListResourceTemplatesRequest()
+        )
+        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.mimeType == proxied.mimeType, (
+                f"Content {i} mimeType mismatch"
+            )
+
+        # Verify the contents are what we expect
+        assert original_result[0].text == "Item test123 - First"
+        assert original_result[0].mimeType == "text/plain"
+        assert original_result[1].text == '{"id": "test123", "status": "active"}'
+        assert original_result[1].mimeType == "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.uriTemplate == "data://user/{user_id}"
+            )
+            assert user_template.name == "overwritten_get_user"
+
+
+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.mimeType == "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()
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 000000000..79a280e72
--- /dev/null
+++ b/tests/server/providers/proxy/test_stateful_proxy_client.py
@@ -0,0 +1,201 @@
+import asyncio
+from dataclasses import dataclass
+
+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.elicitation import AcceptedElicitation
+from fastmcp.server.providers.proxy import FastMCPProxy, StatefulProxyClient
+from fastmcp.utilities.tests import find_available_port, run_server_async
+
+
+@pytest.fixture
+def fastmcp_server():
+    mcp = FastMCP("TestServer")
+
+    states: dict[int, 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"""
+        key = id(context.session)
+        states[key] = value
+
+    @mcp.tool
+    async def stateful_get(context: Context) -> int:
+        """get the value associated with the server session"""
+        key = id(context.session)
+        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!"
diff --git a/tests/server/providers/test_base_provider.py b/tests/server/providers/test_base_provider.py
new file mode 100644
index 000000000..ed084c34d
--- /dev/null
+++ b/tests/server/providers/test_base_provider.py
@@ -0,0 +1,91 @@
+"""Tests for base Provider class behavior."""
+
+from typing import Any
+
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.server.transforms import Namespace
+from fastmcp.tools.tool 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 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"
diff --git a/tests/server/providers/test_fastmcp_provider.py b/tests/server/providers/test_fastmcp_provider.py
new file mode 100644
index 000000000..f7f86d9a3
--- /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.prompt import PromptResult
+from fastmcp.resources.resource import ResourceResult
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.providers import FastMCPProvider
+from fastmcp.tools.tool 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 000000000..2db664338
--- /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.prompt import Prompt
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.tool 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 000000000..0176a9b53
--- /dev/null
+++ b/tests/server/providers/test_local_provider_prompts.py
@@ -0,0 +1,481 @@
+"""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.prompt 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)
+            assert message.content.text == "Hello, World! 1"
+
+
+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 000000000..4c8da4559
--- /dev/null
+++ b/tests/server/providers/test_local_provider_resources.py
@@ -0,0 +1,984 @@
+"""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)
+            assert result[0].text == "1"
+
+
+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."""
+        mcp = FastMCP()
+
+        @mcp.resource(
+            "api://users/{user_id}",
+            annotations={"httpMethod": "GET", "Cache-Control": "no-cache"},
+        )
+        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 hasattr(template.annotations, "httpMethod")
+        assert getattr(template.annotations, "httpMethod") == "GET"
+        assert hasattr(template.annotations, "Cache-Control")
+        assert getattr(template.annotations, "Cache-Control") == "no-cache"
+
+
+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)
+            assert result[0].text.startswith("Resource template: test 1")
+
+    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)
+            assert result[0].text.startswith("Resource template: test 1")
+
+
+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_skills_provider.py b/tests/server/providers/test_skills_provider.py
new file mode 100644
index 000000000..3caa96cf4
--- /dev/null
+++ b/tests/server/providers/test_skills_provider.py
@@ -0,0 +1,666 @@
+"""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
+
+
+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 (either normalized away or blocked)
+            # The important thing is that SECRET DATA is never returned
+            with pytest.raises(Exception):
+                result = await client.read_resource(
+                    AnyUrl("skill://test-skill/../../../secret.txt")
+                )
+                # If we somehow got here, ensure we didn't get the secret
+                if result:
+                    for content in result:
+                        if hasattr(content, "text"):
+                            assert "SECRET DATA" not in content.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 000000000..65959ef1d
--- /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 000000000..ce7acd2a4
--- /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 000000000..e69de29bb
diff --git a/tests/server/sampling/test_prepare_tools.py b/tests/server/sampling/test_prepare_tools.py
new file mode 100644
index 000000000..c08a27ae1
--- /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]
+
+    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 000000000..a95b393ac
--- /dev/null
+++ b/tests/server/sampling/test_sampling_tool.py
@@ -0,0 +1,292 @@
+"""Tests for SamplingTool."""
+
+import pytest
+
+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.inputSchema.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]
+
+    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]
+
+    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}
diff --git a/tests/server/tasks/__init__.py b/tests/server/tasks/__init__.py
new file mode 100644
index 000000000..84d43c008
--- /dev/null
+++ b/tests/server/tasks/__init__.py
@@ -0,0 +1 @@
+"""Tests for MCP SEP-1686 background tasks."""
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 000000000..8b2a92889
--- /dev/null
+++ b/tests/server/tasks/test_context_background_task.py
@@ -0,0 +1,480 @@
+"""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
+from typing import cast
+
+import pytest
+from mcp import ServerSession
+
+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, DeclinedElicitation
+from fastmcp.server.tasks.elicitation import handle_task_input
+
+# =============================================================================
+# 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 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.
+        """
+        from unittest.mock import patch
+
+        from fastmcp.server.elicitation import CancelledElicitation
+
+        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 != ""
+
+            key = docket.key(
+                f"fastmcp:task:{ctx.session_id}:{ctx.task_id}:origin_request_id"
+            )
+            async with docket.redis() as redis:
+                raw = await redis.get(key)
+
+            assert raw is not None
+            if isinstance(raw, bytes):
+                raw = raw.decode()
+            assert str(raw) == 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"
+
+    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."""
+        from pydantic import BaseModel
+
+        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,
+                session_id="nonexistent-session",
+                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."""
+        from mcp.server.auth.middleware.auth_context import auth_context_var
+        from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+
+        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."""
+        from datetime import datetime, timezone
+
+        from fastmcp.server.dependencies import _task_access_token
+
+        expired = AccessToken(
+            token="expired-jwt",
+            client_id="test-client",
+            scopes=["read"],
+            expires_at=int(datetime.now(timezone.utc).timestamp()) - 3600,
+        )
+        _task_access_token.set(expired)
+        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."""
+        from datetime import datetime, timezone
+
+        from fastmcp.server.dependencies import _task_access_token
+
+        valid = AccessToken(
+            token="valid-jwt",
+            client_id="test-client",
+            scopes=["read"],
+            expires_at=int(datetime.now(timezone.utc).timestamp()) + 3600,
+        )
+        _task_access_token.set(valid)
+        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."""
+        from fastmcp.server.dependencies import _task_access_token
+
+        no_expiry = AccessToken(
+            token="eternal-jwt",
+            client_id="test-client",
+            scopes=["read"],
+        )
+        _task_access_token.set(no_expiry)
+        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 000000000..381fd24ac
--- /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.tool 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 000000000..f0e144fd4
--- /dev/null
+++ b/tests/server/tasks/test_notifications.py
@@ -0,0 +1,148 @@
+"""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 as mcp_types
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.messages import MessageHandler
+from fastmcp.server.context import Context
+from fastmcp.server.elicitation import AcceptedElicitation
+from fastmcp.server.tasks.notifications import (
+    get_subscriber_count,
+)
+
+
+class NotificationCaptureHandler(MessageHandler):
+    """Capture server notifications for test assertions."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.notifications: list[mcp_types.ServerNotification] = []
+
+    async def on_notification(self, message: mcp_types.ServerNotification) -> None:
+        self.notifications.append(message)
+
+    def for_method(self, method: str) -> list[mcp_types.ServerNotification]:
+        return [
+            notification
+            for notification in self.notifications
+            if notification.root.method == method
+        ]
+
+
+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.
+
+        The elicitation relay handles the response via the client's
+        elicitation_handler. We verify both the notification metadata
+        structure and the end-to-end elicitation flow.
+        """
+        mcp = FastMCP("notification-test")
+        notification_handler = NotificationCaptureHandler()
+
+        @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,
+            message_handler=notification_handler,
+            elicitation_handler=elicitation_handler,
+        ) as client:
+            task = await client.call_tool("elicit_tool", {}, task=True)
+
+            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.ServerNotification | None = None
+            candidates = notification_handler.for_method("notifications/tasks/status")
+            for candidate in reversed(candidates):
+                candidate_meta = getattr(candidate.root, "_meta", None)
+                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 = getattr(notification.root, "_meta", None)
+            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 000000000..d6b121ba7
--- /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.statusMessage
+        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 000000000..50650f9d5
--- /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.resource 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.taskId}"
+
+        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.taskId}"
+
+        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 000000000..8bb0ec6c8
--- /dev/null
+++ b/tests/server/tasks/test_server_tasks_parameter.py
@@ -0,0 +1,388 @@
+"""
+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.
+"""
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+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
+
+
+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)
+        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)
+        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)
+        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)
+        assert default.returned_immediately
+        result = await default.result()
+        assert result.is_error
+
+
+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)
+        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)
+        assert tool_task.returned_immediately
+        result = await tool_task.result()
+        assert result.is_error
+
+
+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
+
+
+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"
+
+
+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"
+
+
+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_sync_function_task_disabled.py b/tests/server/tasks/test_sync_function_task_disabled.py
new file mode 100644
index 000000000..c5255b0b4
--- /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 000000000..146d80d41
--- /dev/null
+++ b/tests/server/tasks/test_task_capabilities.py
@@ -0,0 +1,44 @@
+"""
+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 {})
+
+
+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"
diff --git a/tests/server/tasks/test_task_config.py b/tests/server/tasks/test_task_config.py
new file mode 100644
index 000000000..6287df933
--- /dev/null
+++ b/tests/server/tasks/test_task_config.py
@@ -0,0 +1,393 @@
+"""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.tool 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)
+            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
+
+    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
+
+    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.taskSupport 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.taskSupport == "optional"
+
+    async def test_required_tool_exposes_task_support(self):
+        """Tools with mode=required should expose taskSupport='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.taskSupport == "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 000000000..b3e7faa42
--- /dev/null
+++ b/tests/server/tasks/test_task_dependencies.py
@@ -0,0 +1,273 @@
+"""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
+
+
+@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]
+
+    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
+
+
+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
+
+
+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}"
+
+    from fastmcp.exceptions import ToolError
+
+    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 000000000..42362edd2
--- /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_meta_parameter.py b/tests/server/tasks/test_task_meta_parameter.py
new file mode 100644
index 000000000..ecf6d303a
--- /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.tool 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.taskId}"
+
+        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 000000000..32ce2b849
--- /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.taskId == 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 000000000..9dd4d7a62
--- /dev/null
+++ b/tests/server/tasks/test_task_methods.py
@@ -0,0 +1,217 @@
+"""
+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.taskId == 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.pollInterval is not None
+        assert isinstance(status.pollInterval, 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"
+
+
+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 000000000..b601792e2
--- /dev/null
+++ b/tests/server/tasks/test_task_mount.py
@@ -0,0 +1,965 @@
+"""
+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 fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.prompts.prompt import PromptResult
+from fastmcp.resources.resource import ResourceResult
+from fastmcp.server.dependencies import CurrentDocket, CurrentFastMCP
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.server.tasks import TaskConfig
+from fastmcp.tools.tool 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"
+
+    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
+            )
+
+            # 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)
+
+    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)
+
+    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
+
+    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]
+            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]
+            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()
+
+            # The server should be the child server since that's where the tool is defined
+            assert len(received_server) == 1
+            # Note: It might be parent or child depending on implementation
+            assert received_server[0] is not None
+
+
+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 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)
+
+            # 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
+        ]
+
+    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",
+        ]
+
+    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",
+        ]
+
+    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.taskId}"
+
+        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.taskId}"
+
+        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.taskId}"
+
+        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.taskId}"
+
+        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.taskId}"
+
+        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.taskId}"
+
+        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.taskId}"
+
+        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 000000000..1a02bec83
--- /dev/null
+++ b/tests/server/tasks/test_task_prompts.py
@@ -0,0 +1,91 @@
+"""
+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
+
+
+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()
+
+
+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 000000000..9c6a88d22
--- /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.taskId == 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 000000000..f1b41a3dc
--- /dev/null
+++ b/tests/server/tasks/test_task_proxy.py
@@ -0,0 +1,169 @@
+"""
+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.providers.proxy import ProxyClient
+
+
+@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 FastMCP.as_proxy(ProxyClient(transport=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)
+
+            # 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
+            )
+
+            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."""
+
+    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."""
+
+    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)
+
+    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 000000000..ed240eb06
--- /dev/null
+++ b/tests/server/tasks/test_task_resources.py
@@ -0,0 +1,107 @@
+"""
+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
+
+
+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"
+
+
+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
+
+
+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 000000000..3ef352902
--- /dev/null
+++ b/tests/server/tasks/test_task_return_types.py
@@ -0,0 +1,670 @@
+"""
+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",
+            str,
+            lambda r: "Hello bytes!" in r.data or "SGVsbG8gYnl0ZXMh" in r.data,
+        ),
+        (
+            "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].mimeType == "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 (
+        AnyUrl,
+        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(),
+            mimeType="image/png",
+        )
+
+    @mcp.tool(task=True)
+    async def return_embedded_resource() -> EmbeddedResource:
+        return EmbeddedResource(
+            type="resource",
+            resource=TextResourceContents(
+                uri=AnyUrl("test://resource"), text="embedded"
+            ),
+        )
+
+    @mcp.tool(task=True)
+    async def return_resource_link() -> ResourceLink:
+        return ResourceLink(
+            type="resource_link", uri=AnyUrl("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(),
+                mimeType="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].mimeType == "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 000000000..88af3aa7d
--- /dev/null
+++ b/tests/server/tasks/test_task_security.py
@@ -0,0 +1,47 @@
+"""
+Tests for session-based task ID isolation (CRITICAL SECURITY).
+
+Ensures that tasks are properly scoped to sessions and clients cannot
+access each other's tasks.
+"""
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+
+
+@pytest.fixture
+async def task_server():
+    """Create a server with background tasks enabled."""
+    mcp = FastMCP("security-test-server")
+
+    @mcp.tool(task=True)  # Enable background execution
+    async def secret_tool(data: str) -> str:
+        """A tool that processes sensitive data."""
+        return f"Secret result: {data}"
+
+    return mcp
+
+
+async def test_same_session_can_access_all_its_tasks(task_server):
+    """A single session can access all tasks it created."""
+    async with Client(task_server) as client:
+        # Submit multiple tasks
+        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"
+        )
+
+        # Wait for both to complete
+        await task1.wait(timeout=2.0)
+        await task2.wait(timeout=2.0)
+
+        # Should be able to access both
+        result1 = await task1.result()
+        result2 = await task2.result()
+
+        assert "first" in str(result1.data)
+        assert "second" in str(result2.data)
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 000000000..98d333ca9
--- /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 000000000..530f6b0e6
--- /dev/null
+++ b/tests/server/tasks/test_task_tools.py
@@ -0,0 +1,101 @@
+"""
+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 pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.tasks import ToolTask
+
+
+@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
+
+
+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)
+        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 000000000..769fafffa
--- /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 000000000..bdcf54173
--- /dev/null
+++ b/tests/server/telemetry/__init__.py
@@ -0,0 +1 @@
+"""Tests for FastMCP server telemetry."""
diff --git a/tests/server/telemetry/test_provider_tracing.py b/tests/server/telemetry/test_provider_tracing.py
new file mode 100644
index 000000000..7118044a2
--- /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_server_tracing.py b/tests/server/telemetry/test_server_tracing.py
new file mode 100644
index 000000000..1d110effe
--- /dev/null
+++ b/tests/server/telemetry/test_server_tracing.py
@@ -0,0 +1,340 @@
+"""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 FastMCP
+from fastmcp.exceptions import NotFoundError, ToolError
+from fastmcp.server.auth import AccessToken
+
+
+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"
+        # Standard RPC semantic conventions
+        assert span.attributes["rpc.system"] == "mcp"
+        assert span.attributes["rpc.service"] == "test-server"
+        assert span.attributes["rpc.method"] == "tools/call"
+        # 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 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
+
+
+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 config://app"
+        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"
+        # Standard RPC semantic conventions
+        assert span.attributes["rpc.system"] == "mcp"
+        assert span.attributes["rpc.service"] == "test-server"
+        assert span.attributes["rpc.method"] == "resources/read"
+        # 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 users://123/profile"
+        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"
+        # Standard RPC semantic conventions
+        assert span.attributes["rpc.method"] == "resources/read"
+        # 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 nonexistent://resource"
+        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"
+        # Standard RPC semantic conventions
+        assert span.attributes["rpc.system"] == "mcp"
+        assert span.attributes["rpc.service"] == "test-server"
+        assert span.attributes["rpc.method"] == "prompts/get"
+        # 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
diff --git a/tests/server/test_app_state.py b/tests/server/test_app_state.py
new file mode 100644
index 000000000..eeccd6fee
--- /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 000000000..102e3e7c3
--- /dev/null
+++ b/tests/server/test_auth_integration.py
@@ -0,0 +1,971 @@
+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()
+        # SDK validates client_id before other fields, returning unauthorized_client
+        # (FastMCP's OAuthProxy transforms this to invalid_client, but this test
+        # uses the SDK's create_auth_routes directly)
+        assert error_response["error"] == "unauthorized_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
+    ):
+        client_metadata = {
+            "redirect_uris": ["https://client.example.com/callback"],
+            "client_name": "Test Client",
+            "grant_types": ["authorization_code"],
+        }
+
+        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 be authorization_code and refresh_token"
+        )
diff --git a/tests/server/test_auth_integration_errors.py b/tests/server/test_auth_integration_errors.py
new file mode 100644
index 000000000..196701119
--- /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_context.py b/tests/server/test_context.py
new file mode 100644
index 000000000..921257c89
--- /dev/null
+++ b/tests/server/test_context.py
@@ -0,0 +1,498 @@
+from typing import Any, cast
+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]
+
+
+class TestSessionId:
+    def test_session_id_with_http_headers(self, context):
+        """Test that session_id returns the value from mcp-session-id header."""
+        from mcp.server.lowlevel.server import request_ctx
+        from mcp.shared.context import RequestContext
+
+        mock_headers = {"mcp-session-id": "test-session-123"}
+
+        token = request_ctx.set(
+            RequestContext(
+                request_id=0,
+                meta=None,
+                session=MagicMock(wraps={}),
+                lifespan_context=MagicMock(),
+                request=MagicMock(headers=mock_headers),
+            )
+        )
+
+        try:
+            assert context.session_id == "test-session-123"
+        finally:
+            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 mcp.server.lowlevel.server import request_ctx
+        from mcp.shared.context import RequestContext
+
+        mock_session = MagicMock(wraps={})
+        token = request_ctx.set(
+            RequestContext(
+                request_id=0,
+                meta=None,
+                session=mock_session,
+                lifespan_context=MagicMock(),
+            )
+        )
+
+        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:
+            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 meta can be accessed from request context."""
+        from mcp.server.lowlevel.server import request_ctx
+        from mcp.shared.context import RequestContext
+
+        # Create a mock meta object with attributes
+        class MockMeta:
+            def __init__(self):
+                self.user_id = "user-123"
+                self.trace_id = "trace-456"
+                self.custom_field = "custom-value"
+
+        mock_meta = MockMeta()
+
+        token = request_ctx.set(
+            RequestContext(
+                request_id=0,
+                meta=cast(Any, mock_meta),  # Mock object for testing
+                session=MagicMock(wraps={}),
+                lifespan_context=MagicMock(),
+            )
+        )
+
+        # Access meta through context
+        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"
+
+        request_ctx.reset(token)
+
+    def test_request_context_meta_none(self, context):
+        """Test that context handles None meta gracefully."""
+        from mcp.server.lowlevel.server import request_ctx
+        from mcp.shared.context import RequestContext
+
+        token = request_ctx.set(
+            RequestContext(
+                request_id=0,
+                meta=None,
+                session=MagicMock(wraps={}),
+                lifespan_context=MagicMock(),
+            )
+        )
+
+        # Access meta through context
+        retrieved_meta = context.request_context.meta
+        assert retrieved_meta is None
+
+        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 000000000..9a4af015b
--- /dev/null
+++ b/tests/server/test_dependencies.py
@@ -0,0 +1,1097 @@
+"""Tests for Docket-style dependency injection in FastMCP."""
+
+from contextlib import asynccontextmanager, contextmanager
+
+import mcp.types as mcp_types
+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
+
+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._list_tools_mcp(mcp_types.ListToolsRequest())
+    tool = next(t for t in result.tools if t.name == "my_tool")
+
+    assert "name" in tool.inputSchema["properties"]
+    assert "age" in tool.inputSchema["properties"]
+    assert "config" not in tool.inputSchema["properties"]
+    assert len(tool.inputSchema["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
+    import pydantic
+
+    with pytest.raises(pydantic.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._list_tools_mcp(mcp_types.ListToolsRequest())
+    tool = next(t for t in result.tools if t.name == "with_connection")
+
+    assert "name" in tool.inputSchema["properties"]
+    assert "connection" not in tool.inputSchema["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._list_tools_mcp(mcp_types.ListToolsRequest())
+    tool = next(t for t in result.tools if t.name == "check_permission")
+    assert "admin" not in tool.inputSchema["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)
+    import pydantic
+
+    with pytest.raises(pydantic.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_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_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."""
+        import mcp.types as mcp_types
+
+        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._list_tools_mcp(mcp_types.ListToolsRequest())
+        tool = next(t for t in result.tools if t.name == "tool_with_token")
+
+        assert "name" in tool.inputSchema["properties"]
+        assert "token" not in tool.inputSchema["properties"]
+
+    async def test_token_claim_excluded_from_tool_schema(self, mcp: FastMCP):
+        """Test that TokenClaim dependency is excluded from tool schema."""
+        import mcp.types as mcp_types
+
+        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._list_tools_mcp(mcp_types.ListToolsRequest())
+        tool = next(t for t in result.tools if t.name == "tool_with_claim")
+
+        assert "name" in tool.inputSchema["properties"]
+        assert "user_id" not in tool.inputSchema["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._list_tools_mcp(mcp_types.ListToolsRequest())
+        tool = next(t for t in result.tools if t.name == "my_tool")
+
+        assert "name" in tool.inputSchema["properties"]
+        assert "db" not in tool.inputSchema["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
diff --git a/tests/server/test_dependencies_advanced.py b/tests/server/test_dependencies_advanced.py
new file mode 100644
index 000000000..19bbb9b87
--- /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 mcp.types as mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.dependencies import CurrentContext
+from fastmcp.server.context import 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._list_tools_mcp(mcp_types.ListToolsRequest())
+        tool = next(t for t in result.tools if t.name == "tool_with_multiple_ctx")
+        assert "name" in tool.inputSchema["properties"]
+        assert "ctx1" not in tool.inputSchema["properties"]
+        assert "ctx2" not in tool.inputSchema["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 000000000..54fbfa828
--- /dev/null
+++ b/tests/server/test_event_store.py
@@ -0,0 +1,238 @@
+"""Tests for the EventStore implementation."""
+
+import pytest
+from mcp.server.streamable_http import EventMessage
+from mcp.types import JSONRPCMessage, JSONRPCRequest
+
+from fastmcp.server.event_store import EventEntry, EventStore, StreamEventList
+
+
+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 JSONRPCMessage(root=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)
+        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
+
+    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 = JSONRPCMessage(
+            root=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 = JSONRPCMessage(
+                root=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 = JSONRPCMessage(
+            root=JSONRPCRequest(jsonrpc="2.0", method="stream1-test", id=1)
+        )
+        msg2 = JSONRPCMessage(
+            root=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
+
+    async def test_default_storage_is_memory(self):
+        """Test that EventStore defaults to in-memory storage."""
+        event_store = EventStore()
+        msg = JSONRPCMessage(root=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 = JSONRPCMessage(
+            root=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 = JSONRPCMessage(
+            root=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 isinstance(replayed[0].message.root, JSONRPCRequest)
+        assert replayed[0].message.root.method == "tools/call"
+        assert replayed[0].message.root.id == "request-456"
diff --git a/tests/servers/test_file_server.py b/tests/server/test_file_server.py
similarity index 59%
rename from tests/servers/test_file_server.py
rename to tests/server/test_file_server.py
index d8f53a388..9bda34c10 100644
--- a/tests/servers/test_file_server.py
+++ b/tests/server/test_file_server.py
@@ -1,8 +1,11 @@
-import json
-from fastmcp import FastMCP
-import pytest
 from pathlib import Path
 
+import mcp.types as mcp_types
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.resources import ResourceContent, ResourceResult
+
 
 @pytest.fixture()
 def test_dir(tmp_path_factory) -> Path:
@@ -25,11 +28,12 @@ def mcp() -> FastMCP:
 
 
 @pytest.fixture(autouse=True)
-def resources(mcp: FastMCP, test_dir: Path) -> None:
+def resources(mcp: FastMCP, test_dir: Path) -> FastMCP:
     @mcp.resource("dir://test_dir")
-    def list_test_dir() -> list[str]:
+    def list_test_dir() -> ResourceResult:
         """List the files in the test directory"""
-        return [str(f) for f in test_dir.iterdir()]
+        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:
@@ -59,8 +63,8 @@ def read_config_json() -> str:
 
 
 @pytest.fixture(autouse=True)
-def tools(mcp: FastMCP, test_dir: Path) -> None:
-    @mcp.tool()
+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:
@@ -68,12 +72,14 @@ def delete_file(path: str) -> bool:
         Path(path).unlink()
         return True
 
+    return mcp
+
 
 async def test_list_resources(mcp: FastMCP):
-    resources = await mcp.list_resources()
-    assert len(resources) == 4
+    result = await mcp._list_resources_mcp(mcp_types.ListResourcesRequest())
+    assert len(result.resources) == 4
 
-    assert [str(r.uri) for r in resources] == [
+    assert [str(r.uri) for r in result.resources] == [
         "dir://test_dir",
         "file://test_dir/example.py",
         "file://test_dir/readme.md",
@@ -82,8 +88,16 @@ async def test_list_resources(mcp: FastMCP):
 
 
 async def test_read_resource_dir(mcp: FastMCP):
-    files = await mcp.read_resource("dir://test_dir")
-    files = json.loads(files)
+    res_result = await mcp._read_resource_mcp("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",
@@ -93,20 +107,28 @@ async def test_read_resource_dir(mcp: FastMCP):
 
 
 async def test_read_resource_file(mcp: FastMCP):
-    result = await mcp.read_resource("file://test_dir/example.py")
-    assert result == "print('hello world')"
+    res_result = await mcp._read_resource_mcp("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.call_tool(
+    await mcp._call_tool_mcp(
         "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.call_tool(
+    await mcp._call_tool_mcp(
         "delete_file", arguments=dict(path=str(test_dir / "example.py"))
     )
-    result = await mcp.read_resource("file://test_dir/example.py")
-    assert result == "File not found"
+    res_result = await mcp._read_resource_mcp("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 000000000..a937728fa
--- /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",
+                mimeType="image/png",
+                sizes=["48x48"],
+            ),
+            Icon(
+                src="data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=",
+                mimeType="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.serverInfo
+            assert server_info.websiteUrl == "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.serverInfo
+            assert server_info.websiteUrl 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", mimeType="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",
+                mimeType="image/png",
+                sizes=["48x48"],
+            ),
+            Icon(
+                src="https://example.com/icon-96.png",
+                mimeType="image/png",
+                sizes=["96x96"],
+            ),
+            Icon(
+                src="https://example.com/icon.svg",
+                mimeType="image/svg+xml",
+                sizes=["any"],
+            ),
+        ]
+
+        mcp = FastMCP("TestServer", icons=icons)
+
+        async with Client(mcp) as client:
+            server_info = client.initialize_result.serverInfo
+            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, mimeType="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.serverInfo
+            assert server_info.icons[0].src == "https://example.com/icon.png"
+            assert server_info.icons[0].mimeType 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 000000000..f986f3769
--- /dev/null
+++ b/tests/server/test_input_validation.py
@@ -0,0 +1,365 @@
+"""
+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
+
+
+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_pydantic_model_with_stringified_json_no_strict(self):
+        """Test if stringified JSON is accepted for Pydantic models 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:
+            # Some LLM clients send stringified JSON instead of actual JSON
+            stringified = json.dumps(
+                {"name": "Bob", "age": 25, "email": "bob@example.com"}
+            )
+
+            # This test verifies whether we handle stringified JSON
+            try:
+                result = await client.call_tool("create_user", {"profile": stringified})
+                # If this succeeds, we're handling stringified JSON
+                assert isinstance(result.content[0], TextContent)
+                assert "Bob" in result.content[0].text
+                stringified_json_works = True
+            except Exception as e:
+                # If this fails, we're not handling stringified JSON
+                stringified_json_works = False
+                error_msg = str(e)
+
+            # Document the behavior - we want to know if this works or not
+            if stringified_json_works:
+                # This is the desired behavior
+                pass
+            else:
+                # This means stringified JSON doesn't work - document it
+                assert (
+                    "validation" in error_msg.lower() or "invalid" in error_msg.lower()
+                )
+
+    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"
diff --git a/tests/server/test_log_level.py b/tests/server/test_log_level.py
new file mode 100644
index 000000000..59aa1ea67
--- /dev/null
+++ b/tests/server/test_log_level.py
@@ -0,0 +1,90 @@
+"""Test log_level parameter support in FastMCP server."""
+
+import asyncio
+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_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 000000000..b8d1237d4
--- /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 000000000..f28fabe1b
--- /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.nextCursor is not None
+
+            # Second page
+            result2 = await client.list_tools_mcp(cursor=result.nextCursor)
+            assert len(result2.tools) == 10
+            assert result2.nextCursor is not None
+
+            # Third (last) page
+            result3 = await client.list_tools_mcp(cursor=result2.nextCursor)
+            assert len(result3.tools) == 5
+            assert result3.nextCursor 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.nextCursor 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.nextCursor is not None
+
+            # Second (last) page
+            result2 = await client.list_tools_mcp(cursor=result.nextCursor)
+            assert len(result2.tools) == 10
+            assert result2.nextCursor 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.nextCursor = "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.nextCursor = "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.nextCursor = "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.nextCursor = "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.nextCursor = 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.nextCursor = ""
+                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.nextCursor = 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.nextCursor = 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.nextCursor = 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_providers.py b/tests/server/test_providers.py
new file mode 100644
index 000000000..aa0ea267a
--- /dev/null
+++ b/tests/server/test_providers.py
@@ -0,0 +1,448 @@
+"""Tests for providers."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import pytest
+from mcp.types import AnyUrl, TextContent
+
+from fastmcp import FastMCP
+from fastmcp.prompts.function_prompt import FunctionPrompt
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.function_resource import FunctionResource
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import FunctionResourceTemplate, ResourceTemplate
+from fastmcp.server.providers import Provider
+from fastmcp.tools.tool 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: list[Tool] | None = None):
+        super().__init__()
+        self._tools = tools or []
+        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: list[Tool]):
+        super().__init__()
+        self._tools = 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() for efficient single-tool 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 is called once for efficient lookup:
+        # call_tool() calls provider.get_tool() to get the tool and execute it
+        # Key point: list_tools is NOT called during tool execution (efficient lookup)
+        assert provider.get_tool_call_count == 1
+
+    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_run_server.py b/tests/server/test_run_server.py
new file mode 100644
index 000000000..65e3112ac
--- /dev/null
+++ b/tests/server/test_run_server.py
@@ -0,0 +1,98 @@
+# from pathlib import Path
+# from typing import TYPE_CHECKING, Any
+
+# import pytest
+
+# import fastmcp
+# from fastmcp import FastMCP
+
+# if TYPE_CHECKING:
+#     pass
+
+# 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
+#     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
+#     def error_tool():
+#         """This tool always raises an error."""
+#         raise ValueError("This is a test error")
+
+#     # --- Resources ---
+
+#     @server.resource(uri="resource://wave")
+#     def wave() -> str:
+#         return "👋"
+
+#     @server.resource(uri="data://users")
+#     async def get_users() -> list[dict[str, Any]]:
+#         return USERS
+
+#     @server.resource(uri="data://user/{user_id}")
+#     async def get_user(user_id: str) -> dict[str, Any] | None:
+#         return next((user for user in USERS if user["id"] == user_id), None)
+
+#     # --- Prompts ---
+
+#     @server.prompt
+#     def welcome(name: str) -> str:
+#         return f"Welcome to FastMCP, {name}!"
+
+#     return server
+
+
+# @pytest.fixture
+# async def stdio_client():
+#     # Find the stdio.py script path
+#     base_dir = Path(__file__).parent
+#     stdio_script = base_dir / "test_servers" / "stdio.py"
+
+#     if not stdio_script.exists():
+#         raise FileNotFoundError(f"Could not find stdio.py script at {stdio_script}")
+
+#     client = fastmcp.Client(
+#         transport=fastmcp.client.transports.StdioTransport(
+#             command="python",
+#             args=[str(stdio_script)],
+#         )
+#     )
+
+#     async with client:
+#         print("READY")
+#         yield client
+#         print("DONE")
+
+
+# class TestRunServerStdio:
+#     async def test_run_server_stdio(
+#         self, fastmcp_server: FastMCP, stdio_client: fastmcp.Client
+#     ):
+#         print("TEST")
+#         tools = await stdio_client.list_tools()
+#         print("TEST 2")
+#         assert tools == 1
+
+
+# class TestRunServerSSE:
+#
+#     async def test_run_server_sse(self, fastmcp_server: FastMCP):
+#         pass
diff --git a/tests/server/test_server.py b/tests/server/test_server.py
new file mode 100644
index 000000000..e3a7f5125
--- /dev/null
+++ b/tests/server/test_server.py
@@ -0,0 +1,436 @@
+import os
+import warnings
+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.tool 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 TestRemoveToolDeprecation:
+    async def test_remove_tool_emits_deprecation_warning(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            mcp.remove_tool("my_tool")
+
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "local_provider" in str(w[0].message)
+
+    async def test_remove_tool_still_works(self):
+        mcp = FastMCP()
+
+        @mcp.tool
+        def my_tool() -> str:
+            return "result"
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            mcp.remove_tool("my_tool")
+
+        tools = await mcp.list_tools()
+        assert not any(t.name == "my_tool" for t in tools)
+
+
+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.uriTemplate == "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 000000000..7d0b7f5c0
--- /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 000000000..2d2b3446e
--- /dev/null
+++ b/tests/server/test_server_lifespan.py
@@ -0,0 +1,545 @@
+"""Tests for server_lifespan and session_lifespan behavior."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.context import Context
+from fastmcp.server.lifespan import ContextManagerLifespan, lifespan
+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]
+
+        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",
+        ]
diff --git a/tests/server/test_session_visibility.py b/tests/server/test_session_visibility.py
new file mode 100644
index 000000000..887f4f330
--- /dev/null
+++ b/tests/server/test_session_visibility.py
@@ -0,0 +1,768 @@
+"""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."""
+        self.notifications.append(
+            NotificationRecording(method=message.root.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 000000000..cd40a288b
--- /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 000000000..b805f4f9e
--- /dev/null
+++ b/tests/server/test_tool_annotations.py
@@ -0,0 +1,255 @@
+from typing import Any
+
+import mcp.types as mcp_types
+from mcp.types import Tool as MCPTool
+from mcp.types import ToolAnnotations, ToolExecution
+
+from fastmcp import Client, FastMCP
+from fastmcp.tools.tool import Tool
+
+
+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",
+            readOnlyHint=True,
+            openWorldHint=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.readOnlyHint is True
+    assert tools[0].annotations.openWorldHint 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",
+            readOnlyHint=True,
+            openWorldHint=False,
+        )
+    )
+    def echo(message: str) -> str:
+        """Echo back the message provided."""
+        return message
+
+    # Check via MCP protocol
+    result = await mcp._list_tools_mcp(mcp_types.ListToolsRequest())
+    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.readOnlyHint is True
+    assert result.tools[0].annotations.openWorldHint 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",
+            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.readOnlyHint is True
+        assert tools_result[0].annotations.openWorldHint 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.readOnlyHint is True
+        assert tools_result[0].annotations.openWorldHint 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",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=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.readOnlyHint is False
+    assert tools[0].annotations.destructiveHint is True
+    assert tools[0].annotations.idempotentHint is False
+    assert tools[0].annotations.openWorldHint 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",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=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.readOnlyHint is False
+        assert tools_result[0].annotations.destructiveHint 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",
+            readOnlyHint=False,
+            destructiveHint=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.readOnlyHint is False
+    assert tools[0].annotations.destructiveHint 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",
+            readOnlyHint=False,
+            destructiveHint=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.taskSupport 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.taskSupport == "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 000000000..b9812f735
--- /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.inputSchema.get("properties", {})
+            assert "user_id" in tool.inputSchema["properties"]
+            assert (
+                tool.inputSchema["properties"]["user_id"]["description"]
+                == "The user ID"
+            )
diff --git a/tests/server/transforms/test_catalog.py b/tests/server/transforms/test_catalog.py
new file mode 100644
index 000000000..01004a2bf
--- /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.tool 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]
+            """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]
+            """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]
+        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 000000000..1583d3b11
--- /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 000000000..49297f98a
--- /dev/null
+++ b/tests/server/transforms/test_resources_as_tools.py
@@ -0,0 +1,227 @@
+"""Tests for ResourcesAsTools transform."""
+
+import base64
+import json
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+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)
diff --git a/tests/server/transforms/test_search.py b/tests/server/transforms/test_search.py
new file mode 100644
index 000000000..9549f8c01
--- /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 as 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.tool 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 000000000..a784af1f4
--- /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.tool 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 000000000..e69de29bb
diff --git a/tests/server/versioning/test_calls.py b/tests/server/versioning/test_calls.py
new file mode 100644
index 000000000..67ac9d51a
--- /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 000000000..c68cf163f
--- /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 000000000..bceb7f9d8
--- /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 000000000..f2866df06
--- /dev/null
+++ b/tests/server/versioning/test_versioning.py
@@ -0,0 +1,314 @@
+"""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,
+    compare_versions,
+    is_version_greater,
+)
+
+
+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")
+
+
+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 000000000..071c77d6e
--- /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 000000000..11b900eac
--- /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 000000000..c760af5cf
--- /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 000000000..5d41897a2
--- /dev/null
+++ b/tests/test_apps.py
@@ -0,0 +1,552 @@
+"""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 typing import Any
+
+import pytest
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.apps import (
+    UI_EXTENSION_ID,
+    UI_MIME_TYPE,
+    AppConfig,
+    ResourceCSP,
+    ResourcePermissions,
+    app_config_to_meta_dict,
+)
+from fastmcp.server.context import Context
+
+# ---------------------------------------------------------------------------
+# 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"
+
+        tools = list(await server.list_tools())
+        assert tools[0].meta is not None
+        assert tools[0].meta["ui"]["resourceUri"] == "ui://foo"
+        assert tools[0].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())
+        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:
+    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
+
+
+# ---------------------------------------------------------------------------
+# 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
+
+
+# ---------------------------------------------------------------------------
+# 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"])
+        )
+        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.ui is preserved — the host decides what to do with it
+            meta = tools[0].meta
+            assert meta is not None
+            assert meta["ui"]["resourceUri"] == "ui://app/view.html"
+            assert meta["ui"]["visibility"] == ["app"]
+
+    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].mimeType == 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].mimeType == 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_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"]))
+        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"
+            ]
diff --git a/tests/test_apps_prefab.py b/tests/test_apps_prefab.py
new file mode 100644
index 000000000..301141d05
--- /dev/null
+++ b/tests/test_apps_prefab.py
@@ -0,0 +1,431 @@
+"""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 PrefabApp
+from prefab_ui.components import Column, Heading, Text
+from prefab_ui.components.base import Component
+
+from fastmcp import Client, FastMCP
+from fastmcp.resources.types import TextResource
+from fastmcp.server.apps import UI_MIME_TYPE, AppConfig
+from fastmcp.server.providers.local_provider.decorators.tools import (
+    PREFAB_RENDERER_URI,
+)
+from fastmcp.tools.tool 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["version"] == "0.2"
+        assert result.structured_content["state"] == {"name": "Alice"}
+        assert result.structured_content["view"]["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["version"] == "0.2"
+        assert result.structured_content["view"]["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["version"] == "0.2"
+        assert result.structured_content["view"]["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["version"] == "0.2"
+        assert result.structured_content["view"]["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
+
+    def test_app_true_registers_renderer_resource(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        renderer_key = f"resource:{PREFAB_RENDERER_URI}@"
+        assert renderer_key in mcp._local_provider._components
+
+    def test_renderer_resource_has_correct_mime_type(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        renderer_key = f"resource:{PREFAB_RENDERER_URI}@"
+        resource = mcp._local_provider._components[renderer_key]
+        assert isinstance(resource, TextResource)
+        assert resource.mime_type == UI_MIME_TYPE
+
+    def test_renderer_resource_has_csp(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def my_tool() -> str:
+            return "hello"
+
+        renderer_key = f"resource:{PREFAB_RENDERER_URI}@"
+        resource = mcp._local_provider._components[renderer_key]
+        assert resource.meta is not None
+        assert "ui" in resource.meta
+        assert "csp" in resource.meta["ui"]
+
+    def test_multiple_tools_share_renderer(self):
+        mcp = FastMCP("test")
+
+        @mcp.tool(app=True)
+        def tool_a() -> str:
+            return "a"
+
+        @mcp.tool(app=True)
+        def tool_b() -> str:
+            return "b"
+
+        renderer_keys = [
+            k for k in mcp._local_provider._components if k.startswith("resource:ui://")
+        ]
+        assert len(renderer_keys) == 1
+
+    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["version"] == "0.2"
+        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["version"] == "0.2"
+
+    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
+        assert meta["ui"]["resourceUri"] == PREFAB_RENDERER_URI
+
+    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:
+            contents = await client.read_resource(PREFAB_RENDERER_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_json_schema_generation.py b/tests/test_json_schema_generation.py
new file mode 100644
index 000000000..9cf10a0a5
--- /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.function_tool import FunctionTool
+from fastmcp.tools.tool import Tool
+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 000000000..2c7f133a7
--- /dev/null
+++ b/tests/test_mcp_config.py
@@ -0,0 +1,1034 @@
+import asyncio
+import gc
+import inspect
+import logging
+import os
+import sys
+import tempfile
+import time
+from collections.abc import AsyncGenerator
+from datetime import timedelta
+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.tool import Tool as FastMCPTool
+
+# Skip all tests in this file on Windows - they spawn subprocess servers via stdio
+# which has process lifecycle issues on Windows
+pytestmark = 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_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]
+
+
+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]
+    )
+
+    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)
+    timeout = timedelta(seconds=42)
+
+    # 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
+
+
+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_server.py b/tests/test_server.py
deleted file mode 100644
index 0a491a2ee..000000000
--- a/tests/test_server.py
+++ /dev/null
@@ -1,266 +0,0 @@
-from mcp.shared.memory import (
-    create_connected_server_and_client_session as client_session,
-)
-from fastmcp import FastMCP
-from fastmcp.resources import FileResource, FunctionResource
-from fastmcp.tools import Image
-from mcp.types import TextContent, ImageContent
-import pytest
-from pydantic import BaseModel
-from pathlib import Path
-import base64
-from typing import Union
-
-
-class TestServer:
-    async def test_create_server(self):
-        mcp = FastMCP()
-        assert mcp.name == "FastMCP"
-
-    async def test_add_tool_decorator(self):
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def add(x: int, y: int) -> int:
-            return x + y
-
-        assert len(mcp._tool_manager.list_tools()) == 1
-
-    async def test_add_tool_decorator_incorrect_usage(self):
-        mcp = FastMCP()
-
-        with pytest.raises(TypeError, match="The @tool decorator was used incorrectly"):
-
-            @mcp.tool  # Missing parentheses
-            def add(x: int, y: int) -> int:
-                return x + y
-
-    async def test_add_resource_decorator(self):
-        mcp = FastMCP()
-
-        @mcp.resource("r://data")
-        def get_data(x: str) -> str:
-            return f"Data: {x}"
-
-        assert len(mcp._resource_manager.list_resources()) == 1
-
-    async def test_add_resource_decorator_incorrect_usage(self):
-        mcp = FastMCP()
-
-        with pytest.raises(
-            TypeError, match="The @resource decorator was used incorrectly"
-        ):
-
-            @mcp.resource  # Missing parentheses
-            def get_data(x: str) -> str:
-                return f"Data: {x}"
-
-
-def tool_fn(x: int, y: int) -> int:
-    return x + y
-
-
-def error_tool_fn() -> None:
-    raise ValueError("Test error")
-
-
-class ErrorResponse(BaseModel):
-    is_error: bool = True
-    message: str
-
-
-def image_tool_fn(path: str) -> Image:
-    return Image(path)
-
-
-def mixed_content_tool_fn() -> list[Union[TextContent, ImageContent]]:
-    return [
-        TextContent(type="text", text="Hello"),
-        ImageContent(type="image", data="abc", mimeType="image/png"),
-    ]
-
-
-class TestServerTools:
-    async def test_add_tool(self):
-        mcp = FastMCP()
-        mcp.add_tool(tool_fn)
-        mcp.add_tool(tool_fn)
-        assert len(mcp._tool_manager.list_tools()) == 1
-
-    async def test_list_tools(self):
-        mcp = FastMCP()
-        mcp.add_tool(tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            tools = await client.list_tools()
-            assert len(tools.tools) == 1
-
-    async def test_call_tool(self):
-        mcp = FastMCP()
-        mcp.add_tool(tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("my_tool", {"arg1": "value"})
-            assert "error" not in result
-            assert len(result.content) > 0
-
-    async def test_tool_exception_handling(self):
-        mcp = FastMCP()
-        mcp.add_tool(error_tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("error_tool_fn", {})
-            assert len(result.content) == 1
-            assert result.content[0].type == "text"
-            assert "Test error" in result.content[0].text
-            assert result.content[0].is_error is True
-
-    async def test_tool_exception_content(self):
-        """Test that exception details are properly formatted in the response"""
-        mcp = FastMCP()
-        mcp.add_tool(error_tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("error_tool_fn", {})
-            content = result.content[0]
-            assert content.type == "text"
-            assert isinstance(content.text, str)
-            assert "Test error" in content.text
-            assert content.is_error is True
-
-    async def test_tool_text_conversion(self):
-        mcp = FastMCP()
-        mcp.add_tool(tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("tool_fn", {"x": 1, "y": 2})
-            assert len(result.content) == 1
-            assert result.content[0].type == "text"
-            assert result.content[0].text == "3"
-
-    async def test_tool_image_helper(self, tmp_path: Path):
-        # Create a test image
-        image_path = tmp_path / "test.png"
-        image_path.write_bytes(b"fake png data")
-
-        mcp = FastMCP()
-        mcp.add_tool(image_tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("image_tool_fn", {"path": str(image_path)})
-            assert len(result.content) == 1
-            assert result.content[0].type == "image"
-            assert result.content[0].mimeType == "image/png"
-            # Verify base64 encoding
-            decoded = base64.b64decode(result.content[0].data)
-            assert decoded == b"fake png data"
-
-    async def test_tool_mixed_content(self):
-        mcp = FastMCP()
-        mcp.add_tool(mixed_content_tool_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("mixed_content_tool_fn", {})
-            assert len(result.content) == 2
-            assert result.content[0].type == "text"
-            assert result.content[0].text == "Hello"
-            assert result.content[1].type == "image"
-            assert result.content[1].mimeType == "image/png"
-            assert result.content[1].data == "abc"
-
-    async def test_tool_mixed_list_with_image(self, tmp_path: Path):
-        """Test that lists containing Image objects and other types are handled correctly"""
-        # Create a test image
-        image_path = tmp_path / "test.png"
-        image_path.write_bytes(b"test image data")
-
-        def mixed_list_fn() -> list:
-            return [
-                "text message",
-                Image(image_path),
-                {"key": "value"},
-                TextContent(type="text", text="direct content"),
-            ]
-
-        mcp = FastMCP()
-        mcp.add_tool(mixed_list_fn)
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.call_tool("mixed_list_fn", {})
-            assert len(result.content) == 4
-            # Check text conversion
-            assert result.content[0].type == "text"
-            assert '"text message"' in result.content[0].text
-            # Check image conversion
-            assert result.content[1].type == "image"
-            assert result.content[1].mimeType == "image/png"
-            assert base64.b64decode(result.content[1].data) == b"test image data"
-            # Check dict conversion
-            assert result.content[2].type == "text"
-            assert '"key": "value"' in result.content[2].text
-            # Check direct TextContent
-            assert result.content[3].type == "text"
-            assert result.content[3].text == "direct content"
-
-
-class TestServerResources:
-    async def test_text_resource(self):
-        mcp = FastMCP()
-
-        def get_text():
-            return "Hello, world!"
-
-        resource = FunctionResource(uri="resource://test", name="test", func=get_text)
-        mcp.add_resource(resource)
-
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.read_resource("resource://test")
-            assert result.contents[0].text == "Hello, world!"
-
-    async def test_binary_resource(self):
-        mcp = FastMCP()
-
-        def get_binary():
-            return b"Binary data"
-
-        resource = FunctionResource(
-            uri="resource://binary",
-            name="binary",
-            func=get_binary,
-            is_binary=True,
-            mime_type="application/octet-stream",
-        )
-        mcp.add_resource(resource)
-
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.read_resource("resource://binary")
-            assert result.contents[0].blob == base64.b64encode(b"Binary data").decode()
-
-    async def test_file_resource_text(self, tmp_path: Path):
-        mcp = FastMCP()
-
-        # Create a text file
-        text_file = tmp_path / "test.txt"
-        text_file.write_text("Hello from file!")
-
-        resource = FileResource(uri="file://test.txt", name="test.txt", path=text_file)
-        mcp.add_resource(resource)
-
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.read_resource("file://test.txt")
-            assert result.contents[0].text == "Hello from file!"
-
-    async def test_file_resource_binary(self, tmp_path: Path):
-        mcp = FastMCP()
-
-        # Create a binary file
-        binary_file = tmp_path / "test.bin"
-        binary_file.write_bytes(b"Binary file data")
-
-        resource = FileResource(
-            uri="file://test.bin",
-            name="test.bin",
-            path=binary_file,
-            is_binary=True,
-            mime_type="application/octet-stream",
-        )
-        mcp.add_resource(resource)
-
-        async with client_session(mcp._mcp_server) as client:
-            result = await client.read_resource("file://test.bin")
-            assert (
-                result.contents[0].blob
-                == base64.b64encode(b"Binary file data").decode()
-            )
diff --git a/tests/test_tool_manager.py b/tests/test_tool_manager.py
deleted file mode 100644
index 8818af938..000000000
--- a/tests/test_tool_manager.py
+++ /dev/null
@@ -1,155 +0,0 @@
-import logging
-import pytest
-from pydantic import BaseModel
-
-from fastmcp.exceptions import ToolError
-from fastmcp.tools import ToolManager
-
-
-class TestAddTools:
-    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
-
-        manager = ToolManager()
-        manager.add_tool(add)
-
-        tool = manager.get_tool("add")
-        assert tool is not None
-        assert tool.name == "add"
-        assert tool.description == "Add two numbers."
-        assert tool.is_async is False
-        assert tool.parameters["properties"]["a"]["type"] == "integer"
-        assert tool.parameters["properties"]["b"]["type"] == "integer"
-
-    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}"
-
-        manager = ToolManager()
-        manager.add_tool(fetch_data)
-
-        tool = manager.get_tool("fetch_data")
-        assert tool is not None
-        assert tool.name == "fetch_data"
-        assert tool.description == "Fetch data from URL."
-        assert tool.is_async is True
-        assert tool.parameters["properties"]["url"]["type"] == "string"
-
-    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()}
-
-        manager = ToolManager()
-        manager.add_tool(create_user)
-
-        tool = manager.get_tool("create_user")
-        assert tool is not None
-        assert tool.name == "create_user"
-        assert tool.description == "Create a new user."
-        assert tool.is_async is False
-        assert "name" in tool.parameters["$defs"]["UserInput"]["properties"]
-        assert "age" in tool.parameters["$defs"]["UserInput"]["properties"]
-        assert "flag" in tool.parameters["properties"]
-
-    def test_add_invalid_tool(self):
-        manager = ToolManager()
-        with pytest.raises(AttributeError):
-            manager.add_tool(1)
-
-    def test_add_lambda(self):
-        manager = ToolManager()
-        tool = manager.add_tool(lambda x: x, name="my_tool")
-        assert tool.name == "my_tool"
-
-    def test_add_lambda_with_no_name(self):
-        manager = ToolManager()
-        with pytest.raises(
-            ValueError, match="You must provide a name for lambda functions"
-        ):
-            manager.add_tool(lambda x: x)
-
-    def test_warn_on_duplicate_tools(self, caplog):
-        """Test warning on duplicate tools."""
-
-        def f(x: int) -> int:
-            return x
-
-        manager = ToolManager()
-        manager.add_tool(f)
-        with caplog.at_level(logging.WARNING):
-            manager.add_tool(f)
-            assert "Tool already exists: f" in caplog.text
-
-    def test_disable_warn_on_duplicate_tools(self, caplog):
-        """Test disabling warning on duplicate tools."""
-
-        def f(x: int) -> int:
-            return x
-
-        manager = ToolManager()
-        manager.add_tool(f)
-        manager.warn_on_duplicate_tools = False
-        with caplog.at_level(logging.WARNING):
-            manager.add_tool(f)
-            assert "Tool already exists: f" not in caplog.text
-
-
-class TestCallTools:
-    async def test_call_tool(self):
-        def add(a: int, b: int) -> int:
-            """Add two numbers."""
-            return a + b
-
-        manager = ToolManager()
-        manager.add_tool(add)
-        result = await manager.call_tool("add", {"a": 1, "b": 2})
-        assert result == 3
-
-    async def test_call_async_tool(self):
-        async def double(n: int) -> int:
-            """Double a number."""
-            return n * 2
-
-        manager = ToolManager()
-        manager.add_tool(double)
-        result = await manager.call_tool("double", {"n": 5})
-        assert result == 10
-
-    async def test_call_tool_with_default_args(self):
-        def add(a: int, b: int = 1) -> int:
-            """Add two numbers."""
-            return a + b
-
-        manager = ToolManager()
-        manager.add_tool(add)
-        result = await manager.call_tool("add", {"a": 1})
-        assert result == 2
-
-    async def test_call_tool_with_missing_args(self):
-        def add(a: int, b: int) -> int:
-            """Add two numbers."""
-            return a + b
-
-        manager = ToolManager()
-        manager.add_tool(add)
-        with pytest.raises(ToolError):
-            await manager.call_tool("add", {"a": 1})
-
-    async def test_call_unknown_tool(self):
-        manager = ToolManager()
-        with pytest.raises(ToolError):
-            await manager.call_tool("unknown", {"a": 1})
diff --git a/tests/tools/__init__.py b/tests/tools/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/tools/test_standalone_decorator.py b/tests/tools/test_standalone_decorator.py
new file mode 100644
index 000000000..de05aab9d
--- /dev/null
+++ b/tests/tools/test_standalone_decorator.py
@@ -0,0 +1,138 @@
+"""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.
+"""
+
+from typing import cast
+
+import pytest
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.tools import tool
+from fastmcp.tools.function_tool import DecoratedTool, ToolMeta
+
+
+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"}
+
+    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_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]
+            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 000000000..10ca9c57a
--- /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.tool 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].mimeType == "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_timeout.py b/tests/tools/test_tool_timeout.py
new file mode 100644
index 000000000..f93a2d8d6
--- /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 000000000..e69de29bb
diff --git a/tests/tools/tool/test_callable.py b/tests/tools/tool/test_callable.py
new file mode 100644
index 000000000..cffe8ab42
--- /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.tool 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 000000000..d08720f80
--- /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 AnyUrl, BaseModel
+
+from fastmcp.tools.tool 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", mimeType="image/png")),
+            (AudioContent(type="audio", data="fakeaudiodata", mimeType="audio/mpeg")),
+            (
+                ResourceLink(
+                    type="resource_link",
+                    name="test resource",
+                    uri=AnyUrl("resource://test"),
+                )
+            ),
+            (
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=AnyUrl("resource://test"),
+                        mimeType="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==", mimeType="image/png"
+                    )
+                ],
+            ),
+            (
+                Audio(data=b"fakeaudiodata"),
+                [
+                    AudioContent(
+                        type="audio", data="ZmFrZWF1ZGlvZGF0YQ==", mimeType="audio/wav"
+                    )
+                ],
+            ),
+            (
+                File(data=b"filedata", format="octet-stream"),
+                [
+                    EmbeddedResource(
+                        type="resource",
+                        resource=BlobResourceContents(
+                            uri=AnyUrl("file:///resource.octet-stream"),
+                            blob="ZmlsZWRhdGE=",
+                            mimeType="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=AnyUrl("resource://test"),
+            ),
+            EmbeddedResource(
+                type="resource",
+                resource=TextResourceContents(
+                    uri=AnyUrl("resource://test"),
+                    mimeType="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==", mimeType="image/png"
+                ),
+                AudioContent(
+                    type="audio", data="ZmFrZWF1ZGlvZGF0YQ==", mimeType="audio/wav"
+                ),
+                ResourceLink(
+                    name="test resource",
+                    uri=AnyUrl("resource://test"),
+                    type="resource_link",
+                ),
+                EmbeddedResource(
+                    type="resource",
+                    resource=TextResourceContents(
+                        uri=AnyUrl("resource://test"),
+                        mimeType="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==", mimeType="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 000000000..fc9468a04
--- /dev/null
+++ b/tests/tools/tool/test_output_schema.py
@@ -0,0 +1,534 @@
+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.tool import Tool
+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_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)
diff --git a/tests/tools/tool/test_results.py b/tests/tools/tool/test_results.py
new file mode 100644
index 000000000..da5973cd8
--- /dev/null
+++ b/tests/tools/tool/test_results.py
@@ -0,0 +1,184 @@
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from fastmcp.tools.tool 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 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
diff --git a/tests/tools/tool/test_title.py b/tests/tools/tool/test_title.py
new file mode 100644
index 000000000..30fa5b3f6
--- /dev/null
+++ b/tests/tools/tool/test_title.py
@@ -0,0 +1,95 @@
+from fastmcp.tools.tool 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 000000000..e2976b674
--- /dev/null
+++ b/tests/tools/tool/test_tool.py
@@ -0,0 +1,606 @@
+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.tool 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),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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):
+        from pydantic import AnyUrl
+
+        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": AnyUrl("file:///resource.octet-stream"),
+                    "mimeType": "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": {"title": "X"}},
+                    "required": ["x"],
+                    "type": "object",
+                },
+                "task_config": {
+                    "mode": "forbidden",
+                    "poll_interval": timedelta(seconds=5),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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),
+                },
+            }
+        )
+
+    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(taskSupport="optional"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.taskSupport == "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(taskSupport="optional"),
+        )
+
+        override_execution = ToolExecution(taskSupport="required")
+        mcp_tool = tool.to_mcp_tool(execution=override_execution)
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.taskSupport == "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.taskSupport == "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(taskSupport="required"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.taskSupport == "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(taskSupport="forbidden"),
+        )
+
+        mcp_tool = tool.to_mcp_tool()
+        assert mcp_tool.execution is not None
+        assert mcp_tool.execution.taskSupport == "forbidden"
diff --git a/tests/tools/tool_transform/__init__.py b/tests/tools/tool_transform/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/tools/tool_transform/test_args.py b/tests/tools/tool_transform/test_args.py
new file mode 100644
index 000000000..7d82169e4
--- /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 000000000..36384afec
--- /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 000000000..41aa7bbe8
--- /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.function_tool import FunctionTool
+from fastmcp.tools.tool import ToolResult
+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 000000000..bcf999ae6
--- /dev/null
+++ b/tests/tools/tool_transform/test_tool_transform.py
@@ -0,0 +1,620 @@
+"""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.function_tool import FunctionTool
+from fastmcp.tools.tool import ToolResult
+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_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="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="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
+
+
+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
+
+        proxy = FastMCP.as_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"
diff --git a/tests/utilities/__init__.py b/tests/utilities/__init__.py
new file mode 100644
index 000000000..e17939203
--- /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 000000000..e69de29bb
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 000000000..db32e40a0
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_advanced.py
@@ -0,0 +1,913 @@
+"""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]
+
+    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]
+        assert result.node.next is None  # type: ignore[attr-defined]
+
+    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]
+        assert result.child.name == "child"  # type: ignore[attr-defined]
+        assert result.child.child is None  # type: ignore[attr-defined]
+
+
+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]
+
+        # Check nested user extra field (BaseModel)
+        assert result.user.name == "Alice"  # type: ignore[attr-defined]
+        assert result.user.extra_user_field == "value"  # type: ignore[attr-defined]
+
+        # Check nested settings - should be dataclass
+        assert result.settings.theme == "dark"  # type: ignore[attr-defined]
+        # 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]
+
+    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]
+        assert result.age == 0  # type: ignore[attr-defined]
+        assert result.extra == "field"  # type: ignore[attr-defined]
+
+    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]
+
+    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]
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 000000000..53a1d9a1e
--- /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 000000000..9b10b5c37
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_containers.py
@@ -0,0 +1,201 @@
+"""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
+
+    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 000000000..781b81a82
--- /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 000000000..fc2226bdc
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_json_schema_type.py
@@ -0,0 +1,170 @@
+"""Core JSON schema type conversion tests."""
+
+from dataclasses import Field
+from enum import Enum
+from typing import 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 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")
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 000000000..7a8c8944e
--- /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 000000000..65fb50b8d
--- /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 000000000..b7158dd1c
--- /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 000000000..65e60ef1e
--- /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 000000000..3c5a98c79
--- /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",
+            inputSchema={"type": "object", "properties": {}},
+            outputSchema=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",
+            inputSchema={"type": "object", "properties": {}},
+            outputSchema=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 000000000..b2c1a0cce
--- /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 000000000..849c91ef4
--- /dev/null
+++ b/tests/utilities/openapi/test_director.py
@@ -0,0 +1,462 @@
+"""Unit tests for RequestDirector."""
+
+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
+        import json
+
+        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
+        import json
+
+        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
+
+        import json
+
+        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)
+
+        import json
+
+        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
+        import json
+
+        body_data = json.loads(request.content)
+        assert body_data == {"prop1": "value1", "prop2": "value2"}
+
+
+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")
diff --git a/tests/utilities/openapi/test_legacy_compatibility.py b/tests/utilities/openapi/test_legacy_compatibility.py
new file mode 100644
index 000000000..a40ee6331
--- /dev/null
+++ b/tests/utilities/openapi/test_legacy_compatibility.py
@@ -0,0 +1,192 @@
+"""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"
+
+    @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 000000000..4361635c2
--- /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 000000000..9cc163f00
--- /dev/null
+++ b/tests/utilities/openapi/test_nullable_fields.py
@@ -0,0 +1,385 @@
+"""Tests for nullable field handling in OpenAPI schemas."""
+
+import pytest
+from jsonschema import ValidationError, validate
+
+from fastmcp.utilities.openapi.json_schema_converter import (
+    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
+
+
+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)
diff --git a/tests/utilities/openapi/test_parser.py b/tests/utilities/openapi/test_parser.py
new file mode 100644
index 000000000..a281c710b
--- /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 000000000..809363410
--- /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 000000000..ceac2bdd6
--- /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 000000000..fbb15f597
--- /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 000000000..03177007d
--- /dev/null
+++ b/tests/utilities/test_async_utils.py
@@ -0,0 +1,110 @@
+"""Tests for fastmcp.utilities.async_utils."""
+
+import functools
+
+import pytest
+
+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 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 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 000000000..fc8378161
--- /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 000000000..f463c2913
--- /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 000000000..d8b852986
--- /dev/null
+++ b/tests/utilities/test_components.py
@@ -0,0 +1,437 @@
+"""Tests for fastmcp.utilities.components module."""
+
+import warnings
+
+import pytest
+from pydantic import ValidationError
+
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.tools.tool 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]
+        )
+        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]
+
+    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
+        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
+
+            assert len(w) == 1
+            assert "NoPrefix does not define KEY_PREFIX" in str(w[0].message)
+
+    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"
+
+            assert len(w) == 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_inspect.py b/tests/utilities/test_inspect.py
new file mode 100644
index 000000000..d846c844a
--- /dev/null
+++ b/tests/utilities/test_inspect.py
@@ -0,0 +1,604 @@
+"""Tests for the inspect.py module."""
+
+import importlib.metadata
+
+from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+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 = FastMCP1x("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 = FastMCP1x("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 = FastMCP1x("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 = FastMCP1x("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 = FastMCP1x("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 = FastMCP1x("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 000000000..bba995545
--- /dev/null
+++ b/tests/utilities/test_inspect_icons.py
@@ -0,0 +1,519 @@
+"""Tests for icon extraction and formatting functions in inspect.py."""
+
+import importlib.metadata
+
+from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+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",
+                    mimeType="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",
+                    mimeType="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", mimeType="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", mimeType="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", mimeType="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",
+                    mimeType="image/png",
+                    sizes=["48x48"],
+                ),
+                Icon(
+                    src="https://example.com/icon-96.png",
+                    mimeType="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, mimeType="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 = FastMCP1x("Icon1xServer")
+
+        @mcp.tool(
+            icons=[Icon(src="https://example.com/v1-tool.png", mimeType="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_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", mimeType="image/png")],
+        )
+
+        @mcp.tool(
+            icons=[Icon(src="https://example.com/tool.png", mimeType="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 000000000..3fce2a7ac
--- /dev/null
+++ b/tests/utilities/test_json_schema.py
@@ -0,0 +1,630 @@
+from fastmcp.utilities.json_schema import (
+    _prune_param,
+    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
+
+
+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",
+        }
+        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
+
+    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
+
+
+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_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
diff --git a/tests/utilities/test_logging.py b/tests/utilities/test_logging.py
new file mode 100644
index 000000000..d15b9c355
--- /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 000000000..28a3f4fd1
--- /dev/null
+++ b/tests/utilities/test_skills.py
@@ -0,0 +1,269 @@
+"""Tests for skills client utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+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,
+)
+
+
+@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 == []
+
+
+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")
+
+
+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()
+
+
+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()
diff --git a/tests/utilities/test_tests.py b/tests/utilities/test_tests.py
new file mode 100644
index 000000000..107781294
--- /dev/null
+++ b/tests/utilities/test_tests.py
@@ -0,0 +1,41 @@
+from unittest.mock import AsyncMock, patch
+
+import fastmcp
+from fastmcp import FastMCP
+from fastmcp.utilities.tests import 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()
diff --git a/tests/utilities/test_typeadapter.py b/tests/utilities/test_typeadapter.py
new file mode 100644
index 000000000..941cd1db9
--- /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 000000000..1f349ebdb
--- /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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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.mimeType == "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 000000000..9cc9aab3b
--- /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
index 72b2ceeed..4bf824746 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,801 +1,2598 @@
 version = 1
+revision = 3
 requires-python = ">=3.10"
+resolution-markers = [
+    "python_full_version >= '3.13'",
+    "python_full_version >= '3.11' and python_full_version < '3.13'",
+    "python_full_version < '3.11'",
+]
+
+[[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 }
+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.84.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/04/ea/0869d6df9ef83dcf393aeefc12dd81677d091c6ffc86f783e51cf44062f2/anthropic-0.84.0.tar.gz", hash = "sha256:72f5f90e5aebe62dca316cb013629cfa24996b0f5a4593b8c3d712bc03c43c37", size = 539457, upload-time = "2026-02-25T05:22:38.54Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643 },
+    { url = "https://files.pythonhosted.org/packages/64/ca/218fa25002a332c0aa149ba18ffc0543175998b1f65de63f6d106689a345/anthropic-0.84.0-py3-none-any.whl", hash = "sha256:861c4c50f91ca45f942e091d83b60530ad6d4f98733bfe648065364da05d29e7", size = 455156, upload-time = "2026-02-25T05:22:40.468Z" },
 ]
 
 [[package]]
 name = "anyio"
-version = "4.6.2.post1"
+version = "4.12.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
     { name = "idna" },
-    { name = "sniffio" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9f/09/45b9b7a6d4e45c6bcb5bf61d19e3ab87df68e0601fa8c5293de3542546cc/anyio-4.6.2.post1.tar.gz", hash = "sha256:4c8bc31ccdb51c7f7bd251f51c609e038d63e34219b44aa86e47576389880b4c", size = 173422 }
+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/e4/f5/f2b75d2fc6f1a260f340f0e7c6a060f4dd2961cc16884ed851b0d18da06a/anyio-4.6.2.post1-py3-none-any.whl", hash = "sha256:6d170c36fba3bdd840c73d3868c1e777e33676a69c3a72cf0a0d5d6d8009b61d", size = 90377 },
+    { 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 = "appnope"
-version = "0.1.4"
+name = "asttokens"
+version = "3.0.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/35/5d/752690df9ef5b76e169e68d6a129fa6d08a7100ca7f754c89495db3c6019/appnope-0.1.4.tar.gz", hash = "sha256:1de3860566df9caf38f01f86f65e0e13e379af54f9e4bee1e66b48f2efffd1ee", size = 4170 }
+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/81/29/5ecc3a15d5a33e31b26c11426c45c501e439cb865d0bff96315d86443b78/appnope-0.1.4-py2.py3-none-any.whl", hash = "sha256:502575ee11cd7a28c0205f379b525beefebab9d161b7c964670864014ed7213c", size = 4321 },
+    { 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 = "asttokens"
-version = "2.4.1"
+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 = "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.6.8"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "six" },
+    { name = "cryptography" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/45/1d/f03bcb60c4a3212e15f99a56085d93093a497718adf828d050b9d675da81/asttokens-2.4.1.tar.gz", hash = "sha256:b03869718ba9a6eb027e134bfdf69f38a236d681c83c160d510768af11254ba0", size = 62284 }
+sdist = { url = "https://files.pythonhosted.org/packages/6b/6c/c88eac87468c607f88bc24df1f3b31445ee6fc9ba123b09e666adf687cd9/authlib-1.6.8.tar.gz", hash = "sha256:41ae180a17cf672bc784e4a518e5c82687f1fe1e98b0cafaeda80c8e4ab2d1cb", size = 165074, upload-time = "2026-02-14T04:02:17.941Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/45/86/4736ac618d82a20d87d2f92ae19441ebc7ac9e7a581d7e58bbe79233b24a/asttokens-2.4.1-py2.py3-none-any.whl", hash = "sha256:051ed49c3dcae8913ea7cd08e46a606dba30b79993209636c4875bc1d637bc24", size = 27764 },
+    { url = "https://files.pythonhosted.org/packages/9b/73/f7084bf12755113cd535ae586782ff3a6e710bfbe6a0d13d1c2f81ffbbfa/authlib-1.6.8-py2.py3-none-any.whl", hash = "sha256:97286fd7a15e6cfefc32771c8ef9c54f0ed58028f1322de6a2a7c969c3817888", size = 244116, upload-time = "2026-02-14T04:02:15.579Z" },
 ]
 
 [[package]]
-name = "attrs"
-version = "24.2.0"
+name = "azure-core"
+version = "1.38.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/fc/0f/aafca9af9315aee06a89ffde799a10a582fe8de76c563ee80bbcdc08b3fb/attrs-24.2.0.tar.gz", hash = "sha256:5cfb1b9148b5b086569baec03f20d7b6bf3bcacc9a42bebf87ffaaca362f6346", size = 792678 }
+dependencies = [
+    { name = "requests" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/53/9b/23893febea484ad8183112c9419b5eb904773adb871492b5fa8ff7b21e09/azure_core-1.38.1.tar.gz", hash = "sha256:9317db1d838e39877eb94a2240ce92fa607db68adf821817b723f0d679facbf6", size = 363323, upload-time = "2026-02-11T02:03:06.051Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6a/21/5b6702a7f963e95456c0de2d495f67bf5fd62840ac655dc451586d23d39a/attrs-24.2.0-py3-none-any.whl", hash = "sha256:81921eb96de3191c8258c199618104dd27ac608d9366f5e35d011eae1867ede2", size = 63001 },
+    { url = "https://files.pythonhosted.org/packages/db/88/aaea2ad269ce70b446660371286272c1f6ba66541a7f6f635baf8b0db726/azure_core-1.38.1-py3-none-any.whl", hash = "sha256:69f08ee3d55136071b7100de5b198994fc1c5f89d2b91f2f43156d20fcf200a4", size = 217930, upload-time = "2026-02-11T02:03:07.548Z" },
 ]
 
 [[package]]
-name = "backcall"
-version = "0.2.0"
+name = "azure-identity"
+version = "1.25.2"
+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/c2/3a/439a32a5e23e45f6a91f0405949dc66cfe6834aba15a430aebfc063a81e7/azure_identity-1.25.2.tar.gz", hash = "sha256:030dbaa720266c796221c6cdbd1999b408c079032c919fef725fcc348a540fe9", size = 284709, upload-time = "2026-02-11T01:55:42.323Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/77/f658c76f9e9a52c784bd836aaca6fd5b9aae176f1f53273e758a2bcda695/azure_identity-1.25.2-py3-none-any.whl", hash = "sha256:1b40060553d01a72ba0d708b9a46d0f61f56312e215d8896d836653ffdc6753d", size = 191423, upload-time = "2026-02-11T01:55:44.245Z" },
+]
+
+[[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.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d4/07/56595285564e90777d758ebd383d6b0b971b87729bbe2184a849932a3736/cachetools-7.0.1.tar.gz", hash = "sha256:e31e579d2c5b6e2944177a0397150d312888ddf4e16e12f1016068f0c03b8341", size = 36126, upload-time = "2026-02-10T22:24:05.03Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ed/9e/5faefbf9db1db466d633735faceda1f94aa99ce506ac450d232536266b32/cachetools-7.0.1-py3-none-any.whl", hash = "sha256:8f086515c254d5664ae2146d14fc7f65c9a4bce75152eb247e5a9c5e6d7b2ecf", size = 13484, upload-time = "2026-02-10T22:24:03.741Z" },
+]
+
+[[package]]
+name = "caio"
+version = "0.9.25"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a2/40/764a663805d84deee23043e1426a9175567db89c8b3287b5c2ad9f71aa93/backcall-0.2.0.tar.gz", hash = "sha256:5cbdbf27be5e7cfadb448baf0aa95508f91f2bbc6c6437cd9cd06e2a4c215e1e", size = 18041 }
+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/4c/1c/ff6546b6c12603d8dd1070aa3c3d273ad4c07f5771689a7b69a550e8c951/backcall-0.2.0-py2.py3-none-any.whl", hash = "sha256:fbbce6a29f263178a1f7915c1940bde0ec2b2a967566fe1c65c1dfb7422bd255", size = 11157 },
+    { 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/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/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/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/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/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 = "2024.8.30"
+version = "2026.1.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/b0/ee/9b19140fe824b367c04c5e1b369942dd754c4c5462d5674002f75c4dedc1/certifi-2024.8.30.tar.gz", hash = "sha256:bec941d2aa8195e248a60b31ff9f0558284cf01a52591ceda73ea9afffd69fd9", size = 168507 }
+sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/12/90/3c9ff0512038035f59d279fddeb79f5f1eccd8859f06d6163c58798b9487/certifi-2024.8.30-py3-none-any.whl", hash = "sha256:922820b53db7a7257ffbda3f597266d435245903d80737e34f8a45ff3e3230d8", size = 167321 },
+    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
 ]
 
 [[package]]
-name = "charset-normalizer"
-version = "3.4.0"
+name = "cffi"
+version = "2.0.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f2/4f/e1808dc01273379acc506d18f1504eb2d299bd4131743b9fc54d7be4df1e/charset_normalizer-3.4.0.tar.gz", hash = "sha256:223217c3d4f82c3ac5e29032b3f1c2eb0fb591b72161f86d93f5719079dae93e", size = 106620 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/8b/825cc84cf13a28bfbcba7c416ec22bf85a9584971be15b21dd8300c65b7f/charset_normalizer-3.4.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:4f9fc98dad6c2eaa32fc3af1417d95b5e3d08aff968df0cd320066def971f9a6", size = 196363 },
-    { url = "https://files.pythonhosted.org/packages/23/81/d7eef6a99e42c77f444fdd7bc894b0ceca6c3a95c51239e74a722039521c/charset_normalizer-3.4.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0de7b687289d3c1b3e8660d0741874abe7888100efe14bd0f9fd7141bcbda92b", size = 125639 },
-    { url = "https://files.pythonhosted.org/packages/21/67/b4564d81f48042f520c948abac7079356e94b30cb8ffb22e747532cf469d/charset_normalizer-3.4.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5ed2e36c3e9b4f21dd9422f6893dec0abf2cca553af509b10cd630f878d3eb99", size = 120451 },
-    { url = "https://files.pythonhosted.org/packages/c2/72/12a7f0943dd71fb5b4e7b55c41327ac0a1663046a868ee4d0d8e9c369b85/charset_normalizer-3.4.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:40d3ff7fc90b98c637bda91c89d51264a3dcf210cade3a2c6f838c7268d7a4ca", size = 140041 },
-    { url = "https://files.pythonhosted.org/packages/67/56/fa28c2c3e31217c4c52158537a2cf5d98a6c1e89d31faf476c89391cd16b/charset_normalizer-3.4.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1110e22af8ca26b90bd6364fe4c763329b0ebf1ee213ba32b68c73de5752323d", size = 150333 },
-    { url = "https://files.pythonhosted.org/packages/f9/d2/466a9be1f32d89eb1554cf84073a5ed9262047acee1ab39cbaefc19635d2/charset_normalizer-3.4.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:86f4e8cca779080f66ff4f191a685ced73d2f72d50216f7112185dc02b90b9b7", size = 142921 },
-    { url = "https://files.pythonhosted.org/packages/f8/01/344ec40cf5d85c1da3c1f57566c59e0c9b56bcc5566c08804a95a6cc8257/charset_normalizer-3.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7f683ddc7eedd742e2889d2bfb96d69573fde1d92fcb811979cdb7165bb9c7d3", size = 144785 },
-    { url = "https://files.pythonhosted.org/packages/73/8b/2102692cb6d7e9f03b9a33a710e0164cadfce312872e3efc7cfe22ed26b4/charset_normalizer-3.4.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:27623ba66c183eca01bf9ff833875b459cad267aeeb044477fedac35e19ba907", size = 146631 },
-    { url = "https://files.pythonhosted.org/packages/d8/96/cc2c1b5d994119ce9f088a9a0c3ebd489d360a2eb058e2c8049f27092847/charset_normalizer-3.4.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:f606a1881d2663630ea5b8ce2efe2111740df4b687bd78b34a8131baa007f79b", size = 140867 },
-    { url = "https://files.pythonhosted.org/packages/c9/27/cde291783715b8ec30a61c810d0120411844bc4c23b50189b81188b273db/charset_normalizer-3.4.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:0b309d1747110feb25d7ed6b01afdec269c647d382c857ef4663bbe6ad95a912", size = 149273 },
-    { url = "https://files.pythonhosted.org/packages/3a/a4/8633b0fc1a2d1834d5393dafecce4a1cc56727bfd82b4dc18fc92f0d3cc3/charset_normalizer-3.4.0-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:136815f06a3ae311fae551c3df1f998a1ebd01ddd424aa5603a4336997629e95", size = 152437 },
-    { url = "https://files.pythonhosted.org/packages/64/ea/69af161062166b5975ccbb0961fd2384853190c70786f288684490913bf5/charset_normalizer-3.4.0-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:14215b71a762336254351b00ec720a8e85cada43b987da5a042e4ce3e82bd68e", size = 150087 },
-    { url = "https://files.pythonhosted.org/packages/3b/fd/e60a9d9fd967f4ad5a92810138192f825d77b4fa2a557990fd575a47695b/charset_normalizer-3.4.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:79983512b108e4a164b9c8d34de3992f76d48cadc9554c9e60b43f308988aabe", size = 145142 },
-    { url = "https://files.pythonhosted.org/packages/6d/02/8cb0988a1e49ac9ce2eed1e07b77ff118f2923e9ebd0ede41ba85f2dcb04/charset_normalizer-3.4.0-cp310-cp310-win32.whl", hash = "sha256:c94057af19bc953643a33581844649a7fdab902624d2eb739738a30e2b3e60fc", size = 94701 },
-    { url = "https://files.pythonhosted.org/packages/d6/20/f1d4670a8a723c46be695dff449d86d6092916f9e99c53051954ee33a1bc/charset_normalizer-3.4.0-cp310-cp310-win_amd64.whl", hash = "sha256:55f56e2ebd4e3bc50442fbc0888c9d8c94e4e06a933804e2af3e89e2f9c1c749", size = 102191 },
-    { url = "https://files.pythonhosted.org/packages/9c/61/73589dcc7a719582bf56aae309b6103d2762b526bffe189d635a7fcfd998/charset_normalizer-3.4.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:0d99dd8ff461990f12d6e42c7347fd9ab2532fb70e9621ba520f9e8637161d7c", size = 193339 },
-    { url = "https://files.pythonhosted.org/packages/77/d5/8c982d58144de49f59571f940e329ad6e8615e1e82ef84584c5eeb5e1d72/charset_normalizer-3.4.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:c57516e58fd17d03ebe67e181a4e4e2ccab1168f8c2976c6a334d4f819fe5944", size = 124366 },
-    { url = "https://files.pythonhosted.org/packages/bf/19/411a64f01ee971bed3231111b69eb56f9331a769072de479eae7de52296d/charset_normalizer-3.4.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6dba5d19c4dfab08e58d5b36304b3f92f3bd5d42c1a3fa37b5ba5cdf6dfcbcee", size = 118874 },
-    { url = "https://files.pythonhosted.org/packages/4c/92/97509850f0d00e9f14a46bc751daabd0ad7765cff29cdfb66c68b6dad57f/charset_normalizer-3.4.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bf4475b82be41b07cc5e5ff94810e6a01f276e37c2d55571e3fe175e467a1a1c", size = 138243 },
-    { url = "https://files.pythonhosted.org/packages/e2/29/d227805bff72ed6d6cb1ce08eec707f7cfbd9868044893617eb331f16295/charset_normalizer-3.4.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ce031db0408e487fd2775d745ce30a7cd2923667cf3b69d48d219f1d8f5ddeb6", size = 148676 },
-    { url = "https://files.pythonhosted.org/packages/13/bc/87c2c9f2c144bedfa62f894c3007cd4530ba4b5351acb10dc786428a50f0/charset_normalizer-3.4.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8ff4e7cdfdb1ab5698e675ca622e72d58a6fa2a8aa58195de0c0061288e6e3ea", size = 141289 },
-    { url = "https://files.pythonhosted.org/packages/eb/5b/6f10bad0f6461fa272bfbbdf5d0023b5fb9bc6217c92bf068fa5a99820f5/charset_normalizer-3.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3710a9751938947e6327ea9f3ea6332a09bf0ba0c09cae9cb1f250bd1f1549bc", size = 142585 },
-    { url = "https://files.pythonhosted.org/packages/3b/a0/a68980ab8a1f45a36d9745d35049c1af57d27255eff8c907e3add84cf68f/charset_normalizer-3.4.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:82357d85de703176b5587dbe6ade8ff67f9f69a41c0733cf2425378b49954de5", size = 144408 },
-    { url = "https://files.pythonhosted.org/packages/d7/a1/493919799446464ed0299c8eef3c3fad0daf1c3cd48bff9263c731b0d9e2/charset_normalizer-3.4.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:47334db71978b23ebcf3c0f9f5ee98b8d65992b65c9c4f2d34c2eaf5bcaf0594", size = 139076 },
-    { url = "https://files.pythonhosted.org/packages/fb/9d/9c13753a5a6e0db4a0a6edb1cef7aee39859177b64e1a1e748a6e3ba62c2/charset_normalizer-3.4.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:8ce7fd6767a1cc5a92a639b391891bf1c268b03ec7e021c7d6d902285259685c", size = 146874 },
-    { url = "https://files.pythonhosted.org/packages/75/d2/0ab54463d3410709c09266dfb416d032a08f97fd7d60e94b8c6ef54ae14b/charset_normalizer-3.4.0-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:f1a2f519ae173b5b6a2c9d5fa3116ce16e48b3462c8b96dfdded11055e3d6365", size = 150871 },
-    { url = "https://files.pythonhosted.org/packages/8d/c9/27e41d481557be53d51e60750b85aa40eaf52b841946b3cdeff363105737/charset_normalizer-3.4.0-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:63bc5c4ae26e4bc6be6469943b8253c0fd4e4186c43ad46e713ea61a0ba49129", size = 148546 },
-    { url = "https://files.pythonhosted.org/packages/ee/44/4f62042ca8cdc0cabf87c0fc00ae27cd8b53ab68be3605ba6d071f742ad3/charset_normalizer-3.4.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bcb4f8ea87d03bc51ad04add8ceaf9b0f085ac045ab4d74e73bbc2dc033f0236", size = 143048 },
-    { url = "https://files.pythonhosted.org/packages/01/f8/38842422988b795220eb8038745d27a675ce066e2ada79516c118f291f07/charset_normalizer-3.4.0-cp311-cp311-win32.whl", hash = "sha256:9ae4ef0b3f6b41bad6366fb0ea4fc1d7ed051528e113a60fa2a65a9abb5b1d99", size = 94389 },
-    { url = "https://files.pythonhosted.org/packages/0b/6e/b13bd47fa9023b3699e94abf565b5a2f0b0be6e9ddac9812182596ee62e4/charset_normalizer-3.4.0-cp311-cp311-win_amd64.whl", hash = "sha256:cee4373f4d3ad28f1ab6290684d8e2ebdb9e7a1b74fdc39e4c211995f77bec27", size = 101752 },
-    { url = "https://files.pythonhosted.org/packages/d3/0b/4b7a70987abf9b8196845806198975b6aab4ce016632f817ad758a5aa056/charset_normalizer-3.4.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0713f3adb9d03d49d365b70b84775d0a0d18e4ab08d12bc46baa6132ba78aaf6", size = 194445 },
-    { url = "https://files.pythonhosted.org/packages/50/89/354cc56cf4dd2449715bc9a0f54f3aef3dc700d2d62d1fa5bbea53b13426/charset_normalizer-3.4.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:de7376c29d95d6719048c194a9cf1a1b0393fbe8488a22008610b0361d834ecf", size = 125275 },
-    { url = "https://files.pythonhosted.org/packages/fa/44/b730e2a2580110ced837ac083d8ad222343c96bb6b66e9e4e706e4d0b6df/charset_normalizer-3.4.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4a51b48f42d9358460b78725283f04bddaf44a9358197b889657deba38f329db", size = 119020 },
-    { url = "https://files.pythonhosted.org/packages/9d/e4/9263b8240ed9472a2ae7ddc3e516e71ef46617fe40eaa51221ccd4ad9a27/charset_normalizer-3.4.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b295729485b06c1a0683af02a9e42d2caa9db04a373dc38a6a58cdd1e8abddf1", size = 139128 },
-    { url = "https://files.pythonhosted.org/packages/6b/e3/9f73e779315a54334240353eaea75854a9a690f3f580e4bd85d977cb2204/charset_normalizer-3.4.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ee803480535c44e7f5ad00788526da7d85525cfefaf8acf8ab9a310000be4b03", size = 149277 },
-    { url = "https://files.pythonhosted.org/packages/1a/cf/f1f50c2f295312edb8a548d3fa56a5c923b146cd3f24114d5adb7e7be558/charset_normalizer-3.4.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3d59d125ffbd6d552765510e3f31ed75ebac2c7470c7274195b9161a32350284", size = 142174 },
-    { url = "https://files.pythonhosted.org/packages/16/92/92a76dc2ff3a12e69ba94e7e05168d37d0345fa08c87e1fe24d0c2a42223/charset_normalizer-3.4.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8cda06946eac330cbe6598f77bb54e690b4ca93f593dee1568ad22b04f347c15", size = 143838 },
-    { url = "https://files.pythonhosted.org/packages/a4/01/2117ff2b1dfc61695daf2babe4a874bca328489afa85952440b59819e9d7/charset_normalizer-3.4.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:07afec21bbbbf8a5cc3651aa96b980afe2526e7f048fdfb7f1014d84acc8b6d8", size = 146149 },
-    { url = "https://files.pythonhosted.org/packages/f6/9b/93a332b8d25b347f6839ca0a61b7f0287b0930216994e8bf67a75d050255/charset_normalizer-3.4.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:6b40e8d38afe634559e398cc32b1472f376a4099c75fe6299ae607e404c033b2", size = 140043 },
-    { url = "https://files.pythonhosted.org/packages/ab/f6/7ac4a01adcdecbc7a7587767c776d53d369b8b971382b91211489535acf0/charset_normalizer-3.4.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:b8dcd239c743aa2f9c22ce674a145e0a25cb1566c495928440a181ca1ccf6719", size = 148229 },
-    { url = "https://files.pythonhosted.org/packages/9d/be/5708ad18161dee7dc6a0f7e6cf3a88ea6279c3e8484844c0590e50e803ef/charset_normalizer-3.4.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:84450ba661fb96e9fd67629b93d2941c871ca86fc38d835d19d4225ff946a631", size = 151556 },
-    { url = "https://files.pythonhosted.org/packages/5a/bb/3d8bc22bacb9eb89785e83e6723f9888265f3a0de3b9ce724d66bd49884e/charset_normalizer-3.4.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:44aeb140295a2f0659e113b31cfe92c9061622cadbc9e2a2f7b8ef6b1e29ef4b", size = 149772 },
-    { url = "https://files.pythonhosted.org/packages/f7/fa/d3fc622de05a86f30beea5fc4e9ac46aead4731e73fd9055496732bcc0a4/charset_normalizer-3.4.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:1db4e7fefefd0f548d73e2e2e041f9df5c59e178b4c72fbac4cc6f535cfb1565", size = 144800 },
-    { url = "https://files.pythonhosted.org/packages/9a/65/bdb9bc496d7d190d725e96816e20e2ae3a6fa42a5cac99c3c3d6ff884118/charset_normalizer-3.4.0-cp312-cp312-win32.whl", hash = "sha256:5726cf76c982532c1863fb64d8c6dd0e4c90b6ece9feb06c9f202417a31f7dd7", size = 94836 },
-    { url = "https://files.pythonhosted.org/packages/3e/67/7b72b69d25b89c0b3cea583ee372c43aa24df15f0e0f8d3982c57804984b/charset_normalizer-3.4.0-cp312-cp312-win_amd64.whl", hash = "sha256:b197e7094f232959f8f20541ead1d9862ac5ebea1d58e9849c1bf979255dfac9", size = 102187 },
-    { url = "https://files.pythonhosted.org/packages/f3/89/68a4c86f1a0002810a27f12e9a7b22feb198c59b2f05231349fbce5c06f4/charset_normalizer-3.4.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:dd4eda173a9fcccb5f2e2bd2a9f423d180194b1bf17cf59e3269899235b2a114", size = 194617 },
-    { url = "https://files.pythonhosted.org/packages/4f/cd/8947fe425e2ab0aa57aceb7807af13a0e4162cd21eee42ef5b053447edf5/charset_normalizer-3.4.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e9e3c4c9e1ed40ea53acf11e2a386383c3304212c965773704e4603d589343ed", size = 125310 },
-    { url = "https://files.pythonhosted.org/packages/5b/f0/b5263e8668a4ee9becc2b451ed909e9c27058337fda5b8c49588183c267a/charset_normalizer-3.4.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:92a7e36b000bf022ef3dbb9c46bfe2d52c047d5e3f3343f43204263c5addc250", size = 119126 },
-    { url = "https://files.pythonhosted.org/packages/ff/6e/e445afe4f7fda27a533f3234b627b3e515a1b9429bc981c9a5e2aa5d97b6/charset_normalizer-3.4.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:54b6a92d009cbe2fb11054ba694bc9e284dad30a26757b1e372a1fdddaf21920", size = 139342 },
-    { url = "https://files.pythonhosted.org/packages/a1/b2/4af9993b532d93270538ad4926c8e37dc29f2111c36f9c629840c57cd9b3/charset_normalizer-3.4.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1ffd9493de4c922f2a38c2bf62b831dcec90ac673ed1ca182fe11b4d8e9f2a64", size = 149383 },
-    { url = "https://files.pythonhosted.org/packages/fb/6f/4e78c3b97686b871db9be6f31d64e9264e889f8c9d7ab33c771f847f79b7/charset_normalizer-3.4.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:35c404d74c2926d0287fbd63ed5d27eb911eb9e4a3bb2c6d294f3cfd4a9e0c23", size = 142214 },
-    { url = "https://files.pythonhosted.org/packages/2b/c9/1c8fe3ce05d30c87eff498592c89015b19fade13df42850aafae09e94f35/charset_normalizer-3.4.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4796efc4faf6b53a18e3d46343535caed491776a22af773f366534056c4e1fbc", size = 144104 },
-    { url = "https://files.pythonhosted.org/packages/ee/68/efad5dcb306bf37db7db338338e7bb8ebd8cf38ee5bbd5ceaaaa46f257e6/charset_normalizer-3.4.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e7fdd52961feb4c96507aa649550ec2a0d527c086d284749b2f582f2d40a2e0d", size = 146255 },
-    { url = "https://files.pythonhosted.org/packages/0c/75/1ed813c3ffd200b1f3e71121c95da3f79e6d2a96120163443b3ad1057505/charset_normalizer-3.4.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:92db3c28b5b2a273346bebb24857fda45601aef6ae1c011c0a997106581e8a88", size = 140251 },
-    { url = "https://files.pythonhosted.org/packages/7d/0d/6f32255c1979653b448d3c709583557a4d24ff97ac4f3a5be156b2e6a210/charset_normalizer-3.4.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ab973df98fc99ab39080bfb0eb3a925181454d7c3ac8a1e695fddfae696d9e90", size = 148474 },
-    { url = "https://files.pythonhosted.org/packages/ac/a0/c1b5298de4670d997101fef95b97ac440e8c8d8b4efa5a4d1ef44af82f0d/charset_normalizer-3.4.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:4b67fdab07fdd3c10bb21edab3cbfe8cf5696f453afce75d815d9d7223fbe88b", size = 151849 },
-    { url = "https://files.pythonhosted.org/packages/04/4f/b3961ba0c664989ba63e30595a3ed0875d6790ff26671e2aae2fdc28a399/charset_normalizer-3.4.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:aa41e526a5d4a9dfcfbab0716c7e8a1b215abd3f3df5a45cf18a12721d31cb5d", size = 149781 },
-    { url = "https://files.pythonhosted.org/packages/d8/90/6af4cd042066a4adad58ae25648a12c09c879efa4849c705719ba1b23d8c/charset_normalizer-3.4.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ffc519621dce0c767e96b9c53f09c5d215578e10b02c285809f76509a3931482", size = 144970 },
-    { url = "https://files.pythonhosted.org/packages/cc/67/e5e7e0cbfefc4ca79025238b43cdf8a2037854195b37d6417f3d0895c4c2/charset_normalizer-3.4.0-cp313-cp313-win32.whl", hash = "sha256:f19c1585933c82098c2a520f8ec1227f20e339e33aca8fa6f956f6691b784e67", size = 94973 },
-    { url = "https://files.pythonhosted.org/packages/65/97/fc9bbc54ee13d33dc54a7fcf17b26368b18505500fc01e228c27b5222d80/charset_normalizer-3.4.0-cp313-cp313-win_amd64.whl", hash = "sha256:707b82d19e65c9bd28b81dde95249b07bf9f5b90ebe1ef17d9b57473f8a64b7b", size = 102308 },
-    { url = "https://files.pythonhosted.org/packages/bf/9b/08c0432272d77b04803958a4598a51e2a4b51c06640af8b8f0f908c18bf2/charset_normalizer-3.4.0-py3-none-any.whl", hash = "sha256:fe9f97feb71aa9896b81973a7bbada8c49501dc73e58a10fcef6663af95e5079", size = 49446 },
+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.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/13/69/33ddede1939fdd074bce5434295f38fae7136463422fe4fd3e0e89b98062/charset_normalizer-3.4.4.tar.gz", hash = "sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a", size = 129418, upload-time = "2025-10-14T04:42:32.879Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1f/b8/6d51fc1d52cbd52cd4ccedd5b5b2f0f6a11bbf6765c782298b0f3e808541/charset_normalizer-3.4.4-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:e824f1492727fa856dd6eda4f7cee25f8518a12f3c4a56a74e8095695089cf6d", size = 209709, upload-time = "2025-10-14T04:40:11.385Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/af/1f9d7f7faafe2ddfb6f72a2e07a548a629c61ad510fe60f9630309908fef/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4bd5d4137d500351a30687c2d3971758aac9a19208fc110ccb9d7188fbe709e8", size = 148814, upload-time = "2025-10-14T04:40:13.135Z" },
+    { url = "https://files.pythonhosted.org/packages/79/3d/f2e3ac2bbc056ca0c204298ea4e3d9db9b4afe437812638759db2c976b5f/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:027f6de494925c0ab2a55eab46ae5129951638a49a34d87f4c3eda90f696b4ad", size = 144467, upload-time = "2025-10-14T04:40:14.728Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/85/1bf997003815e60d57de7bd972c57dc6950446a3e4ccac43bc3070721856/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f820802628d2694cb7e56db99213f930856014862f3fd943d290ea8438d07ca8", size = 162280, upload-time = "2025-10-14T04:40:16.14Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/8e/6aa1952f56b192f54921c436b87f2aaf7c7a7c3d0d1a765547d64fd83c13/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:798d75d81754988d2565bff1b97ba5a44411867c0cf32b77a7e8f8d84796b10d", size = 159454, upload-time = "2025-10-14T04:40:17.567Z" },
+    { url = "https://files.pythonhosted.org/packages/36/3b/60cbd1f8e93aa25d1c669c649b7a655b0b5fb4c571858910ea9332678558/charset_normalizer-3.4.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d1bb833febdff5c8927f922386db610b49db6e0d4f4ee29601d71e7c2694313", size = 153609, upload-time = "2025-10-14T04:40:19.08Z" },
+    { url = "https://files.pythonhosted.org/packages/64/91/6a13396948b8fd3c4b4fd5bc74d045f5637d78c9675585e8e9fbe5636554/charset_normalizer-3.4.4-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:9cd98cdc06614a2f768d2b7286d66805f94c48cde050acdbbb7db2600ab3197e", size = 151849, upload-time = "2025-10-14T04:40:20.607Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/7a/59482e28b9981d105691e968c544cc0df3b7d6133152fb3dcdc8f135da7a/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:077fbb858e903c73f6c9db43374fd213b0b6a778106bc7032446a8e8b5b38b93", size = 151586, upload-time = "2025-10-14T04:40:21.719Z" },
+    { url = "https://files.pythonhosted.org/packages/92/59/f64ef6a1c4bdd2baf892b04cd78792ed8684fbc48d4c2afe467d96b4df57/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:244bfb999c71b35de57821b8ea746b24e863398194a4014e4c76adc2bbdfeff0", size = 145290, upload-time = "2025-10-14T04:40:23.069Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/63/3bf9f279ddfa641ffa1962b0db6a57a9c294361cc2f5fcac997049a00e9c/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:64b55f9dce520635f018f907ff1b0df1fdc31f2795a922fb49dd14fbcdf48c84", size = 163663, upload-time = "2025-10-14T04:40:24.17Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/09/c9e38fc8fa9e0849b172b581fd9803bdf6e694041127933934184e19f8c3/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:faa3a41b2b66b6e50f84ae4a68c64fcd0c44355741c6374813a800cd6695db9e", size = 151964, upload-time = "2025-10-14T04:40:25.368Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/d1/d28b747e512d0da79d8b6a1ac18b7ab2ecfd81b2944c4c710e166d8dd09c/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:6515f3182dbe4ea06ced2d9e8666d97b46ef4c75e326b79bb624110f122551db", size = 161064, upload-time = "2025-10-14T04:40:26.806Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/9a/31d62b611d901c3b9e5500c36aab0ff5eb442043fb3a1c254200d3d397d9/charset_normalizer-3.4.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:cc00f04ed596e9dc0da42ed17ac5e596c6ccba999ba6bd92b0e0aef2f170f2d6", size = 155015, upload-time = "2025-10-14T04:40:28.284Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f3/107e008fa2bff0c8b9319584174418e5e5285fef32f79d8ee6a430d0039c/charset_normalizer-3.4.4-cp310-cp310-win32.whl", hash = "sha256:f34be2938726fc13801220747472850852fe6b1ea75869a048d6f896838c896f", size = 99792, upload-time = "2025-10-14T04:40:29.613Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/66/e396e8a408843337d7315bab30dbf106c38966f1819f123257f5520f8a96/charset_normalizer-3.4.4-cp310-cp310-win_amd64.whl", hash = "sha256:a61900df84c667873b292c3de315a786dd8dac506704dea57bc957bd31e22c7d", size = 107198, upload-time = "2025-10-14T04:40:30.644Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/58/01b4f815bf0312704c267f2ccb6e5d42bcc7752340cd487bc9f8c3710597/charset_normalizer-3.4.4-cp310-cp310-win_arm64.whl", hash = "sha256:cead0978fc57397645f12578bfd2d5ea9138ea0fac82b2f63f7f7c6877986a69", size = 100262, upload-time = "2025-10-14T04:40:32.108Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/27/c6491ff4954e58a10f69ad90aca8a1b6fe9c5d3c6f380907af3c37435b59/charset_normalizer-3.4.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6e1fcf0720908f200cd21aa4e6750a48ff6ce4afe7ff5a79a90d5ed8a08296f8", size = 206988, upload-time = "2025-10-14T04:40:33.79Z" },
+    { url = "https://files.pythonhosted.org/packages/94/59/2e87300fe67ab820b5428580a53cad894272dbb97f38a7a814a2a1ac1011/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5f819d5fe9234f9f82d75bdfa9aef3a3d72c4d24a6e57aeaebba32a704553aa0", size = 147324, upload-time = "2025-10-14T04:40:34.961Z" },
+    { url = "https://files.pythonhosted.org/packages/07/fb/0cf61dc84b2b088391830f6274cb57c82e4da8bbc2efeac8c025edb88772/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:a59cb51917aa591b1c4e6a43c132f0cdc3c76dbad6155df4e28ee626cc77a0a3", size = 142742, upload-time = "2025-10-14T04:40:36.105Z" },
+    { url = "https://files.pythonhosted.org/packages/62/8b/171935adf2312cd745d290ed93cf16cf0dfe320863ab7cbeeae1dcd6535f/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8ef3c867360f88ac904fd3f5e1f902f13307af9052646963ee08ff4f131adafc", size = 160863, upload-time = "2025-10-14T04:40:37.188Z" },
+    { url = "https://files.pythonhosted.org/packages/09/73/ad875b192bda14f2173bfc1bc9a55e009808484a4b256748d931b6948442/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d9e45d7faa48ee908174d8fe84854479ef838fc6a705c9315372eacbc2f02897", size = 157837, upload-time = "2025-10-14T04:40:38.435Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/fc/de9cce525b2c5b94b47c70a4b4fb19f871b24995c728e957ee68ab1671ea/charset_normalizer-3.4.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:840c25fb618a231545cbab0564a799f101b63b9901f2569faecd6b222ac72381", size = 151550, upload-time = "2025-10-14T04:40:40.053Z" },
+    { url = "https://files.pythonhosted.org/packages/55/c2/43edd615fdfba8c6f2dfbd459b25a6b3b551f24ea21981e23fb768503ce1/charset_normalizer-3.4.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ca5862d5b3928c4940729dacc329aa9102900382fea192fc5e52eb69d6093815", size = 149162, upload-time = "2025-10-14T04:40:41.163Z" },
+    { url = "https://files.pythonhosted.org/packages/03/86/bde4ad8b4d0e9429a4e82c1e8f5c659993a9a863ad62c7df05cf7b678d75/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d9c7f57c3d666a53421049053eaacdd14bbd0a528e2186fcb2e672effd053bb0", size = 150019, upload-time = "2025-10-14T04:40:42.276Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/86/a151eb2af293a7e7bac3a739b81072585ce36ccfb4493039f49f1d3cae8c/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:277e970e750505ed74c832b4bf75dac7476262ee2a013f5574dd49075879e161", size = 143310, upload-time = "2025-10-14T04:40:43.439Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/fe/43dae6144a7e07b87478fdfc4dbe9efd5defb0e7ec29f5f58a55aeef7bf7/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:31fd66405eaf47bb62e8cd575dc621c56c668f27d46a61d975a249930dd5e2a4", size = 162022, upload-time = "2025-10-14T04:40:44.547Z" },
+    { url = "https://files.pythonhosted.org/packages/80/e6/7aab83774f5d2bca81f42ac58d04caf44f0cc2b65fc6db2b3b2e8a05f3b3/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:0d3d8f15c07f86e9ff82319b3d9ef6f4bf907608f53fe9d92b28ea9ae3d1fd89", size = 149383, upload-time = "2025-10-14T04:40:46.018Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/e8/b289173b4edae05c0dde07f69f8db476a0b511eac556dfe0d6bda3c43384/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:9f7fcd74d410a36883701fafa2482a6af2ff5ba96b9a620e9e0721e28ead5569", size = 159098, upload-time = "2025-10-14T04:40:47.081Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/df/fe699727754cae3f8478493c7f45f777b17c3ef0600e28abfec8619eb49c/charset_normalizer-3.4.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ebf3e58c7ec8a8bed6d66a75d7fb37b55e5015b03ceae72a8e7c74495551e224", size = 152991, upload-time = "2025-10-14T04:40:48.246Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/86/584869fe4ddb6ffa3bd9f491b87a01568797fb9bd8933f557dba9771beaf/charset_normalizer-3.4.4-cp311-cp311-win32.whl", hash = "sha256:eecbc200c7fd5ddb9a7f16c7decb07b566c29fa2161a16cf67b8d068bd21690a", size = 99456, upload-time = "2025-10-14T04:40:49.376Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f6/62fdd5feb60530f50f7e38b4f6a1d5203f4d16ff4f9f0952962c044e919a/charset_normalizer-3.4.4-cp311-cp311-win_amd64.whl", hash = "sha256:5ae497466c7901d54b639cf42d5b8c1b6a4fead55215500d2f486d34db48d016", size = 106978, upload-time = "2025-10-14T04:40:50.844Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/9d/0710916e6c82948b3be62d9d398cb4fcf4e97b56d6a6aeccd66c4b2f2bd5/charset_normalizer-3.4.4-cp311-cp311-win_arm64.whl", hash = "sha256:65e2befcd84bc6f37095f5961e68a6f077bf44946771354a28ad434c2cce0ae1", size = 99969, upload-time = "2025-10-14T04:40:52.272Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/85/1637cd4af66fa687396e757dec650f28025f2a2f5a5531a3208dc0ec43f2/charset_normalizer-3.4.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0a98e6759f854bd25a58a73fa88833fba3b7c491169f86ce1180c948ab3fd394", size = 208425, upload-time = "2025-10-14T04:40:53.353Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/6a/04130023fef2a0d9c62d0bae2649b69f7b7d8d24ea5536feef50551029df/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b5b290ccc2a263e8d185130284f8501e3e36c5e02750fc6b6bdeb2e9e96f1e25", size = 148162, upload-time = "2025-10-14T04:40:54.558Z" },
+    { url = "https://files.pythonhosted.org/packages/78/29/62328d79aa60da22c9e0b9a66539feae06ca0f5a4171ac4f7dc285b83688/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74bb723680f9f7a6234dcf67aea57e708ec1fbdf5699fb91dfd6f511b0a320ef", size = 144558, upload-time = "2025-10-14T04:40:55.677Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bb/b32194a4bf15b88403537c2e120b817c61cd4ecffa9b6876e941c3ee38fe/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f1e34719c6ed0b92f418c7c780480b26b5d9c50349e9a9af7d76bf757530350d", size = 161497, upload-time = "2025-10-14T04:40:57.217Z" },
+    { url = "https://files.pythonhosted.org/packages/19/89/a54c82b253d5b9b111dc74aca196ba5ccfcca8242d0fb64146d4d3183ff1/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2437418e20515acec67d86e12bf70056a33abdacb5cb1655042f6538d6b085a8", size = 159240, upload-time = "2025-10-14T04:40:58.358Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/10/d20b513afe03acc89ec33948320a5544d31f21b05368436d580dec4e234d/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:11d694519d7f29d6cd09f6ac70028dba10f92f6cdd059096db198c283794ac86", size = 153471, upload-time = "2025-10-14T04:40:59.468Z" },
+    { url = "https://files.pythonhosted.org/packages/61/fa/fbf177b55bdd727010f9c0a3c49eefa1d10f960e5f09d1d887bf93c2e698/charset_normalizer-3.4.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ac1c4a689edcc530fc9d9aa11f5774b9e2f33f9a0c6a57864e90908f5208d30a", size = 150864, upload-time = "2025-10-14T04:41:00.623Z" },
+    { url = "https://files.pythonhosted.org/packages/05/12/9fbc6a4d39c0198adeebbde20b619790e9236557ca59fc40e0e3cebe6f40/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:21d142cc6c0ec30d2efee5068ca36c128a30b0f2c53c1c07bd78cb6bc1d3be5f", size = 150647, upload-time = "2025-10-14T04:41:01.754Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/1f/6a9a593d52e3e8c5d2b167daf8c6b968808efb57ef4c210acb907c365bc4/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:5dbe56a36425d26d6cfb40ce79c314a2e4dd6211d51d6d2191c00bed34f354cc", size = 145110, upload-time = "2025-10-14T04:41:03.231Z" },
+    { url = "https://files.pythonhosted.org/packages/30/42/9a52c609e72471b0fc54386dc63c3781a387bb4fe61c20231a4ebcd58bdd/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:5bfbb1b9acf3334612667b61bd3002196fe2a1eb4dd74d247e0f2a4d50ec9bbf", size = 162839, upload-time = "2025-10-14T04:41:04.715Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/5b/c0682bbf9f11597073052628ddd38344a3d673fda35a36773f7d19344b23/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:d055ec1e26e441f6187acf818b73564e6e6282709e9bcb5b63f5b23068356a15", size = 150667, upload-time = "2025-10-14T04:41:05.827Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/24/a41afeab6f990cf2daf6cb8c67419b63b48cf518e4f56022230840c9bfb2/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:af2d8c67d8e573d6de5bc30cdb27e9b95e49115cd9baad5ddbd1a6207aaa82a9", size = 160535, upload-time = "2025-10-14T04:41:06.938Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/e5/6a4ce77ed243c4a50a1fecca6aaaab419628c818a49434be428fe24c9957/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:780236ac706e66881f3b7f2f32dfe90507a09e67d1d454c762cf642e6e1586e0", size = 154816, upload-time = "2025-10-14T04:41:08.101Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/ef/89297262b8092b312d29cdb2517cb1237e51db8ecef2e9af5edbe7b683b1/charset_normalizer-3.4.4-cp312-cp312-win32.whl", hash = "sha256:5833d2c39d8896e4e19b689ffc198f08ea58116bee26dea51e362ecc7cd3ed26", size = 99694, upload-time = "2025-10-14T04:41:09.23Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/2d/1e5ed9dd3b3803994c155cd9aacb60c82c331bad84daf75bcb9c91b3295e/charset_normalizer-3.4.4-cp312-cp312-win_amd64.whl", hash = "sha256:a79cfe37875f822425b89a82333404539ae63dbdddf97f84dcbc3d339aae9525", size = 107131, upload-time = "2025-10-14T04:41:10.467Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/d9/0ed4c7098a861482a7b6a95603edce4c0d9db2311af23da1fb2b75ec26fc/charset_normalizer-3.4.4-cp312-cp312-win_arm64.whl", hash = "sha256:376bec83a63b8021bb5c8ea75e21c4ccb86e7e45ca4eb81146091b56599b80c3", size = 100390, upload-time = "2025-10-14T04:41:11.915Z" },
+    { url = "https://files.pythonhosted.org/packages/97/45/4b3a1239bbacd321068ea6e7ac28875b03ab8bc0aa0966452db17cd36714/charset_normalizer-3.4.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794", size = 208091, upload-time = "2025-10-14T04:41:13.346Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/62/73a6d7450829655a35bb88a88fca7d736f9882a27eacdca2c6d505b57e2e/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed", size = 147936, upload-time = "2025-10-14T04:41:14.461Z" },
+    { url = "https://files.pythonhosted.org/packages/89/c5/adb8c8b3d6625bef6d88b251bbb0d95f8205831b987631ab0c8bb5d937c2/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72", size = 144180, upload-time = "2025-10-14T04:41:15.588Z" },
+    { url = "https://files.pythonhosted.org/packages/91/ed/9706e4070682d1cc219050b6048bfd293ccf67b3d4f5a4f39207453d4b99/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328", size = 161346, upload-time = "2025-10-14T04:41:16.738Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/0d/031f0d95e4972901a2f6f09ef055751805ff541511dc1252ba3ca1f80cf5/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede", size = 158874, upload-time = "2025-10-14T04:41:17.923Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/83/6ab5883f57c9c801ce5e5677242328aa45592be8a00644310a008d04f922/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894", size = 153076, upload-time = "2025-10-14T04:41:19.106Z" },
+    { url = "https://files.pythonhosted.org/packages/75/1e/5ff781ddf5260e387d6419959ee89ef13878229732732ee73cdae01800f2/charset_normalizer-3.4.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1", size = 150601, upload-time = "2025-10-14T04:41:20.245Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/57/71be810965493d3510a6ca79b90c19e48696fb1ff964da319334b12677f0/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490", size = 150376, upload-time = "2025-10-14T04:41:21.398Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/d5/c3d057a78c181d007014feb7e9f2e65905a6c4ef182c0ddf0de2924edd65/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44", size = 144825, upload-time = "2025-10-14T04:41:22.583Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8c/d0406294828d4976f275ffbe66f00266c4b3136b7506941d87c00cab5272/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133", size = 162583, upload-time = "2025-10-14T04:41:23.754Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/24/e2aa1f18c8f15c4c0e932d9287b8609dd30ad56dbe41d926bd846e22fb8d/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3", size = 150366, upload-time = "2025-10-14T04:41:25.27Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/5b/1e6160c7739aad1e2df054300cc618b06bf784a7a164b0f238360721ab86/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e", size = 160300, upload-time = "2025-10-14T04:41:26.725Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/10/f882167cd207fbdd743e55534d5d9620e095089d176d55cb22d5322f2afd/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc", size = 154465, upload-time = "2025-10-14T04:41:28.322Z" },
+    { url = "https://files.pythonhosted.org/packages/89/66/c7a9e1b7429be72123441bfdbaf2bc13faab3f90b933f664db506dea5915/charset_normalizer-3.4.4-cp313-cp313-win32.whl", hash = "sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac", size = 99404, upload-time = "2025-10-14T04:41:29.95Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/26/b9924fa27db384bdcd97ab83b4f0a8058d96ad9626ead570674d5e737d90/charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14", size = 107092, upload-time = "2025-10-14T04:41:31.188Z" },
+    { url = "https://files.pythonhosted.org/packages/af/8f/3ed4bfa0c0c72a7ca17f0380cd9e4dd842b09f664e780c13cff1dcf2ef1b/charset_normalizer-3.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2", size = 100408, upload-time = "2025-10-14T04:41:32.624Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/35/7051599bd493e62411d6ede36fd5af83a38f37c4767b92884df7301db25d/charset_normalizer-3.4.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:da3326d9e65ef63a817ecbcc0df6e94463713b754fe293eaa03da99befb9a5bd", size = 207746, upload-time = "2025-10-14T04:41:33.773Z" },
+    { url = "https://files.pythonhosted.org/packages/10/9a/97c8d48ef10d6cd4fcead2415523221624bf58bcf68a802721a6bc807c8f/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8af65f14dc14a79b924524b1e7fffe304517b2bff5a58bf64f30b98bbc5079eb", size = 147889, upload-time = "2025-10-14T04:41:34.897Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/979224a919a1b606c82bd2c5fa49b5c6d5727aa47b4312bb27b1734f53cd/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74664978bb272435107de04e36db5a9735e78232b85b77d45cfb38f758efd33e", size = 143641, upload-time = "2025-10-14T04:41:36.116Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/33/0ad65587441fc730dc7bd90e9716b30b4702dc7b617e6ba4997dc8651495/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:752944c7ffbfdd10c074dc58ec2d5a8a4cd9493b314d367c14d24c17684ddd14", size = 160779, upload-time = "2025-10-14T04:41:37.229Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ed/331d6b249259ee71ddea93f6f2f0a56cfebd46938bde6fcc6f7b9a3d0e09/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d1f13550535ad8cff21b8d757a3257963e951d96e20ec82ab44bc64aeb62a191", size = 159035, upload-time = "2025-10-14T04:41:38.368Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ff/f6b948ca32e4f2a4576aa129d8bed61f2e0543bf9f5f2b7fc3758ed005c9/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ecaae4149d99b1c9e7b88bb03e3221956f68fd6d50be2ef061b2381b61d20838", size = 152542, upload-time = "2025-10-14T04:41:39.862Z" },
+    { url = "https://files.pythonhosted.org/packages/16/85/276033dcbcc369eb176594de22728541a925b2632f9716428c851b149e83/charset_normalizer-3.4.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cb6254dc36b47a990e59e1068afacdcd02958bdcce30bb50cc1700a8b9d624a6", size = 149524, upload-time = "2025-10-14T04:41:41.319Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/f2/6a2a1f722b6aba37050e626530a46a68f74e63683947a8acff92569f979a/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c8ae8a0f02f57a6e61203a31428fa1d677cbe50c93622b4149d5c0f319c1d19e", size = 150395, upload-time = "2025-10-14T04:41:42.539Z" },
+    { url = "https://files.pythonhosted.org/packages/60/bb/2186cb2f2bbaea6338cad15ce23a67f9b0672929744381e28b0592676824/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:47cc91b2f4dd2833fddaedd2893006b0106129d4b94fdb6af1f4ce5a9965577c", size = 143680, upload-time = "2025-10-14T04:41:43.661Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/a5/bf6f13b772fbb2a90360eb620d52ed8f796f3c5caee8398c3b2eb7b1c60d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:82004af6c302b5d3ab2cfc4cc5f29db16123b1a8417f2e25f9066f91d4411090", size = 162045, upload-time = "2025-10-14T04:41:44.821Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c5/d1be898bf0dc3ef9030c3825e5d3b83f2c528d207d246cbabe245966808d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b7d8f6c26245217bd2ad053761201e9f9680f8ce52f0fcd8d0755aeae5b2152", size = 149687, upload-time = "2025-10-14T04:41:46.442Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/42/90c1f7b9341eef50c8a1cb3f098ac43b0508413f33affd762855f67a410e/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:799a7a5e4fb2d5898c60b640fd4981d6a25f1c11790935a44ce38c54e985f828", size = 160014, upload-time = "2025-10-14T04:41:47.631Z" },
+    { url = "https://files.pythonhosted.org/packages/76/be/4d3ee471e8145d12795ab655ece37baed0929462a86e72372fd25859047c/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:99ae2cffebb06e6c22bdc25801d7b30f503cc87dbd283479e7b606f70aff57ec", size = 154044, upload-time = "2025-10-14T04:41:48.81Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/6f/8f7af07237c34a1defe7defc565a9bc1807762f672c0fde711a4b22bf9c0/charset_normalizer-3.4.4-cp314-cp314-win32.whl", hash = "sha256:f9d332f8c2a2fcbffe1378594431458ddbef721c1769d78e2cbc06280d8155f9", size = 99940, upload-time = "2025-10-14T04:41:49.946Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/51/8ade005e5ca5b0d80fb4aff72a3775b325bdc3d27408c8113811a7cbe640/charset_normalizer-3.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:8a6562c3700cce886c5be75ade4a5db4214fda19fede41d9792d100288d8f94c", size = 107104, upload-time = "2025-10-14T04:41:51.051Z" },
+    { url = "https://files.pythonhosted.org/packages/da/5f/6b8f83a55bb8278772c5ae54a577f3099025f9ade59d0136ac24a0df4bde/charset_normalizer-3.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:de00632ca48df9daf77a2c65a484531649261ec9f25489917f09e455cb09ddb2", size = 100743, upload-time = "2025-10-14T04:41:52.122Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/4c/925909008ed5a988ccbb72dcc897407e5d6d3bd72410d69e051fc0c14647/charset_normalizer-3.4.4-py3-none-any.whl", hash = "sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f", size = 53402, upload-time = "2025-10-14T04:42:31.76Z" },
 ]
 
 [[package]]
 name = "click"
-version = "8.1.7"
+version = "8.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "colorama", marker = "platform_system == 'Windows'" },
+    { 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" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/96/d3/f04c7bfcf5c1862a2a5b845c6b2b360488cf47af55dfa79c98f6a6bf98b5/click-8.1.7.tar.gz", hash = "sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de", size = 336121 }
+
+[[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/00/2e/d53fa4befbf2cfa713304affc7ca780ce4fc1fd8710527771b58311a3229/click-8.1.7-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28", size = 97941 },
+    { 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 }
+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.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/24/56/95b7e30fa389756cb56630faa728da46a27b8c6eb46f9d557c68fff12b65/coverage-7.13.4.tar.gz", hash = "sha256:e5c8f6ed1e61a8b2dcdf31eb0b9bbf0130750ca79c1c49eb898e2ad86f5ccc91", size = 827239, upload-time = "2026-02-09T12:59:03.86Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/44/d4/7827d9ffa34d5d4d752eec907022aa417120936282fc488306f5da08c292/coverage-7.13.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0fc31c787a84f8cd6027eba44010517020e0d18487064cd3d8968941856d1415", size = 219152, upload-time = "2026-02-09T12:56:11.974Z" },
+    { url = "https://files.pythonhosted.org/packages/35/b0/d69df26607c64043292644dbb9dc54b0856fabaa2cbb1eeee3331cc9e280/coverage-7.13.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:a32ebc02a1805adf637fc8dec324b5cdacd2e493515424f70ee33799573d661b", size = 219667, upload-time = "2026-02-09T12:56:13.33Z" },
+    { url = "https://files.pythonhosted.org/packages/82/a4/c1523f7c9e47b2271dbf8c2a097e7a1f89ef0d66f5840bb59b7e8814157b/coverage-7.13.4-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e24f9156097ff9dc286f2f913df3a7f63c0e333dcafa3c196f2c18b4175ca09a", size = 246425, upload-time = "2026-02-09T12:56:14.552Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/02/aa7ec01d1a5023c4b680ab7257f9bfde9defe8fdddfe40be096ac19e8177/coverage-7.13.4-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8041b6c5bfdc03257666e9881d33b1abc88daccaf73f7b6340fb7946655cd10f", size = 248229, upload-time = "2026-02-09T12:56:16.31Z" },
+    { url = "https://files.pythonhosted.org/packages/35/98/85aba0aed5126d896162087ef3f0e789a225697245256fc6181b95f47207/coverage-7.13.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2a09cfa6a5862bc2fc6ca7c3def5b2926194a56b8ab78ffcf617d28911123012", size = 250106, upload-time = "2026-02-09T12:56:18.024Z" },
+    { url = "https://files.pythonhosted.org/packages/96/72/1db59bd67494bc162e3e4cd5fbc7edba2c7026b22f7c8ef1496d58c2b94c/coverage-7.13.4-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:296f8b0af861d3970c2a4d8c91d48eb4dd4771bcef9baedec6a9b515d7de3def", size = 252021, upload-time = "2026-02-09T12:56:19.272Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/97/72899c59c7066961de6e3daa142d459d47d104956db43e057e034f015c8a/coverage-7.13.4-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e101609bcbbfb04605ea1027b10dc3735c094d12d40826a60f897b98b1c30256", size = 247114, upload-time = "2026-02-09T12:56:21.051Z" },
+    { url = "https://files.pythonhosted.org/packages/39/1f/f1885573b5970235e908da4389176936c8933e86cb316b9620aab1585fa2/coverage-7.13.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:aa3feb8db2e87ff5e6d00d7e1480ae241876286691265657b500886c98f38bda", size = 248143, upload-time = "2026-02-09T12:56:22.585Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/cf/e80390c5b7480b722fa3e994f8202807799b85bc562aa4f1dde209fbb7be/coverage-7.13.4-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:4fc7fa81bbaf5a02801b65346c8b3e657f1d93763e58c0abdf7c992addd81a92", size = 246152, upload-time = "2026-02-09T12:56:23.748Z" },
+    { url = "https://files.pythonhosted.org/packages/44/bf/f89a8350d85572f95412debb0fb9bb4795b1d5b5232bd652923c759e787b/coverage-7.13.4-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:33901f604424145c6e9c2398684b92e176c0b12df77d52db81c20abd48c3794c", size = 249959, upload-time = "2026-02-09T12:56:25.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/6e/612a02aece8178c818df273e8d1642190c4875402ca2ba74514394b27aba/coverage-7.13.4-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:bb28c0f2cf2782508a40cec377935829d5fcc3ad9a3681375af4e84eb34b6b58", size = 246416, upload-time = "2026-02-09T12:56:26.475Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/98/b5afc39af67c2fa6786b03c3a7091fc300947387ce8914b096db8a73d67a/coverage-7.13.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:9d107aff57a83222ddbd8d9ee705ede2af2cc926608b57abed8ef96b50b7e8f9", size = 247025, upload-time = "2026-02-09T12:56:27.727Z" },
+    { url = "https://files.pythonhosted.org/packages/51/30/2bba8ef0682d5bd210c38fe497e12a06c9f8d663f7025e9f5c2c31ce847d/coverage-7.13.4-cp310-cp310-win32.whl", hash = "sha256:a6f94a7d00eb18f1b6d403c91a88fd58cfc92d4b16080dfdb774afc8294469bf", size = 221758, upload-time = "2026-02-09T12:56:29.051Z" },
+    { url = "https://files.pythonhosted.org/packages/78/13/331f94934cf6c092b8ea59ff868eb587bc8fe0893f02c55bc6c0183a192e/coverage-7.13.4-cp310-cp310-win_amd64.whl", hash = "sha256:2cb0f1e000ebc419632bbe04366a8990b6e32c4e0b51543a6484ffe15eaeda95", size = 222693, upload-time = "2026-02-09T12:56:30.366Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/ad/b59e5b451cf7172b8d1043dc0fa718f23aab379bc1521ee13d4bd9bfa960/coverage-7.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:d490ba50c3f35dd7c17953c68f3270e7ccd1c6642e2d2afe2d8e720b98f5a053", size = 219278, upload-time = "2026-02-09T12:56:31.673Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/17/0cb7ca3de72e5f4ef2ec2fa0089beafbcaaaead1844e8b8a63d35173d77d/coverage-7.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:19bc3c88078789f8ef36acb014d7241961dbf883fd2533d18cb1e7a5b4e28b11", size = 219783, upload-time = "2026-02-09T12:56:33.104Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/63/325d8e5b11e0eaf6d0f6a44fad444ae58820929a9b0de943fa377fe73e85/coverage-7.13.4-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3998e5a32e62fdf410c0dbd3115df86297995d6e3429af80b8798aad894ca7aa", size = 250200, upload-time = "2026-02-09T12:56:34.474Z" },
+    { url = "https://files.pythonhosted.org/packages/76/53/c16972708cbb79f2942922571a687c52bd109a7bd51175aeb7558dff2236/coverage-7.13.4-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8e264226ec98e01a8e1054314af91ee6cde0eacac4f465cc93b03dbe0bce2fd7", size = 252114, upload-time = "2026-02-09T12:56:35.749Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/c2/7ab36d8b8cc412bec9ea2d07c83c48930eb4ba649634ba00cb7e4e0f9017/coverage-7.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a3aa4e7b9e416774b21797365b358a6e827ffadaaca81b69ee02946852449f00", size = 254220, upload-time = "2026-02-09T12:56:37.796Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/4d/cf52c9a3322c89a0e6febdfbc83bb45c0ed3c64ad14081b9503adee702e7/coverage-7.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:71ca20079dd8f27fcf808817e281e90220475cd75115162218d0e27549f95fef", size = 256164, upload-time = "2026-02-09T12:56:39.016Z" },
+    { url = "https://files.pythonhosted.org/packages/78/e9/eb1dd17bd6de8289df3580e967e78294f352a5df8a57ff4671ee5fc3dcd0/coverage-7.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e2f25215f1a359ab17320b47bcdaca3e6e6356652e8256f2441e4ef972052903", size = 250325, upload-time = "2026-02-09T12:56:40.668Z" },
+    { url = "https://files.pythonhosted.org/packages/71/07/8c1542aa873728f72267c07278c5cc0ec91356daf974df21335ccdb46368/coverage-7.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d65b2d373032411e86960604dc4edac91fdfb5dca539461cf2cbe78327d1e64f", size = 251913, upload-time = "2026-02-09T12:56:41.97Z" },
+    { url = "https://files.pythonhosted.org/packages/74/d7/c62e2c5e4483a748e27868e4c32ad3daa9bdddbba58e1bc7a15e252baa74/coverage-7.13.4-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94eb63f9b363180aff17de3e7c8760c3ba94664ea2695c52f10111244d16a299", size = 249974, upload-time = "2026-02-09T12:56:43.323Z" },
+    { url = "https://files.pythonhosted.org/packages/98/9f/4c5c015a6e98ced54efd0f5cf8d31b88e5504ecb6857585fc0161bb1e600/coverage-7.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e856bf6616714c3a9fbc270ab54103f4e685ba236fa98c054e8f87f266c93505", size = 253741, upload-time = "2026-02-09T12:56:45.155Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/59/0f4eef89b9f0fcd9633b5d350016f54126ab49426a70ff4c4e87446cabdc/coverage-7.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:65dfcbe305c3dfe658492df2d85259e0d79ead4177f9ae724b6fb245198f55d6", size = 249695, upload-time = "2026-02-09T12:56:46.636Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/2c/b7476f938deb07166f3eb281a385c262675d688ff4659ad56c6c6b8e2e70/coverage-7.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b507778ae8a4c915436ed5c2e05b4a6cecfa70f734e19c22a005152a11c7b6a9", size = 250599, upload-time = "2026-02-09T12:56:48.13Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/34/c3420709d9846ee3785b9f2831b4d94f276f38884032dca1457fa83f7476/coverage-7.13.4-cp311-cp311-win32.whl", hash = "sha256:784fc3cf8be001197b652d51d3fd259b1e2262888693a4636e18879f613a62a9", size = 221780, upload-time = "2026-02-09T12:56:50.479Z" },
+    { url = "https://files.pythonhosted.org/packages/61/08/3d9c8613079d2b11c185b865de9a4c1a68850cfda2b357fae365cf609f29/coverage-7.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:2421d591f8ca05b308cf0092807308b2facbefe54af7c02ac22548b88b95c98f", size = 222715, upload-time = "2026-02-09T12:56:51.815Z" },
+    { url = "https://files.pythonhosted.org/packages/18/1a/54c3c80b2f056164cc0a6cdcb040733760c7c4be9d780fe655f356f433e4/coverage-7.13.4-cp311-cp311-win_arm64.whl", hash = "sha256:79e73a76b854d9c6088fe5d8b2ebe745f8681c55f7397c3c0a016192d681045f", size = 221385, upload-time = "2026-02-09T12:56:53.194Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/81/4ce2fdd909c5a0ed1f6dedb88aa57ab79b6d1fbd9b588c1ac7ef45659566/coverage-7.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:02231499b08dabbe2b96612993e5fc34217cdae907a51b906ac7fca8027a4459", size = 219449, upload-time = "2026-02-09T12:56:54.889Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/96/5238b1efc5922ddbdc9b0db9243152c09777804fb7c02ad1741eb18a11c0/coverage-7.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40aa8808140e55dc022b15d8aa7f651b6b3d68b365ea0398f1441e0b04d859c3", size = 219810, upload-time = "2026-02-09T12:56:56.33Z" },
+    { url = "https://files.pythonhosted.org/packages/78/72/2f372b726d433c9c35e56377cf1d513b4c16fe51841060d826b95caacec1/coverage-7.13.4-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:5b856a8ccf749480024ff3bd7310adaef57bf31fd17e1bfc404b7940b6986634", size = 251308, upload-time = "2026-02-09T12:56:57.858Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/a0/2ea570925524ef4e00bb6c82649f5682a77fac5ab910a65c9284de422600/coverage-7.13.4-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2c048ea43875fbf8b45d476ad79f179809c590ec7b79e2035c662e7afa3192e3", size = 254052, upload-time = "2026-02-09T12:56:59.754Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/ac/45dc2e19a1939098d783c846e130b8f862fbb50d09e0af663988f2f21973/coverage-7.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b7b38448866e83176e28086674fe7368ab8590e4610fb662b44e345b86d63ffa", size = 255165, upload-time = "2026-02-09T12:57:01.287Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/4d/26d236ff35abc3b5e63540d3386e4c3b192168c1d96da5cb2f43c640970f/coverage-7.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:de6defc1c9badbf8b9e67ae90fd00519186d6ab64e5cc5f3d21359c2a9b2c1d3", size = 257432, upload-time = "2026-02-09T12:57:02.637Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/55/14a966c757d1348b2e19caf699415a2a4c4f7feaa4bbc6326a51f5c7dd1b/coverage-7.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7eda778067ad7ffccd23ecffce537dface96212576a07924cbf0d8799d2ded5a", size = 251716, upload-time = "2026-02-09T12:57:04.056Z" },
+    { url = "https://files.pythonhosted.org/packages/77/33/50116647905837c66d28b2af1321b845d5f5d19be9655cb84d4a0ea806b4/coverage-7.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e87f6c587c3f34356c3759f0420693e35e7eb0e2e41e4c011cb6ec6ecbbf1db7", size = 253089, upload-time = "2026-02-09T12:57:05.503Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/b4/8efb11a46e3665d92635a56e4f2d4529de6d33f2cb38afd47d779d15fc99/coverage-7.13.4-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8248977c2e33aecb2ced42fef99f2d319e9904a36e55a8a68b69207fb7e43edc", size = 251232, upload-time = "2026-02-09T12:57:06.879Z" },
+    { url = "https://files.pythonhosted.org/packages/51/24/8cd73dd399b812cc76bb0ac260e671c4163093441847ffe058ac9fda1e32/coverage-7.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:25381386e80ae727608e662474db537d4df1ecd42379b5ba33c84633a2b36d47", size = 255299, upload-time = "2026-02-09T12:57:08.245Z" },
+    { url = "https://files.pythonhosted.org/packages/03/94/0a4b12f1d0e029ce1ccc1c800944a9984cbe7d678e470bb6d3c6bc38a0da/coverage-7.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:ee756f00726693e5ba94d6df2bdfd64d4852d23b09bb0bc700e3b30e6f333985", size = 250796, upload-time = "2026-02-09T12:57:10.142Z" },
+    { url = "https://files.pythonhosted.org/packages/73/44/6002fbf88f6698ca034360ce474c406be6d5a985b3fdb3401128031eef6b/coverage-7.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fdfc1e28e7c7cdce44985b3043bc13bbd9c747520f94a4d7164af8260b3d91f0", size = 252673, upload-time = "2026-02-09T12:57:12.197Z" },
+    { url = "https://files.pythonhosted.org/packages/de/c6/a0279f7c00e786be75a749a5674e6fa267bcbd8209cd10c9a450c655dfa7/coverage-7.13.4-cp312-cp312-win32.whl", hash = "sha256:01d4cbc3c283a17fc1e42d614a119f7f438eabb593391283adca8dc86eff1246", size = 221990, upload-time = "2026-02-09T12:57:14.085Z" },
+    { url = "https://files.pythonhosted.org/packages/77/4e/c0a25a425fcf5557d9abd18419c95b63922e897bc86c1f327f155ef234a9/coverage-7.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:9401ebc7ef522f01d01d45532c68c5ac40fb27113019b6b7d8b208f6e9baa126", size = 222800, upload-time = "2026-02-09T12:57:15.944Z" },
+    { url = "https://files.pythonhosted.org/packages/47/ac/92da44ad9a6f4e3a7debd178949d6f3769bedca33830ce9b1dcdab589a37/coverage-7.13.4-cp312-cp312-win_arm64.whl", hash = "sha256:b1ec7b6b6e93255f952e27ab58fbc68dcc468844b16ecbee881aeb29b6ab4d8d", size = 221415, upload-time = "2026-02-09T12:57:17.497Z" },
+    { url = "https://files.pythonhosted.org/packages/db/23/aad45061a31677d68e47499197a131eea55da4875d16c1f42021ab963503/coverage-7.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b66a2da594b6068b48b2692f043f35d4d3693fb639d5ea8b39533c2ad9ac3ab9", size = 219474, upload-time = "2026-02-09T12:57:19.332Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/70/9b8b67a0945f3dfec1fd896c5cefb7c19d5a3a6d74630b99a895170999ae/coverage-7.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:3599eb3992d814d23b35c536c28df1a882caa950f8f507cef23d1cbf334995ac", size = 219844, upload-time = "2026-02-09T12:57:20.66Z" },
+    { url = "https://files.pythonhosted.org/packages/97/fd/7e859f8fab324cef6c4ad7cff156ca7c489fef9179d5749b0c8d321281c2/coverage-7.13.4-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:93550784d9281e374fb5a12bf1324cc8a963fd63b2d2f223503ef0fd4aa339ea", size = 250832, upload-time = "2026-02-09T12:57:22.007Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/dc/b2442d10020c2f52617828862d8b6ee337859cd8f3a1f13d607dddda9cf7/coverage-7.13.4-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b720ce6a88a2755f7c697c23268ddc47a571b88052e6b155224347389fdf6a3b", size = 253434, upload-time = "2026-02-09T12:57:23.339Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/88/6728a7ad17428b18d836540630487231f5470fb82454871149502f5e5aa2/coverage-7.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7b322db1284a2ed3aa28ffd8ebe3db91c929b7a333c0820abec3d838ef5b3525", size = 254676, upload-time = "2026-02-09T12:57:24.774Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/bc/21244b1b8cedf0dff0a2b53b208015fe798d5f2a8d5348dbfece04224fff/coverage-7.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f4594c67d8a7c89cf922d9df0438c7c7bb022ad506eddb0fdb2863359ff78242", size = 256807, upload-time = "2026-02-09T12:57:26.125Z" },
+    { url = "https://files.pythonhosted.org/packages/97/a0/ddba7ed3251cff51006737a727d84e05b61517d1784a9988a846ba508877/coverage-7.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:53d133df809c743eb8bce33b24bcababb371f4441340578cd406e084d94a6148", size = 251058, upload-time = "2026-02-09T12:57:27.614Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/55/e289addf7ff54d3a540526f33751951bf0878f3809b47f6dfb3def69c6f7/coverage-7.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:76451d1978b95ba6507a039090ba076105c87cc76fc3efd5d35d72093964d49a", size = 252805, upload-time = "2026-02-09T12:57:29.066Z" },
+    { url = "https://files.pythonhosted.org/packages/13/4e/cc276b1fa4a59be56d96f1dabddbdc30f4ba22e3b1cd42504c37b3313255/coverage-7.13.4-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:7f57b33491e281e962021de110b451ab8a24182589be17e12a22c79047935e23", size = 250766, upload-time = "2026-02-09T12:57:30.522Z" },
+    { url = "https://files.pythonhosted.org/packages/94/44/1093b8f93018f8b41a8cf29636c9292502f05e4a113d4d107d14a3acd044/coverage-7.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:1731dc33dc276dafc410a885cbf5992f1ff171393e48a21453b78727d090de80", size = 254923, upload-time = "2026-02-09T12:57:31.946Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/55/ea2796da2d42257f37dbea1aab239ba9263b31bd91d5527cdd6db5efe174/coverage-7.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:bd60d4fe2f6fa7dff9223ca1bbc9f05d2b6697bc5961072e5d3b952d46e1b1ea", size = 250591, upload-time = "2026-02-09T12:57:33.842Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fa/7c4bb72aacf8af5020675aa633e59c1fbe296d22aed191b6a5b711eb2bc7/coverage-7.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9181a3ccead280b828fae232df12b16652702b49d41e99d657f46cc7b1f6ec7a", size = 252364, upload-time = "2026-02-09T12:57:35.743Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/38/a8d2ec0146479c20bbaa7181b5b455a0c41101eed57f10dd19a78ab44c80/coverage-7.13.4-cp313-cp313-win32.whl", hash = "sha256:f53d492307962561ac7de4cd1de3e363589b000ab69617c6156a16ba7237998d", size = 222010, upload-time = "2026-02-09T12:57:37.25Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/0c/dbfafbe90a185943dcfbc766fe0e1909f658811492d79b741523a414a6cc/coverage-7.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:e6f70dec1cc557e52df5306d051ef56003f74d56e9c4dd7ddb07e07ef32a84dd", size = 222818, upload-time = "2026-02-09T12:57:38.734Z" },
+    { url = "https://files.pythonhosted.org/packages/04/d1/934918a138c932c90d78301f45f677fb05c39a3112b96fd2c8e60503cdc7/coverage-7.13.4-cp313-cp313-win_arm64.whl", hash = "sha256:fb07dc5da7e849e2ad31a5d74e9bece81f30ecf5a42909d0a695f8bd1874d6af", size = 221438, upload-time = "2026-02-09T12:57:40.223Z" },
+    { url = "https://files.pythonhosted.org/packages/52/57/ee93ced533bcb3e6df961c0c6e42da2fc6addae53fb95b94a89b1e33ebd7/coverage-7.13.4-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:40d74da8e6c4b9ac18b15331c4b5ebc35a17069410cad462ad4f40dcd2d50c0d", size = 220165, upload-time = "2026-02-09T12:57:41.639Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/e0/969fc285a6fbdda49d91af278488d904dcd7651b2693872f0ff94e40e84a/coverage-7.13.4-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4223b4230a376138939a9173f1bdd6521994f2aff8047fae100d6d94d50c5a12", size = 220516, upload-time = "2026-02-09T12:57:44.215Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/b8/9531944e16267e2735a30a9641ff49671f07e8138ecf1ca13db9fd2560c7/coverage-7.13.4-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1d4be36a5114c499f9f1f9195e95ebf979460dbe2d88e6816ea202010ba1c34b", size = 261804, upload-time = "2026-02-09T12:57:45.989Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f3/e63df6d500314a2a60390d1989240d5f27318a7a68fa30ad3806e2a9323e/coverage-7.13.4-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:200dea7d1e8095cc6e98cdabe3fd1d21ab17d3cee6dab00cadbb2fe35d9c15b9", size = 263885, upload-time = "2026-02-09T12:57:47.42Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/67/7654810de580e14b37670b60a09c599fa348e48312db5b216d730857ffe6/coverage-7.13.4-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b8eb931ee8e6d8243e253e5ed7336deea6904369d2fd8ae6e43f68abbf167092", size = 266308, upload-time = "2026-02-09T12:57:49.345Z" },
+    { url = "https://files.pythonhosted.org/packages/37/6f/39d41eca0eab3cc82115953ad41c4e77935286c930e8fad15eaed1389d83/coverage-7.13.4-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:75eab1ebe4f2f64d9509b984f9314d4aa788540368218b858dad56dc8f3e5eb9", size = 267452, upload-time = "2026-02-09T12:57:50.811Z" },
+    { url = "https://files.pythonhosted.org/packages/50/6d/39c0fbb8fc5cd4d2090811e553c2108cf5112e882f82505ee7495349a6bf/coverage-7.13.4-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c35eb28c1d085eb7d8c9b3296567a1bebe03ce72962e932431b9a61f28facf26", size = 261057, upload-time = "2026-02-09T12:57:52.447Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/a2/60010c669df5fa603bb5a97fb75407e191a846510da70ac657eb696b7fce/coverage-7.13.4-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:eb88b316ec33760714a4720feb2816a3a59180fd58c1985012054fa7aebee4c2", size = 263875, upload-time = "2026-02-09T12:57:53.938Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/d9/63b22a6bdbd17f1f96e9ed58604c2a6b0e72a9133e37d663bef185877cf6/coverage-7.13.4-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:7d41eead3cc673cbd38a4417deb7fd0b4ca26954ff7dc6078e33f6ff97bed940", size = 261500, upload-time = "2026-02-09T12:57:56.012Z" },
+    { url = "https://files.pythonhosted.org/packages/70/bf/69f86ba1ad85bc3ad240e4c0e57a2e620fbc0e1645a47b5c62f0e941ad7f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:fb26a934946a6afe0e326aebe0730cdff393a8bc0bbb65a2f41e30feddca399c", size = 265212, upload-time = "2026-02-09T12:57:57.5Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/f2/5f65a278a8c2148731831574c73e42f57204243d33bedaaf18fa79c5958f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:dae88bc0fc77edaa65c14be099bd57ee140cf507e6bfdeea7938457ab387efb0", size = 260398, upload-time = "2026-02-09T12:57:59.027Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/80/6e8280a350ee9fea92f14b8357448a242dcaa243cb2c72ab0ca591f66c8c/coverage-7.13.4-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:845f352911777a8e722bfce168958214951e07e47e5d5d9744109fa5fe77f79b", size = 262584, upload-time = "2026-02-09T12:58:01.129Z" },
+    { url = "https://files.pythonhosted.org/packages/22/63/01ff182fc95f260b539590fb12c11ad3e21332c15f9799cb5e2386f71d9f/coverage-7.13.4-cp313-cp313t-win32.whl", hash = "sha256:2fa8d5f8de70688a28240de9e139fa16b153cc3cbb01c5f16d88d6505ebdadf9", size = 222688, upload-time = "2026-02-09T12:58:02.736Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/43/89de4ef5d3cd53b886afa114065f7e9d3707bdb3e5efae13535b46ae483d/coverage-7.13.4-cp313-cp313t-win_amd64.whl", hash = "sha256:9351229c8c8407645840edcc277f4a2d44814d1bc34a2128c11c2a031d45a5dd", size = 223746, upload-time = "2026-02-09T12:58:05.362Z" },
+    { url = "https://files.pythonhosted.org/packages/35/39/7cf0aa9a10d470a5309b38b289b9bb07ddeac5d61af9b664fe9775a4cb3e/coverage-7.13.4-cp313-cp313t-win_arm64.whl", hash = "sha256:30b8d0512f2dc8c8747557e8fb459d6176a2c9e5731e2b74d311c03b78451997", size = 222003, upload-time = "2026-02-09T12:58:06.952Z" },
+    { url = "https://files.pythonhosted.org/packages/92/11/a9cf762bb83386467737d32187756a42094927150c3e107df4cb078e8590/coverage-7.13.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:300deaee342f90696ed186e3a00c71b5b3d27bffe9e827677954f4ee56969601", size = 219522, upload-time = "2026-02-09T12:58:08.623Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/28/56e6d892b7b052236d67c95f1936b6a7cf7c3e2634bf27610b8cbd7f9c60/coverage-7.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:29e3220258d682b6226a9b0925bc563ed9a1ebcff3cad30f043eceea7eaf2689", size = 219855, upload-time = "2026-02-09T12:58:10.176Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/69/233459ee9eb0c0d10fcc2fe425a029b3fa5ce0f040c966ebce851d030c70/coverage-7.13.4-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:391ee8f19bef69210978363ca930f7328081c6a0152f1166c91f0b5fdd2a773c", size = 250887, upload-time = "2026-02-09T12:58:12.503Z" },
+    { url = "https://files.pythonhosted.org/packages/06/90/2cdab0974b9b5bbc1623f7876b73603aecac11b8d95b85b5b86b32de5eab/coverage-7.13.4-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0dd7ab8278f0d58a0128ba2fca25824321f05d059c1441800e934ff2efa52129", size = 253396, upload-time = "2026-02-09T12:58:14.615Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/15/ea4da0f85bf7d7b27635039e649e99deb8173fe551096ea15017f7053537/coverage-7.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78cdf0d578b15148b009ccf18c686aa4f719d887e76e6b40c38ffb61d264a552", size = 254745, upload-time = "2026-02-09T12:58:16.162Z" },
+    { url = "https://files.pythonhosted.org/packages/99/11/bb356e86920c655ca4d61daee4e2bbc7258f0a37de0be32d233b561134ff/coverage-7.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:48685fee12c2eb3b27c62f2658e7ea21e9c3239cba5a8a242801a0a3f6a8c62a", size = 257055, upload-time = "2026-02-09T12:58:17.892Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/0f/9ae1f8cb17029e09da06ca4e28c9e1d5c1c0a511c7074592e37e0836c915/coverage-7.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4e83efc079eb39480e6346a15a1bcb3e9b04759c5202d157e1dd4303cd619356", size = 250911, upload-time = "2026-02-09T12:58:19.495Z" },
+    { url = "https://files.pythonhosted.org/packages/89/3a/adfb68558fa815cbc29747b553bc833d2150228f251b127f1ce97e48547c/coverage-7.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ecae9737b72408d6a950f7e525f30aca12d4bd8dd95e37342e5beb3a2a8c4f71", size = 252754, upload-time = "2026-02-09T12:58:21.064Z" },
+    { url = "https://files.pythonhosted.org/packages/32/b1/540d0c27c4e748bd3cd0bd001076ee416eda993c2bae47a73b7cc9357931/coverage-7.13.4-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ae4578f8528569d3cf303fef2ea569c7f4c4059a38c8667ccef15c6e1f118aa5", size = 250720, upload-time = "2026-02-09T12:58:22.622Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/95/383609462b3ffb1fe133014a7c84fc0dd01ed55ac6140fa1093b5af7ebb1/coverage-7.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:6fdef321fdfbb30a197efa02d48fcd9981f0d8ad2ae8903ac318adc653f5df98", size = 254994, upload-time = "2026-02-09T12:58:24.548Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/ba/1761138e86c81680bfc3c49579d66312865457f9fe405b033184e5793cb3/coverage-7.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b0f6ccf3dbe577170bebfce1318707d0e8c3650003cb4b3a9dd744575daa8b5", size = 250531, upload-time = "2026-02-09T12:58:26.271Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/8e/05900df797a9c11837ab59c4d6fe94094e029582aab75c3309a93e6fb4e3/coverage-7.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:75fcd519f2a5765db3f0e391eb3b7d150cce1a771bf4c9f861aeab86c767a3c0", size = 252189, upload-time = "2026-02-09T12:58:27.807Z" },
+    { url = "https://files.pythonhosted.org/packages/00/bd/29c9f2db9ea4ed2738b8a9508c35626eb205d51af4ab7bf56a21a2e49926/coverage-7.13.4-cp314-cp314-win32.whl", hash = "sha256:8e798c266c378da2bd819b0677df41ab46d78065fb2a399558f3f6cae78b2fbb", size = 222258, upload-time = "2026-02-09T12:58:29.441Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/4d/1f8e723f6829977410efeb88f73673d794075091c8c7c18848d273dc9d73/coverage-7.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:245e37f664d89861cf2329c9afa2c1fe9e6d4e1a09d872c947e70718aeeac505", size = 223073, upload-time = "2026-02-09T12:58:31.026Z" },
+    { url = "https://files.pythonhosted.org/packages/51/5b/84100025be913b44e082ea32abcf1afbf4e872f5120b7a1cab1d331b1e13/coverage-7.13.4-cp314-cp314-win_arm64.whl", hash = "sha256:ad27098a189e5838900ce4c2a99f2fe42a0bf0c2093c17c69b45a71579e8d4a2", size = 221638, upload-time = "2026-02-09T12:58:32.599Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/e4/c884a405d6ead1370433dad1e3720216b4f9fd8ef5b64bfd984a2a60a11a/coverage-7.13.4-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:85480adfb35ffc32d40918aad81b89c69c9cc5661a9b8a81476d3e645321a056", size = 220246, upload-time = "2026-02-09T12:58:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/81/5c/4d7ed8b23b233b0fffbc9dfec53c232be2e695468523242ea9fd30f97ad2/coverage-7.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:79be69cf7f3bf9b0deeeb062eab7ac7f36cd4cc4c4dd694bd28921ba4d8596cc", size = 220514, upload-time = "2026-02-09T12:58:35.704Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/6f/3284d4203fd2f28edd73034968398cd2d4cb04ab192abc8cff007ea35679/coverage-7.13.4-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:caa421e2684e382c5d8973ac55e4f36bed6821a9bad5c953494de960c74595c9", size = 261877, upload-time = "2026-02-09T12:58:37.864Z" },
+    { url = "https://files.pythonhosted.org/packages/09/aa/b672a647bbe1556a85337dc95bfd40d146e9965ead9cc2fe81bde1e5cbce/coverage-7.13.4-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:14375934243ee05f56c45393fe2ce81fe5cc503c07cee2bdf1725fb8bef3ffaf", size = 264004, upload-time = "2026-02-09T12:58:39.492Z" },
+    { url = "https://files.pythonhosted.org/packages/79/a1/aa384dbe9181f98bba87dd23dda436f0c6cf2e148aecbb4e50fc51c1a656/coverage-7.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:25a41c3104d08edb094d9db0d905ca54d0cd41c928bb6be3c4c799a54753af55", size = 266408, upload-time = "2026-02-09T12:58:41.852Z" },
+    { url = "https://files.pythonhosted.org/packages/53/5e/5150bf17b4019bc600799f376bb9606941e55bd5a775dc1e096b6ffea952/coverage-7.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f01afcff62bf9a08fb32b2c1d6e924236c0383c02c790732b6537269e466a72", size = 267544, upload-time = "2026-02-09T12:58:44.093Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/ed/f1de5c675987a4a7a672250d2c5c9d73d289dbf13410f00ed7181d8017dd/coverage-7.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:eb9078108fbf0bcdde37c3f4779303673c2fa1fe8f7956e68d447d0dd426d38a", size = 260980, upload-time = "2026-02-09T12:58:45.721Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/e3/fe758d01850aa172419a6743fe76ba8b92c29d181d4f676ffe2dae2ba631/coverage-7.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:0e086334e8537ddd17e5f16a344777c1ab8194986ec533711cbe6c41cde841b6", size = 263871, upload-time = "2026-02-09T12:58:47.334Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/76/b829869d464115e22499541def9796b25312b8cf235d3bb00b39f1675395/coverage-7.13.4-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:725d985c5ab621268b2edb8e50dfe57633dc69bda071abc470fed55a14935fd3", size = 261472, upload-time = "2026-02-09T12:58:48.995Z" },
+    { url = "https://files.pythonhosted.org/packages/14/9e/caedb1679e73e2f6ad240173f55218488bfe043e38da577c4ec977489915/coverage-7.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:3c06f0f1337c667b971ca2f975523347e63ec5e500b9aa5882d91931cd3ef750", size = 265210, upload-time = "2026-02-09T12:58:51.178Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/10/0dd02cb009b16ede425b49ec344aba13a6ae1dc39600840ea6abcb085ac4/coverage-7.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:590c0ed4bf8e85f745e6b805b2e1c457b2e33d5255dd9729743165253bc9ad39", size = 260319, upload-time = "2026-02-09T12:58:53.081Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8e/234d2c927af27c6d7a5ffad5bd2cf31634c46a477b4c7adfbfa66baf7ebb/coverage-7.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:eb30bf180de3f632cd043322dad5751390e5385108b2807368997d1a92a509d0", size = 262638, upload-time = "2026-02-09T12:58:55.258Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/64/e5547c8ff6964e5965c35a480855911b61509cce544f4d442caa759a0702/coverage-7.13.4-cp314-cp314t-win32.whl", hash = "sha256:c4240e7eded42d131a2d2c4dec70374b781b043ddc79a9de4d55ca71f8e98aea", size = 223040, upload-time = "2026-02-09T12:58:56.936Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/96/38086d58a181aac86d503dfa9c47eb20715a79c3e3acbdf786e92e5c09a8/coverage-7.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:4c7d3cc01e7350f2f0f6f7036caaf5673fb56b6998889ccfe9e1c1fe75a9c932", size = 224148, upload-time = "2026-02-09T12:58:58.645Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/72/8d10abd3740a0beb98c305e0c3faf454366221c0f37a8bcf8f60020bb65a/coverage-7.13.4-cp314-cp314t-win_arm64.whl", hash = "sha256:23e3f687cf945070d1c90f85db66d11e3025665d8dafa831301a0e0038f3db9b", size = 222172, upload-time = "2026-02-09T12:59:00.396Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/4a/331fe2caf6799d591109bb9c08083080f6de90a823695d412a935622abb2/coverage-7.13.4-py3-none-any.whl", hash = "sha256:1af1641e57cf7ba1bd67d677c9abdbcd6cc2ab7da3bca7fa1e2b7e50e65f2ad0", size = 211242, upload-time = "2026-02-09T12:59:02.032Z" },
+]
+
+[package.optional-dependencies]
+toml = [
+    { name = "tomli", marker = "python_full_version <= '3.11'" },
+]
+
+[[package]]
+name = "croniter"
+version = "6.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "python-dateutil" },
+    { name = "pytz" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ad/2f/44d1ae153a0e27be56be43465e5cb39b9650c781e001e7864389deb25090/croniter-6.0.0.tar.gz", hash = "sha256:37c504b313956114a983ece2c2b07790b1f1094fe9d81cc94739214748255577", size = 64481, upload-time = "2024-12-17T17:17:47.32Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335 },
+    { url = "https://files.pythonhosted.org/packages/07/4b/290b4c3efd6417a8b0c284896de19b1d5855e6dbdb97d2a35e68fa42de85/croniter-6.0.0-py2.py3-none-any.whl", hash = "sha256:2f878c3856f17896979b2a4379ba1f09c83e374931ea15cc835c5dd2eee9b368", size = 25468, upload-time = "2024-12-17T17:17:45.359Z" },
 ]
 
 [[package]]
-name = "copychat"
-version = "0.5.2"
+name = "cryptography"
+version = "46.0.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "gitpython" },
-    { name = "pathspec" },
-    { name = "pyperclip" },
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/60/04/ee2a9e8542e4fa2773b81771ff8349ff19cdd56b7258a0cc442639052edb/cryptography-46.0.5.tar.gz", hash = "sha256:abace499247268e3757271b2f1e244b36b06f8515cf27c4d49468fc9eb16e93d", size = 750064, upload-time = "2026-02-10T19:18:38.255Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/81/b0bb27f2ba931a65409c6b8a8b358a7f03c0e46eceacddff55f7c84b1f3b/cryptography-46.0.5-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:351695ada9ea9618b3500b490ad54c739860883df6c1f555e088eaf25b1bbaad", size = 7176289, upload-time = "2026-02-10T19:17:08.274Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/9e/6b4397a3e3d15123de3b1806ef342522393d50736c13b20ec4c9ea6693a6/cryptography-46.0.5-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c18ff11e86df2e28854939acde2d003f7984f721eba450b56a200ad90eeb0e6b", size = 4275637, upload-time = "2026-02-10T19:17:10.53Z" },
+    { url = "https://files.pythonhosted.org/packages/63/e7/471ab61099a3920b0c77852ea3f0ea611c9702f651600397ac567848b897/cryptography-46.0.5-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:4d7e3d356b8cd4ea5aff04f129d5f66ebdc7b6f8eae802b93739ed520c47c79b", size = 4424742, upload-time = "2026-02-10T19:17:12.388Z" },
+    { url = "https://files.pythonhosted.org/packages/37/53/a18500f270342d66bf7e4d9f091114e31e5ee9e7375a5aba2e85a91e0044/cryptography-46.0.5-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:50bfb6925eff619c9c023b967d5b77a54e04256c4281b0e21336a130cd7fc263", size = 4277528, upload-time = "2026-02-10T19:17:13.853Z" },
+    { url = "https://files.pythonhosted.org/packages/22/29/c2e812ebc38c57b40e7c583895e73c8c5adb4d1e4a0cc4c5a4fdab2b1acc/cryptography-46.0.5-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:803812e111e75d1aa73690d2facc295eaefd4439be1023fefc4995eaea2af90d", size = 4947993, upload-time = "2026-02-10T19:17:15.618Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/e7/237155ae19a9023de7e30ec64e5d99a9431a567407ac21170a046d22a5a3/cryptography-46.0.5-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ee190460e2fbe447175cda91b88b84ae8322a104fc27766ad09428754a618ed", size = 4456855, upload-time = "2026-02-10T19:17:17.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/87/fc628a7ad85b81206738abbd213b07702bcbdada1dd43f72236ef3cffbb5/cryptography-46.0.5-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:f145bba11b878005c496e93e257c1e88f154d278d2638e6450d17e0f31e558d2", size = 3984635, upload-time = "2026-02-10T19:17:18.792Z" },
+    { url = "https://files.pythonhosted.org/packages/84/29/65b55622bde135aedf4565dc509d99b560ee4095e56989e815f8fd2aa910/cryptography-46.0.5-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e9251e3be159d1020c4030bd2e5f84d6a43fe54b6c19c12f51cde9542a2817b2", size = 4277038, upload-time = "2026-02-10T19:17:20.256Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/36/45e76c68d7311432741faf1fbf7fac8a196a0a735ca21f504c75d37e2558/cryptography-46.0.5-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:47fb8a66058b80e509c47118ef8a75d14c455e81ac369050f20ba0d23e77fee0", size = 4912181, upload-time = "2026-02-10T19:17:21.825Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/1a/c1ba8fead184d6e3d5afcf03d569acac5ad063f3ac9fb7258af158f7e378/cryptography-46.0.5-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4c3341037c136030cb46e4b1e17b7418ea4cbd9dd207e4a6f3b2b24e0d4ac731", size = 4456482, upload-time = "2026-02-10T19:17:25.133Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/e5/3fb22e37f66827ced3b902cf895e6a6bc1d095b5b26be26bd13c441fdf19/cryptography-46.0.5-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:890bcb4abd5a2d3f852196437129eb3667d62630333aacc13dfd470fad3aaa82", size = 4405497, upload-time = "2026-02-10T19:17:26.66Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/df/9d58bb32b1121a8a2f27383fabae4d63080c7ca60b9b5c88be742be04ee7/cryptography-46.0.5-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80a8d7bfdf38f87ca30a5391c0c9ce4ed2926918e017c29ddf643d0ed2778ea1", size = 4667819, upload-time = "2026-02-10T19:17:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/ed/325d2a490c5e94038cdb0117da9397ece1f11201f425c4e9c57fe5b9f08b/cryptography-46.0.5-cp311-abi3-win32.whl", hash = "sha256:60ee7e19e95104d4c03871d7d7dfb3d22ef8a9b9c6778c94e1c8fcc8365afd48", size = 3028230, upload-time = "2026-02-10T19:17:30.518Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/5a/ac0f49e48063ab4255d9e3b79f5def51697fce1a95ea1370f03dc9db76f6/cryptography-46.0.5-cp311-abi3-win_amd64.whl", hash = "sha256:38946c54b16c885c72c4f59846be9743d699eee2b69b6988e0a00a01f46a61a4", size = 3480909, upload-time = "2026-02-10T19:17:32.083Z" },
+    { url = "https://files.pythonhosted.org/packages/00/13/3d278bfa7a15a96b9dc22db5a12ad1e48a9eb3d40e1827ef66a5df75d0d0/cryptography-46.0.5-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:94a76daa32eb78d61339aff7952ea819b1734b46f73646a07decb40e5b3448e2", size = 7119287, upload-time = "2026-02-10T19:17:33.801Z" },
+    { url = "https://files.pythonhosted.org/packages/67/c8/581a6702e14f0898a0848105cbefd20c058099e2c2d22ef4e476dfec75d7/cryptography-46.0.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5be7bf2fb40769e05739dd0046e7b26f9d4670badc7b032d6ce4db64dddc0678", size = 4265728, upload-time = "2026-02-10T19:17:35.569Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/4a/ba1a65ce8fc65435e5a849558379896c957870dd64fecea97b1ad5f46a37/cryptography-46.0.5-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fe346b143ff9685e40192a4960938545c699054ba11d4f9029f94751e3f71d87", size = 4408287, upload-time = "2026-02-10T19:17:36.938Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/67/8ffdbf7b65ed1ac224d1c2df3943553766914a8ca718747ee3871da6107e/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:c69fd885df7d089548a42d5ec05be26050ebcd2283d89b3d30676eb32ff87dee", size = 4270291, upload-time = "2026-02-10T19:17:38.748Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/e5/f52377ee93bc2f2bba55a41a886fd208c15276ffbd2569f2ddc89d50e2c5/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:8293f3dea7fc929ef7240796ba231413afa7b68ce38fd21da2995549f5961981", size = 4927539, upload-time = "2026-02-10T19:17:40.241Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/02/cfe39181b02419bbbbcf3abdd16c1c5c8541f03ca8bda240debc467d5a12/cryptography-46.0.5-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:1abfdb89b41c3be0365328a410baa9df3ff8a9110fb75e7b52e66803ddabc9a9", size = 4442199, upload-time = "2026-02-10T19:17:41.789Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/96/2fcaeb4873e536cf71421a388a6c11b5bc846e986b2b069c79363dc1648e/cryptography-46.0.5-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:d66e421495fdb797610a08f43b05269e0a5ea7f5e652a89bfd5a7d3c1dee3648", size = 3960131, upload-time = "2026-02-10T19:17:43.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/d2/b27631f401ddd644e94c5cf33c9a4069f72011821cf3dc7309546b0642a0/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:4e817a8920bfbcff8940ecfd60f23d01836408242b30f1a708d93198393a80b4", size = 4270072, upload-time = "2026-02-10T19:17:45.481Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/a7/60d32b0370dae0b4ebe55ffa10e8599a2a59935b5ece1b9f06edb73abdeb/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:68f68d13f2e1cb95163fa3b4db4bf9a159a418f5f6e7242564fc75fcae667fd0", size = 4892170, upload-time = "2026-02-10T19:17:46.997Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b9/cf73ddf8ef1164330eb0b199a589103c363afa0cf794218c24d524a58eab/cryptography-46.0.5-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:a3d1fae9863299076f05cb8a778c467578262fae09f9dc0ee9b12eb4268ce663", size = 4441741, upload-time = "2026-02-10T19:17:48.661Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/eb/eee00b28c84c726fe8fa0158c65afe312d9c3b78d9d01daf700f1f6e37ff/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c4143987a42a2397f2fc3b4d7e3a7d313fbe684f67ff443999e803dd75a76826", size = 4396728, upload-time = "2026-02-10T19:17:50.058Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f4/6bc1a9ed5aef7145045114b75b77c2a8261b4d38717bd8dea111a63c3442/cryptography-46.0.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:7d731d4b107030987fd61a7f8ab512b25b53cef8f233a97379ede116f30eb67d", size = 4652001, upload-time = "2026-02-10T19:17:51.54Z" },
+    { url = "https://files.pythonhosted.org/packages/86/ef/5d00ef966ddd71ac2e6951d278884a84a40ffbd88948ef0e294b214ae9e4/cryptography-46.0.5-cp314-cp314t-win32.whl", hash = "sha256:c3bcce8521d785d510b2aad26ae2c966092b7daa8f45dd8f44734a104dc0bc1a", size = 3003637, upload-time = "2026-02-10T19:17:52.997Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/57/f3f4160123da6d098db78350fdfd9705057aad21de7388eacb2401dceab9/cryptography-46.0.5-cp314-cp314t-win_amd64.whl", hash = "sha256:4d8ae8659ab18c65ced284993c2265910f6c9e650189d4e3f68445ef82a810e4", size = 3469487, upload-time = "2026-02-10T19:17:54.549Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/fa/a66aa722105ad6a458bebd64086ca2b72cdd361fed31763d20390f6f1389/cryptography-46.0.5-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:4108d4c09fbbf2789d0c926eb4152ae1760d5a2d97612b92d508d96c861e4d31", size = 7170514, upload-time = "2026-02-10T19:17:56.267Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/04/c85bdeab78c8bc77b701bf0d9bdcf514c044e18a46dcff330df5448631b0/cryptography-46.0.5-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7d1f30a86d2757199cb2d56e48cce14deddf1f9c95f1ef1b64ee91ea43fe2e18", size = 4275349, upload-time = "2026-02-10T19:17:58.419Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/32/9b87132a2f91ee7f5223b091dc963055503e9b442c98fc0b8a5ca765fab0/cryptography-46.0.5-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:039917b0dc418bb9f6edce8a906572d69e74bd330b0b3fea4f79dab7f8ddd235", size = 4420667, upload-time = "2026-02-10T19:18:00.619Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/a6/a7cb7010bec4b7c5692ca6f024150371b295ee1c108bdc1c400e4c44562b/cryptography-46.0.5-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:ba2a27ff02f48193fc4daeadf8ad2590516fa3d0adeeb34336b96f7fa64c1e3a", size = 4276980, upload-time = "2026-02-10T19:18:02.379Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/7c/c4f45e0eeff9b91e3f12dbd0e165fcf2a38847288fcfd889deea99fb7b6d/cryptography-46.0.5-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:61aa400dce22cb001a98014f647dc21cda08f7915ceb95df0c9eaf84b4b6af76", size = 4939143, upload-time = "2026-02-10T19:18:03.964Z" },
+    { url = "https://files.pythonhosted.org/packages/37/19/e1b8f964a834eddb44fa1b9a9976f4e414cbb7aa62809b6760c8803d22d1/cryptography-46.0.5-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:3ce58ba46e1bc2aac4f7d9290223cead56743fa6ab94a5d53292ffaac6a91614", size = 4453674, upload-time = "2026-02-10T19:18:05.588Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ed/db15d3956f65264ca204625597c410d420e26530c4e2943e05a0d2f24d51/cryptography-46.0.5-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:420d0e909050490d04359e7fdb5ed7e667ca5c3c402b809ae2563d7e66a92229", size = 3978801, upload-time = "2026-02-10T19:18:07.167Z" },
+    { url = "https://files.pythonhosted.org/packages/41/e2/df40a31d82df0a70a0daf69791f91dbb70e47644c58581d654879b382d11/cryptography-46.0.5-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:582f5fcd2afa31622f317f80426a027f30dc792e9c80ffee87b993200ea115f1", size = 4276755, upload-time = "2026-02-10T19:18:09.813Z" },
+    { url = "https://files.pythonhosted.org/packages/33/45/726809d1176959f4a896b86907b98ff4391a8aa29c0aaaf9450a8a10630e/cryptography-46.0.5-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:bfd56bb4b37ed4f330b82402f6f435845a5f5648edf1ad497da51a8452d5d62d", size = 4901539, upload-time = "2026-02-10T19:18:11.263Z" },
+    { url = "https://files.pythonhosted.org/packages/99/0f/a3076874e9c88ecb2ecc31382f6e7c21b428ede6f55aafa1aa272613e3cd/cryptography-46.0.5-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:a3d507bb6a513ca96ba84443226af944b0f7f47dcc9a399d110cd6146481d24c", size = 4452794, upload-time = "2026-02-10T19:18:12.914Z" },
+    { url = "https://files.pythonhosted.org/packages/02/ef/ffeb542d3683d24194a38f66ca17c0a4b8bf10631feef44a7ef64e631b1a/cryptography-46.0.5-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9f16fbdf4da055efb21c22d81b89f155f02ba420558db21288b3d0035bafd5f4", size = 4404160, upload-time = "2026-02-10T19:18:14.375Z" },
+    { url = "https://files.pythonhosted.org/packages/96/93/682d2b43c1d5f1406ed048f377c0fc9fc8f7b0447a478d5c65ab3d3a66eb/cryptography-46.0.5-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ced80795227d70549a411a4ab66e8ce307899fad2220ce5ab2f296e687eacde9", size = 4667123, upload-time = "2026-02-10T19:18:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/45/2d/9c5f2926cb5300a8eefc3f4f0b3f3df39db7f7ce40c8365444c49363cbda/cryptography-46.0.5-cp38-abi3-win32.whl", hash = "sha256:02f547fce831f5096c9a567fd41bc12ca8f11df260959ecc7c3202555cc47a72", size = 3010220, upload-time = "2026-02-10T19:18:17.361Z" },
+    { url = "https://files.pythonhosted.org/packages/48/ef/0c2f4a8e31018a986949d34a01115dd057bf536905dca38897bacd21fac3/cryptography-46.0.5-cp38-abi3-win_amd64.whl", hash = "sha256:556e106ee01aa13484ce9b0239bca667be5004efb0aabbed28d353df86445595", size = 3467050, upload-time = "2026-02-10T19:18:18.899Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/dd/2d9fdb07cebdf3d51179730afb7d5e576153c6744c3ff8fded23030c204e/cryptography-46.0.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:3b4995dc971c9fb83c25aa44cf45f02ba86f71ee600d81091c2f0cbae116b06c", size = 3476964, upload-time = "2026-02-10T19:18:20.687Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/6f/6cc6cc9955caa6eaf83660b0da2b077c7fe8ff9950a3c5e45d605038d439/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:bc84e875994c3b445871ea7181d424588171efec3e185dced958dad9e001950a", size = 4218321, upload-time = "2026-02-10T19:18:22.349Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/5d/c4da701939eeee699566a6c1367427ab91a8b7088cc2328c09dbee940415/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:2ae6971afd6246710480e3f15824ed3029a60fc16991db250034efd0b9fb4356", size = 4381786, upload-time = "2026-02-10T19:18:24.529Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/97/a538654732974a94ff96c1db621fa464f455c02d4bb7d2652f4edc21d600/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:d861ee9e76ace6cf36a6a89b959ec08e7bc2493ee39d07ffe5acb23ef46d27da", size = 4217990, upload-time = "2026-02-10T19:18:25.957Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/11/7e500d2dd3ba891197b9efd2da5454b74336d64a7cc419aa7327ab74e5f6/cryptography-46.0.5-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:2b7a67c9cd56372f3249b39699f2ad479f6991e62ea15800973b956f4b73e257", size = 4381252, upload-time = "2026-02-10T19:18:27.496Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/58/6b3d24e6b9bc474a2dcdee65dfd1f008867015408a271562e4b690561a4d/cryptography-46.0.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:8456928655f856c6e1533ff59d5be76578a7157224dbd9ce6872f25055ab9ab7", size = 3407605, upload-time = "2026-02-10T19:18:29.233Z" },
+]
+
+[[package]]
+name = "cyclopts"
+version = "4.5.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "docstring-parser" },
     { name = "rich" },
-    { name = "tiktoken" },
-    { name = "typer" },
+    { 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/b4/fb/6001a67d1c072bc1082ee18f5ed67dc4338d78c3053b37f337bfd03b17d0/copychat-0.5.2.tar.gz", hash = "sha256:a341c629e8b5179678970173b65955fd8dcd7a29c2ecbb72ebd748a838730e23", size = 53018 }
+sdist = { url = "https://files.pythonhosted.org/packages/a5/16/06e35c217334930ff7c476ce1c8e74ed786fa3ef6742e59a1458e2412290/cyclopts-4.5.3.tar.gz", hash = "sha256:35fa70971204c450d9668646a6ca372eb5fa3070fbe8dd51c5b4b31e65198f2d", size = 162437, upload-time = "2026-02-16T15:07:11.96Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/00/8a/5fba1f777bd49954636cc715bcd2e1a546e35b2a73eaea01741afc96831f/copychat-0.5.2-py3-none-any.whl", hash = "sha256:1368e5d79e4912b29e91c20e4d47de3c375c5c974fa313ee46d2c62cf68895b0", size = 15412 },
+    { url = "https://files.pythonhosted.org/packages/3a/1f/d8bce383a90d8a6a11033327777afa4d4d611ec11869284adb6f48152906/cyclopts-4.5.3-py3-none-any.whl", hash = "sha256:50af3085bb15d4a6f2582dd383dad5e4ba6a0d4d4c64ee63326d881a752a6919", size = 200231, upload-time = "2026-02-16T15:07:13.045Z" },
 ]
 
 [[package]]
 name = "decorator"
-version = "5.1.1"
+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/66/0c/8d907af351aa16b42caae42f9d6aa37b900c67308052d10fdce809f8d952/decorator-5.1.1.tar.gz", hash = "sha256:637996211036b6385ef91435e4fae22989472f9d571faba8927ba8253acbc330", size = 35016 }
+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/d5/50/83c593b07763e1161326b3b8c6686f0f4b0f24d5526546bee538c89837d6/decorator-5.1.1-py3-none-any.whl", hash = "sha256:b8c3f85900b9dc423225913c5aace94729fe1fa9763b38939a95226f02d37186", size = 9073 },
+    { 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.2.2"
+version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/09/35/2495c4ac46b980e4ca1f6ad6db102322ef3ad2410b79fdde159a4b0f3b92/exceptiongroup-1.2.2.tar.gz", hash = "sha256:47c2edf7c6738fafb49fd34290706d1a1a2f4d1c6df275526b62cbb4aa5393cc", size = 28883 }
+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/02/cc/b7e31358aac6ed1ef2bb790a9746ac2c69bcb3c8588b41616914eb106eaf/exceptiongroup-1.2.2-py3-none-any.whl", hash = "sha256:3111b9d131c238bec2f8f516e123e14ba243563fb135d3fe885990585aa7795b", size = 16453 },
+    { 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.1"
+version = "2.1.2"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/bb/ff/b4c0dc78fbe20c3e59c0c7334de0c27eb4001a2b2017999af398bf730817/execnet-2.1.1.tar.gz", hash = "sha256:5189b52c6121c24feae288166ab41b32549c7e2348652736540b9e6e7d4e72e3", size = 166524 }
+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/43/09/2aea36ff60d16dd8879bdb2f5b3ee0ba8d08cbbdcdfe870e695ce3784385/execnet-2.1.1-py3-none-any.whl", hash = "sha256:26dee51f1b80cebd6d0ca8e74dd8745419761d3bef34163928cbebbdc4749fdc", size = 40612 },
+    { 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.1.0"
+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 = "fakeredis"
+version = "2.34.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/8c/e3/7d45f492c2c4a0e8e0fad57d081a7c8a0286cdd86372b070cca1ec0caa1e/executing-2.1.0.tar.gz", hash = "sha256:8ea27ddd260da8150fa5a708269c4a10e76161e2496ec3e587da9e3c0fe4b9ab", size = 977485 }
+dependencies = [
+    { name = "redis" },
+    { name = "sortedcontainers" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d8/44/c403963727d707e03f49a417712b0a23e853d33ae50729679040b6cfe281/fakeredis-2.34.0.tar.gz", hash = "sha256:72bc51a7ab39bedf5004f0cf1b5206822619c1be8c2657fd878d1f4250256c57", size = 177156, upload-time = "2026-02-16T15:56:34.318Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b5/fd/afcd0496feca3276f509df3dbd5dae726fcc756f1a08d9e25abe1733f962/executing-2.1.0-py2.py3-none-any.whl", hash = "sha256:8d63781349375b5ebccc3142f4b30350c0cd9c79f921cde38be2be4637e98eaf", size = 25805 },
+    { url = "https://files.pythonhosted.org/packages/1a/8e/af19c00753c432355f9b76cec3ab0842578de43ba575e82735b18c1b3ec9/fakeredis-2.34.0-py3-none-any.whl", hash = "sha256:bc45d362c6cc3a537f8287372d8ea532538dfbe7f5d635d0905d7b3464ec51d2", size = 122063, upload-time = "2026-02-16T15:56:21.227Z" },
+]
+
+[package.optional-dependencies]
+lua = [
+    { name = "lupa" },
 ]
 
 [[package]]
 name = "fancycompleter"
-version = "0.9.1"
+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.129.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "pyreadline", marker = "platform_system == 'Windows'" },
-    { name = "pyrepl" },
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a9/95/649d135442d8ecf8af5c7e235550c628056423c96c4bc6787348bdae9248/fancycompleter-0.9.1.tar.gz", hash = "sha256:09e0feb8ae242abdfd7ef2ba55069a46f011814a80fe5476be48f51b00247272", size = 10866 }
+sdist = { url = "https://files.pythonhosted.org/packages/48/47/75f6bea02e797abff1bca968d5997793898032d9923c1935ae2efdece642/fastapi-0.129.0.tar.gz", hash = "sha256:61315cebd2e65df5f97ec298c888f9de30430dd0612d59d6480beafbc10655af", size = 375450, upload-time = "2026-02-12T13:54:52.541Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/38/ef/c08926112034d017633f693d3afc8343393a035134a29dfc12dcd71b0375/fancycompleter-0.9.1-py3-none-any.whl", hash = "sha256:dd076bca7d9d524cc7f25ec8f35ef95388ffef9ef46def4d3d25e9b044ad7080", size = 9681 },
+    { url = "https://files.pythonhosted.org/packages/9e/dd/d0ee25348ac58245ee9f90b6f3cbb666bf01f69be7e0911f9851bddbda16/fastapi-0.129.0-py3-none-any.whl", hash = "sha256:b4946880e48f462692b31c083be0432275cbfb6e2274566b1be91479cc1a84ec", size = 102950, upload-time = "2026-02-12T13:54:54.528Z" },
 ]
 
 [[package]]
 name = "fastmcp"
-version = "0.2.1.dev8+gfc560b3.d20241130"
 source = { editable = "." }
 dependencies = [
+    { name = "authlib" },
+    { name = "cyclopts" },
+    { name = "exceptiongroup" },
     { name = "httpx" },
+    { name = "jsonref" },
+    { name = "jsonschema-path" },
     { name = "mcp" },
-    { name = "pydantic" },
-    { name = "pydantic-settings" },
-    { name = "typer" },
+    { 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" },
+]
+
+[package.optional-dependencies]
+anthropic = [
+    { name = "anthropic" },
+]
+apps = [
+    { name = "prefab-ui" },
+]
+azure = [
+    { name = "azure-identity" },
+]
+code-mode = [
+    { name = "pydantic-monty" },
+]
+gemini = [
+    { name = "google-genai" },
+]
+openai = [
+    { name = "openai" },
+]
+tasks = [
+    { name = "pydocket" },
 ]
 
 [package.dev-dependencies]
 dev = [
-    { name = "copychat" },
-    { name = "ipython" },
+    { name = "dirty-equals" },
+    { name = "fastapi" },
+    { name = "fastmcp", extra = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"] },
+    { name = "inline-snapshot", extra = ["dirty-equals"] },
+    { name = "ipython", version = "8.38.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "ipython", version = "9.10.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+    { 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-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 = "httpx", specifier = ">=0.26.0" },
-    { name = "mcp", specifier = ">=1.0.0" },
-    { name = "pydantic", specifier = ">=2.5.3" },
-    { name = "pydantic-settings", specifier = ">=2.6.1" },
-    { name = "typer", specifier = ">=0.9.0" },
-]
+    { name = "anthropic", marker = "extra == 'anthropic'", specifier = ">=0.40.0" },
+    { name = "authlib", specifier = ">=1.6.5" },
+    { name = "azure-identity", marker = "extra == 'azure'", specifier = ">=1.16.0" },
+    { name = "cyclopts", specifier = ">=4.0.0" },
+    { name = "exceptiongroup", specifier = ">=1.2.2" },
+    { name = "google-genai", marker = "extra == 'gemini'", specifier = ">=1.18.0" },
+    { name = "httpx", specifier = ">=0.28.1,<1.0" },
+    { name = "jsonref", specifier = ">=1.1.0" },
+    { name = "jsonschema-path", specifier = ">=0.3.4" },
+    { name = "mcp", specifier = ">=1.24.0,<2.0" },
+    { name = "openai", marker = "extra == 'openai'", specifier = ">=1.102.0" },
+    { name = "openapi-pydantic", specifier = ">=0.5.1" },
+    { name = "opentelemetry-api", specifier = ">=1.20.0" },
+    { name = "packaging", specifier = ">=24.0" },
+    { name = "platformdirs", specifier = ">=4.0.0" },
+    { name = "prefab-ui", marker = "extra == 'apps'", specifier = ">=0.6.0" },
+    { name = "py-key-value-aio", extras = ["filetree", "keyring", "memory"], specifier = ">=0.4.4,<0.5.0" },
+    { name = "pydantic", extras = ["email"], specifier = ">=2.11.7" },
+    { name = "pydantic-monty", marker = "extra == 'code-mode'", specifier = ">=0.0.7" },
+    { name = "pydocket", marker = "extra == 'tasks'", specifier = ">=0.18.0" },
+    { name = "pyperclip", specifier = ">=1.9.0" },
+    { name = "python-dotenv", specifier = ">=1.1.0" },
+    { name = "pyyaml", specifier = ">=6.0,<7.0" },
+    { name = "rich", specifier = ">=13.9.4" },
+    { name = "uncalled-for", specifier = ">=0.2.0" },
+    { name = "uvicorn", specifier = ">=0.35" },
+    { name = "watchfiles", specifier = ">=1.0.0" },
+    { name = "websockets", specifier = ">=15.0.1" },
+]
+provides-extras = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"]
 
 [package.metadata.requires-dev]
 dev = [
-    { name = "copychat", specifier = ">=0.5.2" },
+    { name = "dirty-equals", specifier = ">=0.9.0" },
+    { name = "fastapi", specifier = ">=0.115.12" },
+    { name = "fastmcp", extras = ["anthropic", "apps", "azure", "code-mode", "gemini", "openai", "tasks"] },
+    { name = "inline-snapshot", extras = ["dirty-equals"], specifier = ">=0.27.2" },
     { name = "ipython", specifier = ">=8.12.3" },
-    { name = "pdbpp", specifier = ">=0.10.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 = ">=0.23.5" },
+    { name = "pytest-asyncio", specifier = ">=1.2.0" },
+    { name = "pytest-cov", specifier = ">=6.1.1" },
+    { name = "pytest-env", specifier = ">=1.1.5" },
+    { 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.20" },
+]
+
+[[package]]
+name = "google-auth"
+version = "2.48.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "pyasn1-modules" },
+    { name = "rsa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0c/41/242044323fbd746615884b1c16639749e73665b718209946ebad7ba8a813/google_auth-2.48.0.tar.gz", hash = "sha256:4f7e706b0cd3208a3d940a19a822c37a476ddba5450156c3e6624a71f7c841ce", size = 326522, upload-time = "2026-01-26T19:22:47.157Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/83/1d/d6466de3a5249d35e832a52834115ca9d1d0de6abc22065f049707516d47/google_auth-2.48.0-py3-none-any.whl", hash = "sha256:2e2a537873d449434252a9632c28bfc268b0adb1e53f9fb62afc5333a975903f", size = 236499, upload-time = "2026-01-26T19:22:45.099Z" },
+]
+
+[package.optional-dependencies]
+requests = [
+    { name = "requests" },
+]
+
+[[package]]
+name = "google-genai"
+version = "1.65.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/79/f9/cc1191c2540d6a4e24609a586c4ed45d2db57cfef47931c139ee70e5874a/google_genai-1.65.0.tar.gz", hash = "sha256:d470eb600af802d58a79c7f13342d9ea0d05d965007cae8f76c7adff3d7a4750", size = 497206, upload-time = "2026-02-26T00:20:33.824Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/3c/3fea4e7c91357c71782d7dcaad7a2577d636c90317e003386893c25bc62c/google_genai-1.65.0-py3-none-any.whl", hash = "sha256:68c025205856919bc03edb0155c11b4b833810b7ce17ad4b7a9eeba5158f6c44", size = 724429, upload-time = "2026-02-26T00:20:32.186Z" },
+]
+
+[[package]]
+name = "googleapis-common-protos"
+version = "1.72.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e5/7b/adfd75544c415c487b33061fe7ae526165241c1ea133f9a9125a56b39fd8/googleapis_common_protos-1.72.0.tar.gz", hash = "sha256:e55a601c1b32b52d7a3e65f43563e2aa61bcd737998ee672ac9b951cd49319f5", size = 147433, upload-time = "2025-11-06T18:29:24.087Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/ab/09169d5a4612a5f92490806649ac8d41e3ec9129c636754575b3553f4ea4/googleapis_common_protos-1.72.0-py3-none-any.whl", hash = "sha256:4299c5a82d5ae1a9702ada957347726b167f9f8d1fc352477702a1e851ff4038", size = 297515, upload-time = "2025-11-06T18:29:13.14Z" },
+]
+
+[[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.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+]
+
+[[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.0"
+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/41/74/19294067d5b5b78144eab2aacec85b998c2d2ea6b3d24eefd9a90255d7aa/inline_snapshot-0.32.0.tar.gz", hash = "sha256:57fa3df325284d0d14def5dab9ac5da89e383f085bea9a7be51fdeab65e59ced", size = 2623331, upload-time = "2026-02-13T19:51:54.469Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/97/25/0e84a6322e5fdb1bf67870b2269151449f4894987b26c78718918dd64ea6/inline_snapshot-0.32.0-py3-none-any.whl", hash = "sha256:b522ae2c891f666e80213c5f9677ec6fd4a2a7d334ab9d6ce745675bec6a40f0", size = 84087, upload-time = "2026-02-13T19:51:52.604Z" },
+]
+
+[package.optional-dependencies]
+dirty-equals = [
+    { name = "dirty-equals" },
+]
+
+[[package]]
+name = "ipython"
+version = "8.38.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/e5/61/1810830e8b93c72dcd3c0f150c80a00c3deb229562d9423807ec92c3a539/ipython-8.38.0.tar.gz", hash = "sha256:9cfea8c903ce0867cc2f23199ed8545eb741f3a69420bfcf3743ad1cec856d39", size = 5513996, upload-time = "2026-01-05T10:59:06.901Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/df/db59624f4c71b39717c423409950ac3f2c8b2ce4b0aac843112c7fb3f721/ipython-8.38.0-py3-none-any.whl", hash = "sha256:750162629d800ac65bb3b543a14e7a74b0e88063eac9b92124d4b2aa3f6d8e86", size = 831813, upload-time = "2026-01-05T10:59:04.239Z" },
+]
+
+[[package]]
+name = "ipython"
+version = "9.10.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.13'",
+    "python_full_version >= '3.11' and python_full_version < '3.13'",
+]
+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/a6/60/2111715ea11f39b1535bed6024b7dec7918b71e5e5d30855a5b503056b50/ipython-9.10.0.tar.gz", hash = "sha256:cd9e656be97618a0676d058134cd44e6dc7012c0e5cb36a9ce96a8c904adaf77", size = 4426526, upload-time = "2026-02-02T10:00:33.594Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3d/aa/898dec789a05731cd5a9f50605b7b44a72bd198fd0d4528e11fc610177cc/ipython-9.10.0-py3-none-any.whl", hash = "sha256:c6ab68cc23bba8c7e18e9b932797014cc61ea7fd6f19de180ab9ba73e65ee58d", size = 622774, upload-time = "2026-02-02T10:00:31.503Z" },
+]
+
+[[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.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "backports-tarfile", marker = "python_full_version < '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cb/9c/a788f5bb29c61e456b8ee52ce76dbdd32fd72cd73dd67bc95f42c7a8d13c/jaraco_context-6.1.0.tar.gz", hash = "sha256:129a341b0a85a7db7879e22acd66902fda67882db771754574338898b2d5d86f", size = 15850, upload-time = "2026-01-13T02:53:53.847Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8d/48/aa685dbf1024c7bd82bede569e3a85f82c32fd3d79ba5fea578f0159571a/jaraco_context-6.1.0-py3-none-any.whl", hash = "sha256:a43b5ed85815223d0d3cfdb6d7ca0d2bc8946f28f30b6f3216bda070f68badda", size = 7065, upload-time = "2026-01-13T02:53:53.031Z" },
+]
+
+[[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 = "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.3.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6e/45/41ebc679c2a4fced6a722f624c18d658dee42612b83ea24c1caf7c0eb3a8/jsonschema_path-0.3.4.tar.gz", hash = "sha256:8365356039f16cc65fddffafda5f58766e34bebab7d6d105616ab52bc4297001", size = 11159, upload-time = "2025-01-24T14:33:16.547Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/58/3485da8cb93d2f393bce453adeef16896751f14ba3e2024bc21dc9597646/jsonschema_path-0.3.4-py3-none-any.whl", hash = "sha256:f502191fdc2b22050f9a81c9237be9d27145b9001c55842bece5e94e382e52f8", size = 14810, upload-time = "2025-01-24T14:33:14.652Z" },
+]
+
+[[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.0a7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/9f/27aacd5b1566ebbec1531ead263fa1f60899b8a7cd6aa1a710c34b05a5b8/loq-0.1.0a7.tar.gz", hash = "sha256:576f70f45d466accf6a4c1020e430f0fc008047eeae1889952bd981f9da12bf0", size = 63997, upload-time = "2026-01-22T04:42:14.476Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fc/e5/b55110b86951b184019bfe7290ee73115b932b3bb0d4428bbe20c68d2f31/loq-0.1.0a7-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:47d40a9792397f8f100e7c2984d56227bd05c7f3d6817e8e26a7af88cbff0b26", size = 1336455, upload-time = "2026-01-22T04:42:23.812Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/b9/519e83707c3819349e4497a4b30e9a814d155eb1317a25425cac73cb8045/loq-0.1.0a7-py3-none-macosx_11_0_arm64.whl", hash = "sha256:178393fa15968082aafb54c24d2015eef7090b0668ca6715e3e3c390bdeeea46", size = 1259828, upload-time = "2026-01-22T04:42:21.951Z" },
+    { url = "https://files.pythonhosted.org/packages/84/28/e9730ef5cf29baef96a015a514752d7142f48287ac7efc8bdd09794d2b28/loq-0.1.0a7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f9527526e4cffb12c84207cd2a92ccfa90968e137908b4329d9f6e07ba0cb575", size = 1278762, upload-time = "2026-01-22T04:42:12.887Z" },
+    { url = "https://files.pythonhosted.org/packages/90/48/be790e0542fa660ec84f863e0440570442e167fc5c65d8ad36bd93e5f315/loq-0.1.0a7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9ed89b64ab1de6be9936d274b95f946a1b6f052493e1a1f1db3aac70852b3e0c", size = 1374495, upload-time = "2026-01-22T04:42:16.588Z" },
+    { url = "https://files.pythonhosted.org/packages/29/8b/74e6e39ac302ff722acd2c154f5f6b3c28f750f914e859158b1333b2330e/loq-0.1.0a7-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e54a96e61c9aafebfa873e5a897132e611b457892f149809380625d4fa9c1147", size = 1318652, upload-time = "2026-01-22T04:42:19.229Z" },
+    { url = "https://files.pythonhosted.org/packages/57/b2/ae6bae30259715db7d97c7c7f929d5a210dd2a59b2564a020899fba8a7e5/loq-0.1.0a7-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:a21ab864964823678b8478fef83f42c2634662f736cf8b552de09736f52ca91f", size = 1440332, upload-time = "2026-01-22T04:42:17.897Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/48/11ed2d491b353cb7c159398a3017a64a5c424c85979a2eb805ded6763739/loq-0.1.0a7-py3-none-win_amd64.whl", hash = "sha256:a5d0f98e9613ffab868aacc1e1277ca3f7d39158c55aa3d0e534865591592da7", size = 1334210, upload-time = "2026-01-22T04:42:20.748Z" },
+]
+
+[[package]]
+name = "lupa"
+version = "2.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b8/1c/191c3e6ec6502e3dbe25a53e27f69a5daeac3e56de1f73c0138224171ead/lupa-2.6.tar.gz", hash = "sha256:9a770a6e89576be3447668d7ced312cd6fd41d3c13c2462c9dc2c2ab570e45d9", size = 7240282, upload-time = "2025-10-24T07:20:29.738Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a1/15/713cab5d0dfa4858f83b99b3e0329072df33dc14fc3ebbaa017e0f9755c4/lupa-2.6-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6b3dabda836317e63c5ad052826e156610f356a04b3003dfa0dbe66b5d54d671", size = 954828, upload-time = "2025-10-24T07:17:15.726Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/71/704740cbc6e587dd6cc8dabf2f04820ac6a671784e57cc3c29db795476db/lupa-2.6-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:8726d1c123bbe9fbb974ce29825e94121824e66003038ff4532c14cc2ed0c51c", size = 1919259, upload-time = "2025-10-24T07:17:18.586Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/18/f248341c423c5d48837e35584c6c3eb4acab7e722b6057d7b3e28e42dae8/lupa-2.6-cp310-cp310-macosx_11_0_x86_64.whl", hash = "sha256:f4e159e7d814171199b246f9235ca8961f6461ea8c1165ab428afa13c9289a94", size = 984998, upload-time = "2025-10-24T07:17:20.428Z" },
+    { url = "https://files.pythonhosted.org/packages/44/1e/8a4bd471e018aad76bcb9455d298c2c96d82eced20f2ae8fcec8cd800948/lupa-2.6-cp310-cp310-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:202160e80dbfddfb79316692a563d843b767e0f6787bbd1c455f9d54052efa6c", size = 1174871, upload-time = "2025-10-24T07:17:22.755Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/5c/3a3f23fd6a91b0986eea1ceaf82ad3f9b958fe3515a9981fb9c4eb046c8b/lupa-2.6-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5deede7c5b36ab64f869dae4831720428b67955b0bb186c8349cf6ea121c852b", size = 1057471, upload-time = "2025-10-24T07:17:24.908Z" },
+    { url = "https://files.pythonhosted.org/packages/45/ac/01be1fed778fb0c8f46ee8cbe344e4d782f6806fac12717f08af87aa4355/lupa-2.6-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:86f04901f920bbf7c0cac56807dc9597e42347123e6f1f3ca920f15f54188ce5", size = 2100592, upload-time = "2025-10-24T07:17:27.089Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/6c/1a05bb873e30830f8574e10cd0b4cdbc72e9dbad2a09e25810b5e3b1f75d/lupa-2.6-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:6deef8f851d6afb965c84849aa5b8c38856942df54597a811ce0369ced678610", size = 1081396, upload-time = "2025-10-24T07:17:29.064Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/c2/a19dd80d6dc98b39bbf8135b8198e38aa7ca3360b720eac68d1d7e9286b5/lupa-2.6-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:21f2b5549681c2a13b1170a26159d30875d367d28f0247b81ca347222c755038", size = 1192007, upload-time = "2025-10-24T07:17:31.362Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/43/e1b297225c827f55752e46fdbfb021c8982081b0f24490e42776ea69ae3b/lupa-2.6-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:66eea57630eab5e6f49fdc5d7811c0a2a41f2011be4ea56a087ea76112011eb7", size = 2196661, upload-time = "2025-10-24T07:17:33.484Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/8f/2272d429a7fa9dc8dbd6e9c5c9073a03af6007eb22a4c78829fec6a34b80/lupa-2.6-cp310-cp310-win32.whl", hash = "sha256:60a403de8cab262a4fe813085dd77010effa6e2eb1886db2181df803140533b1", size = 1412738, upload-time = "2025-10-24T07:17:35.11Z" },
+    { url = "https://files.pythonhosted.org/packages/35/2a/1708911271dd49ad87b4b373b5a4b0e0a0516d3d2af7b76355946c7ee171/lupa-2.6-cp310-cp310-win_amd64.whl", hash = "sha256:e4656a39d93dfa947cf3db56dc16c7916cb0cc8024acd3a952071263f675df64", size = 1656898, upload-time = "2025-10-24T07:17:36.949Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/29/1f66907c1ebf1881735afa695e646762c674f00738ebf66d795d59fc0665/lupa-2.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6d988c0f9331b9f2a5a55186701a25444ab10a1432a1021ee58011499ecbbdd5", size = 962875, upload-time = "2025-10-24T07:17:39.107Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/67/4a748604be360eb9c1c215f6a0da921cd1a2b44b2c5951aae6fb83019d3a/lupa-2.6-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:ebe1bbf48259382c72a6fe363dea61a0fd6fe19eab95e2ae881e20f3654587bf", size = 1935390, upload-time = "2025-10-24T07:17:41.427Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/0c/8ef9ee933a350428b7bdb8335a37ef170ab0bb008bbf9ca8f4f4310116b6/lupa-2.6-cp311-cp311-macosx_11_0_x86_64.whl", hash = "sha256:a8fcee258487cf77cdd41560046843bb38c2e18989cd19671dd1e2596f798306", size = 992193, upload-time = "2025-10-24T07:17:43.231Z" },
+    { url = "https://files.pythonhosted.org/packages/65/46/e6c7facebdb438db8a65ed247e56908818389c1a5abbf6a36aab14f1057d/lupa-2.6-cp311-cp311-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:561a8e3be800827884e767a694727ed8482d066e0d6edfcbf423b05e63b05535", size = 1165844, upload-time = "2025-10-24T07:17:45.437Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/26/9f1154c6c95f175ccbf96aa96c8f569c87f64f463b32473e839137601a8b/lupa-2.6-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:af880a62d47991cae78b8e9905c008cbfdc4a3a9723a66310c2634fc7644578c", size = 1048069, upload-time = "2025-10-24T07:17:47.181Z" },
+    { url = "https://files.pythonhosted.org/packages/68/67/2cc52ab73d6af81612b2ea24c870d3fa398443af8e2875e5befe142398b1/lupa-2.6-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:80b22923aa4023c86c0097b235615f89d469a0c4eee0489699c494d3367c4c85", size = 2079079, upload-time = "2025-10-24T07:17:49.755Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/dc/f843f09bbf325f6e5ee61730cf6c3409fc78c010d968c7c78acba3019ca7/lupa-2.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:153d2cc6b643f7efb9cfc0c6bb55ec784d5bac1a3660cfc5b958a7b8f38f4a75", size = 1071428, upload-time = "2025-10-24T07:17:51.991Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/60/37533a8d85bf004697449acb97ecdacea851acad28f2ad3803662487dd2a/lupa-2.6-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:3fa8777e16f3ded50b72967dc17e23f5a08e4f1e2c9456aff2ebdb57f5b2869f", size = 1181756, upload-time = "2025-10-24T07:17:53.752Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/f2/cf29b20dbb4927b6a3d27c339ac5d73e74306ecc28c8e2c900b2794142ba/lupa-2.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:8dbdcbe818c02a2f56f5ab5ce2de374dab03e84b25266cfbaef237829bc09b3f", size = 2175687, upload-time = "2025-10-24T07:17:56.228Z" },
+    { url = "https://files.pythonhosted.org/packages/94/7c/050e02f80c7131b63db1474bff511e63c545b5a8636a24cbef3fc4da20b6/lupa-2.6-cp311-cp311-win32.whl", hash = "sha256:defaf188fde8f7a1e5ce3a5e6d945e533b8b8d547c11e43b96c9b7fe527f56dc", size = 1412592, upload-time = "2025-10-24T07:17:59.062Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/9a/6f2af98aa5d771cea661f66c8eb8f53772ec1ab1dfbce24126cfcd189436/lupa-2.6-cp311-cp311-win_amd64.whl", hash = "sha256:9505ae600b5c14f3e17e70f87f88d333717f60411faca1ddc6f3e61dce85fa9e", size = 1669194, upload-time = "2025-10-24T07:18:01.647Z" },
+    { url = "https://files.pythonhosted.org/packages/94/86/ce243390535c39d53ea17ccf0240815e6e457e413e40428a658ea4ee4b8d/lupa-2.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:47ce718817ef1cc0c40d87c3d5ae56a800d61af00fbc0fad1ca9be12df2f3b56", size = 951707, upload-time = "2025-10-24T07:18:03.884Z" },
+    { url = "https://files.pythonhosted.org/packages/86/85/cedea5e6cbeb54396fdcc55f6b741696f3f036d23cfaf986d50d680446da/lupa-2.6-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:7aba985b15b101495aa4b07112cdc08baa0c545390d560ad5cfde2e9e34f4d58", size = 1916703, upload-time = "2025-10-24T07:18:05.6Z" },
+    { url = "https://files.pythonhosted.org/packages/24/be/3d6b5f9a8588c01a4d88129284c726017b2089f3a3fd3ba8bd977292fea0/lupa-2.6-cp312-cp312-macosx_11_0_x86_64.whl", hash = "sha256:b766f62f95b2739f2248977d29b0722e589dcf4f0ccfa827ccbd29f0148bd2e5", size = 985152, upload-time = "2025-10-24T07:18:08.561Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/23/9f9a05beee5d5dce9deca4cb07c91c40a90541fc0a8e09db4ee670da550f/lupa-2.6-cp312-cp312-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:00a934c23331f94cb51760097ebfab14b005d55a6b30a2b480e3c53dd2fa290d", size = 1159599, upload-time = "2025-10-24T07:18:10.346Z" },
+    { url = "https://files.pythonhosted.org/packages/40/4e/e7c0583083db9d7f1fd023800a9767d8e4391e8330d56c2373d890ac971b/lupa-2.6-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:21de9f38bd475303e34a042b7081aabdf50bd9bafd36ce4faea2f90fd9f15c31", size = 1038686, upload-time = "2025-10-24T07:18:12.112Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/9f/5a4f7d959d4feba5e203ff0c31889e74d1ca3153122be4a46dca7d92bf7c/lupa-2.6-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cf3bda96d3fc41237e964a69c23647d50d4e28421111360274d4799832c560e9", size = 2071956, upload-time = "2025-10-24T07:18:14.572Z" },
+    { url = "https://files.pythonhosted.org/packages/92/34/2f4f13ca65d01169b1720176aedc4af17bc19ee834598c7292db232cb6dc/lupa-2.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:5a76ead245da54801a81053794aa3975f213221f6542d14ec4b859ee2e7e0323", size = 1057199, upload-time = "2025-10-24T07:18:16.379Z" },
+    { url = "https://files.pythonhosted.org/packages/35/2a/5f7d2eebec6993b0dcd428e0184ad71afb06a45ba13e717f6501bfed1da3/lupa-2.6-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8dd0861741caa20886ddbda0a121d8e52fb9b5bb153d82fa9bba796962bf30e8", size = 1173693, upload-time = "2025-10-24T07:18:18.153Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/29/089b4d2f8e34417349af3904bb40bec40b65c8731f45e3fd8d497ca573e5/lupa-2.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:239e63948b0b23023f81d9a19a395e768ed3da6a299f84e7963b8f813f6e3f9c", size = 2164394, upload-time = "2025-10-24T07:18:20.403Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/1b/79c17b23c921f81468a111cad843b076a17ef4b684c4a8dff32a7969c3f0/lupa-2.6-cp312-cp312-win32.whl", hash = "sha256:325894e1099499e7a6f9c351147661a2011887603c71086d36fe0f964d52d1ce", size = 1420647, upload-time = "2025-10-24T07:18:23.368Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/15/5121e68aad3584e26e1425a5c9a79cd898f8a152292059e128c206ee817c/lupa-2.6-cp312-cp312-win_amd64.whl", hash = "sha256:c735a1ce8ee60edb0fe71d665f1e6b7c55c6021f1d340eb8c865952c602cd36f", size = 1688529, upload-time = "2025-10-24T07:18:25.523Z" },
+    { url = "https://files.pythonhosted.org/packages/28/1d/21176b682ca5469001199d8b95fa1737e29957a3d185186e7a8b55345f2e/lupa-2.6-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:663a6e58a0f60e7d212017d6678639ac8df0119bc13c2145029dcba084391310", size = 947232, upload-time = "2025-10-24T07:18:27.878Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/4c/d327befb684660ca13cf79cd1f1d604331808f9f1b6fb6bf57832f8edf80/lupa-2.6-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:d1f5afda5c20b1f3217a80e9bc1b77037f8a6eb11612fd3ada19065303c8f380", size = 1908625, upload-time = "2025-10-24T07:18:29.944Z" },
+    { url = "https://files.pythonhosted.org/packages/66/8e/ad22b0a19454dfd08662237a84c792d6d420d36b061f239e084f29d1a4f3/lupa-2.6-cp313-cp313-macosx_11_0_x86_64.whl", hash = "sha256:26f2b3c085fe76e9119e48c1013c1cccdc1f51585d456858290475aa38e7089e", size = 981057, upload-time = "2025-10-24T07:18:31.553Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/48/74859073ab276bd0566c719f9ca0108b0cfc1956ca0d68678d117d47d155/lupa-2.6-cp313-cp313-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:60d2f902c7b96fb8ab98493dcff315e7bb4d0b44dc9dd76eb37de575025d5685", size = 1156227, upload-time = "2025-10-24T07:18:33.981Z" },
+    { url = "https://files.pythonhosted.org/packages/09/6c/0e9ded061916877253c2266074060eb71ed99fb21d73c8c114a76725bce2/lupa-2.6-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a02d25dee3a3250967c36590128d9220ae02f2eda166a24279da0b481519cbff", size = 1035752, upload-time = "2025-10-24T07:18:36.32Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/ef/f8c32e454ef9f3fe909f6c7d57a39f950996c37a3deb7b391fec7903dab7/lupa-2.6-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6eae1ee16b886b8914ff292dbefbf2f48abfbdee94b33a88d1d5475e02423203", size = 2069009, upload-time = "2025-10-24T07:18:38.072Z" },
+    { url = "https://files.pythonhosted.org/packages/53/dc/15b80c226a5225815a890ee1c11f07968e0aba7a852df41e8ae6fe285063/lupa-2.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:b0edd5073a4ee74ab36f74fe61450148e6044f3952b8d21248581f3c5d1a58be", size = 1056301, upload-time = "2025-10-24T07:18:40.165Z" },
+    { url = "https://files.pythonhosted.org/packages/31/14/2086c1425c985acfb30997a67e90c39457122df41324d3c179d6ee2292c6/lupa-2.6-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:0c53ee9f22a8a17e7d4266ad48e86f43771951797042dd51d1494aaa4f5f3f0a", size = 1170673, upload-time = "2025-10-24T07:18:42.426Z" },
+    { url = "https://files.pythonhosted.org/packages/10/e5/b216c054cf86576c0191bf9a9f05de6f7e8e07164897d95eea0078dca9b2/lupa-2.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:de7c0f157a9064a400d828789191a96da7f4ce889969a588b87ec80de9b14772", size = 2162227, upload-time = "2025-10-24T07:18:46.112Z" },
+    { url = "https://files.pythonhosted.org/packages/59/2f/33ecb5bedf4f3bc297ceacb7f016ff951331d352f58e7e791589609ea306/lupa-2.6-cp313-cp313-win32.whl", hash = "sha256:ee9523941ae0a87b5b703417720c5d78f72d2f5bc23883a2ea80a949a3ed9e75", size = 1419558, upload-time = "2025-10-24T07:18:48.371Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/b4/55e885834c847ea610e111d87b9ed4768f0afdaeebc00cd46810f25029f6/lupa-2.6-cp313-cp313-win_amd64.whl", hash = "sha256:b1335a5835b0a25ebdbc75cf0bda195e54d133e4d994877ef025e218c2e59db9", size = 1683424, upload-time = "2025-10-24T07:18:50.976Z" },
+    { url = "https://files.pythonhosted.org/packages/66/9d/d9427394e54d22a35d1139ef12e845fd700d4872a67a34db32516170b746/lupa-2.6-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:dcb6d0a3264873e1653bc188499f48c1fb4b41a779e315eba45256cfe7bc33c1", size = 953818, upload-time = "2025-10-24T07:18:53.378Z" },
+    { url = "https://files.pythonhosted.org/packages/10/41/27bbe81953fb2f9ecfced5d9c99f85b37964cfaf6aa8453bb11283983721/lupa-2.6-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:a37e01f2128f8c36106726cb9d360bac087d58c54b4522b033cc5691c584db18", size = 1915850, upload-time = "2025-10-24T07:18:55.259Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/98/f9ff60db84a75ba8725506bbf448fb085bc77868a021998ed2a66d920568/lupa-2.6-cp314-cp314-macosx_11_0_x86_64.whl", hash = "sha256:458bd7e9ff3c150b245b0fcfbb9bd2593d1152ea7f0a7b91c1d185846da033fe", size = 982344, upload-time = "2025-10-24T07:18:57.05Z" },
+    { url = "https://files.pythonhosted.org/packages/41/f7/f39e0f1c055c3b887d86b404aaf0ca197b5edfd235a8b81b45b25bac7fc3/lupa-2.6-cp314-cp314-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:052ee82cac5206a02df77119c325339acbc09f5ce66967f66a2e12a0f3211cad", size = 1156543, upload-time = "2025-10-24T07:18:59.251Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/9c/59e6cffa0d672d662ae17bd7ac8ecd2c89c9449dee499e3eb13ca9cd10d9/lupa-2.6-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96594eca3c87dd07938009e95e591e43d554c1dbd0385be03c100367141db5a8", size = 1047974, upload-time = "2025-10-24T07:19:01.449Z" },
+    { url = "https://files.pythonhosted.org/packages/23/c6/a04e9cef7c052717fcb28fb63b3824802488f688391895b618e39be0f684/lupa-2.6-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e8faddd9d198688c8884091173a088a8e920ecc96cda2ffed576a23574c4b3f6", size = 2073458, upload-time = "2025-10-24T07:19:03.369Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/10/824173d10f38b51fc77785228f01411b6ca28826ce27404c7c912e0e442c/lupa-2.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:daebb3a6b58095c917e76ba727ab37b27477fb926957c825205fbda431552134", size = 1067683, upload-time = "2025-10-24T07:19:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/dc/9692fbcf3c924d9c4ece2d8d2f724451ac2e09af0bd2a782db1cef34e799/lupa-2.6-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:f3154e68972befe0f81564e37d8142b5d5d79931a18309226a04ec92487d4ea3", size = 1171892, upload-time = "2025-10-24T07:19:08.544Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ff/e318b628d4643c278c96ab3ddea07fc36b075a57383c837f5b11e537ba9d/lupa-2.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e4dadf77b9fedc0bfa53417cc28dc2278a26d4cbd95c29f8927ad4d8fe0a7ef9", size = 2166641, upload-time = "2025-10-24T07:19:10.485Z" },
+    { url = "https://files.pythonhosted.org/packages/12/f7/a6f9ec2806cf2d50826980cdb4b3cffc7691dc6f95e13cc728846d5cb793/lupa-2.6-cp314-cp314-win32.whl", hash = "sha256:cb34169c6fa3bab3e8ac58ca21b8a7102f6a94b6a5d08d3636312f3f02fafd8f", size = 1456857, upload-time = "2025-10-24T07:19:37.989Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/de/df71896f25bdc18360fdfa3b802cd7d57d7fede41a0e9724a4625b412c85/lupa-2.6-cp314-cp314-win_amd64.whl", hash = "sha256:b74f944fe46c421e25d0f8692aef1e842192f6f7f68034201382ac440ef9ea67", size = 1731191, upload-time = "2025-10-24T07:19:40.281Z" },
+    { url = "https://files.pythonhosted.org/packages/47/3c/a1f23b01c54669465f5f4c4083107d496fbe6fb45998771420e9aadcf145/lupa-2.6-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0e21b716408a21ab65723f8841cf7f2f37a844b7a965eeabb785e27fca4099cf", size = 999343, upload-time = "2025-10-24T07:19:12.519Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/6d/501994291cb640bfa2ccf7f554be4e6914afa21c4026bd01bff9ca8aac57/lupa-2.6-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:589db872a141bfff828340079bbdf3e9a31f2689f4ca0d88f97d9e8c2eae6142", size = 2000730, upload-time = "2025-10-24T07:19:14.869Z" },
+    { url = "https://files.pythonhosted.org/packages/53/a5/457ffb4f3f20469956c2d4c4842a7675e884efc895b2f23d126d23e126cc/lupa-2.6-cp314-cp314t-macosx_11_0_x86_64.whl", hash = "sha256:cd852a91a4a9d4dcbb9a58100f820a75a425703ec3e3f049055f60b8533b7953", size = 1021553, upload-time = "2025-10-24T07:19:17.123Z" },
+    { url = "https://files.pythonhosted.org/packages/51/6b/36bb5a5d0960f2a5c7c700e0819abb76fd9bf9c1d8a66e5106416d6e9b14/lupa-2.6-cp314-cp314t-manylinux2010_i686.manylinux_2_12_i686.manylinux_2_28_i686.whl", hash = "sha256:0334753be028358922415ca97a64a3048e4ed155413fc4eaf87dd0a7e2752983", size = 1133275, upload-time = "2025-10-24T07:19:20.51Z" },
+    { url = "https://files.pythonhosted.org/packages/19/86/202ff4429f663013f37d2229f6176ca9f83678a50257d70f61a0a97281bf/lupa-2.6-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:661d895cd38c87658a34780fac54a690ec036ead743e41b74c3fb81a9e65a6aa", size = 1038441, upload-time = "2025-10-24T07:19:22.509Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/42/d8125f8e420714e5b52e9c08d88b5329dfb02dcca731b4f21faaee6cc5b5/lupa-2.6-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6aa58454ccc13878cc177c62529a2056be734da16369e451987ff92784994ca7", size = 2058324, upload-time = "2025-10-24T07:19:24.979Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/2c/47bf8b84059876e877a339717ddb595a4a7b0e8740bacae78ba527562e1c/lupa-2.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:1425017264e470c98022bba8cff5bd46d054a827f5df6b80274f9cc71dafd24f", size = 1060250, upload-time = "2025-10-24T07:19:27.262Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/06/d88add2b6406ca1bdec99d11a429222837ca6d03bea42ca75afa169a78cb/lupa-2.6-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:224af0532d216e3105f0a127410f12320f7c5f1aa0300bdf9646b8d9afb0048c", size = 1151126, upload-time = "2025-10-24T07:19:29.522Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/a0/89e6a024c3b4485b89ef86881c9d55e097e7cb0bdb74efb746f2fa6a9a76/lupa-2.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9abb98d5a8fd27c8285302e82199f0e56e463066f88f619d6594a450bf269d80", size = 2153693, upload-time = "2025-10-24T07:19:31.379Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/36/a0f007dc58fc1bbf51fb85dcc82fcb1f21b8c4261361de7dab0e3d8521ef/lupa-2.6-cp314-cp314t-win32.whl", hash = "sha256:1849efeba7a8f6fb8aa2c13790bee988fd242ae404bd459509640eeea3d1e291", size = 1590104, upload-time = "2025-10-24T07:19:33.514Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/5e/db903ce9cf82c48d6b91bf6d63ae4c8d0d17958939a4e04ba6b9f38b8643/lupa-2.6-cp314-cp314t-win_amd64.whl", hash = "sha256:fc1498d1a4fc028bc521c26d0fad4ca00ed63b952e32fb95949bda76a04bad52", size = 1913818, upload-time = "2025-10-24T07:19:36.039Z" },
+]
+
+[[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 = "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 = "msal"
+version = "1.34.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cryptography" },
+    { name = "pyjwt", extra = ["crypto"] },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cf/0e/c857c46d653e104019a84f22d4494f2119b4fe9f896c92b4b864b3b045cc/msal-1.34.0.tar.gz", hash = "sha256:76ba83b716ea5a6d75b0279c0ac353a0e05b820ca1f6682c0eb7f45190c43c2f", size = 153961, upload-time = "2025-09-22T23:05:48.989Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c2/dc/18d48843499e278538890dc709e9ee3dea8375f8be8e82682851df1b48b5/msal-1.34.0-py3-none-any.whl", hash = "sha256:f669b1644e4950115da7a176441b0e13ec2975c29528d8b9e81316023676d6e1", size = 116987, upload-time = "2025-09-22T23:05:47.294Z" },
+]
+
+[[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 = "openai"
+version = "2.21.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/92/e5/3d197a0947a166649f566706d7a4c8f7fe38f1fa7b24c9bcffe4c7591d44/openai-2.21.0.tar.gz", hash = "sha256:81b48ce4b8bbb2cc3af02047ceb19561f7b1dc0d4e52d1de7f02abfd15aa59b7", size = 644374, upload-time = "2026-02-14T00:12:01.577Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/56/0a89092a453bb2c676d66abee44f863e742b2110d4dbb1dbcca3f7e5fc33/openai-2.21.0-py3-none-any.whl", hash = "sha256:0bc1c775e5b1536c294eded39ee08f8407656537ccc71b1004104fe1602e267c", size = 1103065, upload-time = "2026-02-14T00:11:59.603Z" },
+]
+
+[[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.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/97/b9/3161be15bb8e3ad01be8be5a968a9237c3027c5be504362ff800fca3e442/opentelemetry_api-1.39.1.tar.gz", hash = "sha256:fbde8c80e1b937a2c61f20347e91c0c18a1940cecf012d62e65a7caf08967c9c", size = 65767, upload-time = "2025-12-11T13:32:39.182Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/df/d3f1ddf4bb4cb50ed9b1139cc7b1c54c34a1e7ce8fd1b9a37c0d1551a6bd/opentelemetry_api-1.39.1-py3-none-any.whl", hash = "sha256:2edd8463432a7f8443edce90972169b195e7d6a05500cd29e6d13898187c9950", size = 66356, upload-time = "2025-12-11T13:32:17.304Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-common"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-proto" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/9d/22d241b66f7bbde88a3bfa6847a351d2c46b84de23e71222c6aae25c7050/opentelemetry_exporter_otlp_proto_common-1.39.1.tar.gz", hash = "sha256:763370d4737a59741c89a67b50f9e39271639ee4afc999dadfe768541c027464", size = 20409, upload-time = "2025-12-11T13:32:40.885Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8c/02/ffc3e143d89a27ac21fd557365b98bd0653b98de8a101151d5805b5d4c33/opentelemetry_exporter_otlp_proto_common-1.39.1-py3-none-any.whl", hash = "sha256:08f8a5862d64cc3435105686d0216c1365dc5701f86844a8cd56597d0c764fde", size = 18366, upload-time = "2025-12-11T13:32:20.2Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-grpc"
+version = "1.39.1"
+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/53/48/b329fed2c610c2c32c9366d9dc597202c9d1e58e631c137ba15248d8850f/opentelemetry_exporter_otlp_proto_grpc-1.39.1.tar.gz", hash = "sha256:772eb1c9287485d625e4dbe9c879898e5253fea111d9181140f51291b5fec3ad", size = 24650, upload-time = "2025-12-11T13:32:41.429Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/81/a3/cc9b66575bd6597b98b886a2067eea2693408d2d5f39dad9ab7fc264f5f3/opentelemetry_exporter_otlp_proto_grpc-1.39.1-py3-none-any.whl", hash = "sha256:fa1c136a05c7e9b4c09f739469cbdb927ea20b34088ab1d959a849b5cc589c18", size = 19766, upload-time = "2025-12-11T13:32:21.027Z" },
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/49/1d/f25d76d8260c156c40c97c9ed4511ec0f9ce353f8108ca6e7561f82a06b2/opentelemetry_proto-1.39.1.tar.gz", hash = "sha256:6c8e05144fc0d3ed4d22c2289c6b126e03bcd0e6a7da0f16cedd2e1c2772e2c8", size = 46152, upload-time = "2025-12-11T13:32:48.681Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/95/b40c96a7b5203005a0b03d8ce8cd212ff23f1793d5ba289c87a097571b18/opentelemetry_proto-1.39.1-py3-none-any.whl", hash = "sha256:22cdc78efd3b3765d09e68bfbd010d4fc254c9818afd0b6b423387d9dee46007", size = 72535, upload-time = "2025-12-11T13:32:33.866Z" },
+]
+
+[[package]]
+name = "opentelemetry-sdk"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/fb/c76080c9ba07e1e8235d24cdcc4d125ef7aa3edf23eb4e497c2e50889adc/opentelemetry_sdk-1.39.1.tar.gz", hash = "sha256:cf4d4563caf7bff906c9f7967e2be22d0d6b349b908be0d90fb21c8e9c995cc6", size = 171460, upload-time = "2025-12-11T13:32:49.369Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7c/98/e91cf858f203d86f4eccdf763dcf01cf03f1dae80c3750f7e635bfa206b6/opentelemetry_sdk-1.39.1-py3-none-any.whl", hash = "sha256:4d5482c478513ecb0a5d938dcc61394e647066e0cc2676bee9f3af3f3f45f01c", size = 132565, upload-time = "2025-12-11T13:32:35.069Z" },
+]
+
+[[package]]
+name = "opentelemetry-semantic-conventions"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/91/df/553f93ed38bf22f4b999d9be9c185adb558982214f33eae539d3b5cd0858/opentelemetry_semantic_conventions-0.60b1.tar.gz", hash = "sha256:87c228b5a0669b748c76d76df6c364c369c28f1c465e50f661e39737e84bc953", size = 137935, upload-time = "2025-12-11T13:32:50.487Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7a/5e/5958555e09635d09b75de3c4f8b9cae7335ca545d77392ffe7331534c402/opentelemetry_semantic_conventions-0.60b1-py3-none-any.whl", hash = "sha256:9fa8c8b0c110da289809292b0591220d3a7b53c1526a23021e977d68597893fb", size = 219982, upload-time = "2025-12-11T13:32:36.955Z" },
+]
+
+[[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.4.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/67/93/8f2c2075b180c12c1e9f6a09d1a985bc2036906b13dff1d8917e395f2048/pathable-0.4.4.tar.gz", hash = "sha256:6905a3cd17804edfac7875b5f6c9142a218c7caef78693c2dbbbfbac186d88b2", size = 8124, upload-time = "2025-01-10T18:43:13.247Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7d/eb/b6260b31b1a96386c0a880edebe26f89669098acea8e0318bff6adb378fd/pathable-0.4.4-py3-none-any.whl", hash = "sha256:5ae9e94793b6ef5a4cbe0a7ce9dbbefc1eec38df253763fd0aeeacf2762dbbc2", size = 9592, upload-time = "2025-01-10T18:43:11.88Z" },
+]
+
+[[package]]
+name = "pdbpp"
+version = "0.12.0.post1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "fancycompleter" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5b/23/0bd339679059fb289e0752671b5eac63a472742d1de0035e13a27429e500/pdbpp-0.12.0.post1.tar.gz", hash = "sha256:cace9951d7414fe651141d240ab20e4509c8f97d20f7b142386d1bd1bb182d18", size = 75765, upload-time = "2026-01-19T10:56:55.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/28/f2/20fa391af27da4ef421832fb7d554748786efcc3b0da69a51e2ca66043d0/pdbpp-0.12.0.post1-py3-none-any.whl", hash = "sha256:8c62acd6adaa02f620d7d9cff689208a28019b6c05e6b894318f313e61fb1dc7", size = 30661, upload-time = "2026-01-19T10:56:53.638Z" },
+]
+
+[[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.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/04/fea538adf7dbbd6d186f551d595961e564a3b6715bdf276b477460858672/platformdirs-4.9.2.tar.gz", hash = "sha256:9a33809944b9db043ad67ca0db94b14bf452cc6aeaac46a88ea55b26e2e9d291", size = 28394, upload-time = "2026-02-16T03:56:10.574Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/48/31/05e764397056194206169869b50cf2fee4dbbbc71b344705b9c0d878d4d8/platformdirs-4.9.2-py3-none-any.whl", hash = "sha256:9170634f126f8efdae22fb58ae8a0eaa86f38365bc57897a6c4f781d1f5875bd", size = 21168, upload-time = "2026-02-16T03:56:08.891Z" },
+]
+
+[[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.8.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cyclopts" },
+    { name = "pydantic" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/04/32/e7bc3db47cd93e2683241bd2a328b3136c44c4332a4277a2ac2f3f6beca4/prefab_ui-0.8.3.tar.gz", hash = "sha256:bfe1304f0fc457da764763232f533bff732160e8cc8ce12977ba48f8e7574152", size = 2819196, upload-time = "2026-02-27T14:44:10.52Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ed/23/cbc8decc176428a1f03b676fee4242f8a8d0ae7e76d5fc76ff96f13f13c1/prefab_ui-0.8.3-py3-none-any.whl", hash = "sha256:b1bac064958f08b20694e67b916ad8ab82de8db883578c31ba4437b521b425e1", size = 803888, upload-time = "2026-02-27T14:44:09.31Z" },
 ]
 
 [[package]]
-name = "gitdb"
-version = "4.0.11"
+name = "prek"
+version = "0.3.3"
 source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "smmap" },
+sdist = { url = "https://files.pythonhosted.org/packages/bf/f1/7613dc8347a33e40fc5b79eec6bc7d458d8bbc339782333d8433b665f86f/prek-0.3.3.tar.gz", hash = "sha256:117bd46ebeb39def24298ce021ccc73edcf697b81856fcff36d762dd56093f6f", size = 343697, upload-time = "2026-02-15T13:33:28.723Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2d/8b/dce13d2a3065fd1e8ffce593a0e51c4a79c3cde9c9a15dc0acc8d9d1573d/prek-0.3.3-py3-none-linux_armv6l.whl", hash = "sha256:e8629cac4bdb131be8dc6e5a337f0f76073ad34a8305f3fe2bc1ab6201ede0a4", size = 4644636, upload-time = "2026-02-15T13:33:43.609Z" },
+    { url = "https://files.pythonhosted.org/packages/01/30/06ab4dbe7ce02a8ce833e92deb1d9a8e85ae9d40e33d1959a2070b7494c6/prek-0.3.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:4b9e819b9e4118e1e785047b1c8bd9aec7e4d836ed034cb58b7db5bcaaf49437", size = 4651410, upload-time = "2026-02-15T13:33:34.277Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fc/da3bc5cb38471e7192eda06b7a26b7c24ef83e82da2c1dbc145f2bf33640/prek-0.3.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:bf29db3b5657c083eb8444c25aadeeec5167dc492e9019e188f87932f01ea50a", size = 4273163, upload-time = "2026-02-15T13:33:42.106Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/74/47839395091e2937beced81a5dd2f8ea9c8239c853da8611aaf78ee21a8b/prek-0.3.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:ae09736149815b26e64a9d350ca05692bab32c2afdf2939114d3211aaad68a3e", size = 4631808, upload-time = "2026-02-15T13:33:20.076Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/89/3f5ef6f7c928c017cb63b029349d6bc03598ab7f6979d4a770ce02575f82/prek-0.3.3-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:856c2b55c51703c366bb4ce81c6a91102b70573a9fc8637db2ac61c66e4565f9", size = 4548959, upload-time = "2026-02-15T13:33:36.325Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/18/80002c4c4475f90ca025f27739a016927a0e5d905c60612fc95da1c56ab7/prek-0.3.3-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3acdf13a018f685beaff0a71d4b0d2ccbab4eaa1aced6d08fd471c1a654183eb", size = 4862256, upload-time = "2026-02-15T13:33:37.754Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/25/648bf084c2468fa7cfcdbbe9e59956bbb31b81f36e113bc9107d80af26a7/prek-0.3.3-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0f035667a8bd0a77b2bfa2b2e125da8cb1793949e9eeef0d8daab7f8ac8b57fe", size = 5404486, upload-time = "2026-02-15T13:33:39.239Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/43/261fb60a11712a327da345912bd8b338dc5a050199de800faafa278a6133/prek-0.3.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d09b2ad14332eede441d977de08eb57fb3f61226ed5fd2ceb7aadf5afcdb6794", size = 4887513, upload-time = "2026-02-15T13:33:40.702Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/2c/581e757ee57ec6046b32e0ee25660fc734bc2622c319f57119c49c0cab58/prek-0.3.3-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:c0c3ffac16e37a9daba43a7e8316778f5809b70254be138761a8b5b9ef0df28e", size = 4632336, upload-time = "2026-02-15T13:33:25.867Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/d8/aa276ce5d11b77882da4102ca0cb7161095831105043ae7979bbfdcc3dc4/prek-0.3.3-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:a3dc7720b580c07c0386e17af2486a5b4bc2f6cc57034a288a614dcbc4abe555", size = 4679370, upload-time = "2026-02-15T13:33:22.247Z" },
+    { url = "https://files.pythonhosted.org/packages/70/19/9d4fa7bde428e58d9f48a74290c08736d42aeb5690dcdccc7a713e34a449/prek-0.3.3-py3-none-musllinux_1_1_armv7l.whl", hash = "sha256:60e0fa15da5020a03df2ee40268145ec5b88267ec2141a205317ad4df8c992d6", size = 4540316, upload-time = "2026-02-15T13:33:24.088Z" },
+    { url = "https://files.pythonhosted.org/packages/25/b5/973cce29257e0b47b16cc9b4c162772ea01dbb7c080791ea0c068e106e05/prek-0.3.3-py3-none-musllinux_1_1_i686.whl", hash = "sha256:553515da9586d9624dc42db32b744fdb91cf62b053753037a0cadb3c2d8d82a2", size = 4724566, upload-time = "2026-02-15T13:33:29.832Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/8b/ad8b2658895a8ed2b0bc630bf38686fe38b7ff2c619c58953a80e4de3048/prek-0.3.3-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:9512cf370e0d1496503463a4a65621480efb41b487841a9e9ff1661edf14b238", size = 4995072, upload-time = "2026-02-15T13:33:27.417Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/b7/0540c101c00882adb9d30319d22d8f879413598269ecc60235e41875efd4/prek-0.3.3-py3-none-win32.whl", hash = "sha256:b2b328c7c6dc14ccdc79785348589aa39850f47baff33d8f199f2dee80ff774c", size = 4293144, upload-time = "2026-02-15T13:33:46.013Z" },
+    { url = "https://files.pythonhosted.org/packages/97/c7/e4f11da653093040efba2d835aa0995d78940aea30887287aeaebe34a545/prek-0.3.3-py3-none-win_amd64.whl", hash = "sha256:3d7d7acf7ca8db65ba0943c52326c898f84bab0b1c26a35c87e0d177f574ca5f", size = 4652761, upload-time = "2026-02-15T13:33:32.962Z" },
+    { url = "https://files.pythonhosted.org/packages/11/e4/d99dec54c6a5fb2763488bff6078166383169a93f3af27d2edae88379a39/prek-0.3.3-py3-none-win_arm64.whl", hash = "sha256:8aa87ee7628cd74482c0dd6537a3def1f162b25cd642d78b1b35dd3e81817f60", size = 4367520, upload-time = "2026-02-15T13:33:31.664Z" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/19/0d/bbb5b5ee188dec84647a4664f3e11b06ade2bde568dbd489d9d64adef8ed/gitdb-4.0.11.tar.gz", hash = "sha256:bf5421126136d6d0af55bc1e7c1af1c397a34f5b7bd79e776cd3e89785c2b04b", size = 394469 }
+
+[[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/fd/5b/8f0c4a5bb9fd491c277c21eff7ccae71b47d43c4446c9d0c6cff2fe8c2c4/gitdb-4.0.11-py3-none-any.whl", hash = "sha256:81a3407ddd2ee8df444cbacea00e2d038e40150acfa3001696fe0dcf1d3adfa4", size = 62721 },
+    { 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 = "gitpython"
-version = "3.1.43"
+name = "prompt-toolkit"
+version = "3.0.52"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "gitdb" },
+    { name = "wcwidth" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b6/a1/106fd9fa2dd989b6fb36e5893961f82992cf676381707253e0bf93eb1662/GitPython-3.1.43.tar.gz", hash = "sha256:35f314a9f878467f5453cc1fee295c3e18e52f1b99f10f6cf5b1682e968a9e7c", size = 214149 }
+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/e9/bd/cc3a402a6439c15c3d4294333e13042b915bbeab54edc457c723931fed3f/GitPython-3.1.43-py3-none-any.whl", hash = "sha256:eec7ec56b92aad751f9912a73404bc02ba212a23adb2c7098ee668417051a1ff", size = 207337 },
+    { 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 = "h11"
-version = "0.14.0"
+name = "protobuf"
+version = "6.33.5"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f5/38/3af3d3633a34a3316095b39c8e8fb4853a28a536e55d347bd8d8e9a14b03/h11-0.14.0.tar.gz", hash = "sha256:8f19fbbe99e72420ff35c00b27a34cb9937e902a8b810e2c88300c6f0a3b699d", size = 100418 }
+sdist = { url = "https://files.pythonhosted.org/packages/ba/25/7c72c307aafc96fa87062aa6291d9f7c94836e43214d43722e86037aac02/protobuf-6.33.5.tar.gz", hash = "sha256:6ddcac2a081f8b7b9642c09406bc6a4290128fce5f471cddd165960bb9119e5c", size = 444465, upload-time = "2026-01-29T21:51:33.494Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/95/04/ff642e65ad6b90db43e668d70ffb6736436c7ce41fcc549f4e9472234127/h11-0.14.0-py3-none-any.whl", hash = "sha256:e3fe4ac4b851c468cc8363d500db52c2ead036020723024a109d37346efaa761", size = 58259 },
+    { url = "https://files.pythonhosted.org/packages/b1/79/af92d0a8369732b027e6d6084251dd8e782c685c72da161bd4a2e00fbabb/protobuf-6.33.5-cp310-abi3-win32.whl", hash = "sha256:d71b040839446bac0f4d162e758bea99c8251161dae9d0983a3b88dee345153b", size = 425769, upload-time = "2026-01-29T21:51:21.751Z" },
+    { url = "https://files.pythonhosted.org/packages/55/75/bb9bc917d10e9ee13dee8607eb9ab963b7cf8be607c46e7862c748aa2af7/protobuf-6.33.5-cp310-abi3-win_amd64.whl", hash = "sha256:3093804752167bcab3998bec9f1048baae6e29505adaf1afd14a37bddede533c", size = 437118, upload-time = "2026-01-29T21:51:24.022Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/6b/e48dfc1191bc5b52950246275bf4089773e91cb5ba3592621723cdddca62/protobuf-6.33.5-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:a5cb85982d95d906df1e2210e58f8e4f1e3cdc088e52c921a041f9c9a0386de5", size = 427766, upload-time = "2026-01-29T21:51:25.413Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/b1/c79468184310de09d75095ed1314b839eb2f72df71097db9d1404a1b2717/protobuf-6.33.5-cp39-abi3-manylinux2014_aarch64.whl", hash = "sha256:9b71e0281f36f179d00cbcb119cb19dec4d14a81393e5ea220f64b286173e190", size = 324638, upload-time = "2026-01-29T21:51:26.423Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/f5/65d838092fd01c44d16037953fd4c2cc851e783de9b8f02b27ec4ffd906f/protobuf-6.33.5-cp39-abi3-manylinux2014_s390x.whl", hash = "sha256:8afa18e1d6d20af15b417e728e9f60f3aa108ee76f23c3b2c07a2c3b546d3afd", size = 339411, upload-time = "2026-01-29T21:51:27.446Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/53/a9443aa3ca9ba8724fdfa02dd1887c1bcd8e89556b715cfbacca6b63dbec/protobuf-6.33.5-cp39-abi3-manylinux2014_x86_64.whl", hash = "sha256:cbf16ba3350fb7b889fca858fb215967792dc125b35c7976ca4818bee3521cf0", size = 323465, upload-time = "2026-01-29T21:51:28.925Z" },
+    { url = "https://files.pythonhosted.org/packages/57/bf/2086963c69bdac3d7cff1cc7ff79b8ce5ea0bec6797a017e1be338a46248/protobuf-6.33.5-py3-none-any.whl", hash = "sha256:69915a973dd0f60f31a08b8318b73eab2bd6a392c79184b3612226b0a3f8ec02", size = 170687, upload-time = "2026-01-29T21:51:32.557Z" },
 ]
 
 [[package]]
-name = "httpcore"
-version = "1.0.7"
+name = "psutil"
+version = "7.2.2"
 source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "certifi" },
-    { name = "h11" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/6a/41/d7d0a89eb493922c37d343b607bc1b5da7f5be7e383740b4753ad8943e90/httpcore-1.0.7.tar.gz", hash = "sha256:8551cb62a169ec7162ac7be8d4817d561f60e08eaa485234898414bb5a8a0b4c", size = 85196 }
+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/87/f5/72347bc88306acb359581ac4d52f23c0ef445b57157adedb9aee0cd689d2/httpcore-1.0.7-py3-none-any.whl", hash = "sha256:a3fff8f43dc260d5bd363d9f9cf1830fa3a458b332856f34282de498ed420edd", size = 78551 },
+    { 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 = "httpx"
-version = "0.28.0"
+name = "ptyprocess"
+version = "0.7.0"
 source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "certifi" },
-    { name = "httpcore" },
-    { name = "idna" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/10/df/676b7cf674dd1bdc71a64ad393c89879f75e4a0ab8395165b498262ae106/httpx-0.28.0.tar.gz", hash = "sha256:0858d3bab51ba7e386637f22a61d8ccddaeec5f3fe4209da3a6168dbb91573e0", size = 141307 }
+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/8f/fb/a19866137577ba60c6d8b69498dc36be479b13ba454f691348ddf428f185/httpx-0.28.0-py3-none-any.whl", hash = "sha256:dc0b419a0cfeb6e8b34e85167c0da2671206f5095f1baa9663d23bcfd6b535fc", size = 73551 },
+    { 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 = "httpx-sse"
-version = "0.4.0"
+name = "pure-eval"
+version = "0.2.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/4c/60/8f4281fa9bbf3c8034fd54c0e7412e66edbab6bc74c4996bd616f8d0406e/httpx-sse-0.4.0.tar.gz", hash = "sha256:1e81a3a3070ce322add1d3529ed42eb5f70817f45ed6ec915ab753f961139721", size = 12624 }
+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/e1/9b/a181f281f65d776426002f330c31849b86b31fc9d848db62e16f03ff739f/httpx_sse-0.4.0-py3-none-any.whl", hash = "sha256:f329af6eae57eaa2bdfd962b42524764af68075ea87370a2de920af5341e318f", size = 7819 },
+    { 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 = "idna"
-version = "3.10"
+name = "py-key-value-aio"
+version = "0.4.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f1/70/7703c29685631f5a7590aa73f1f1d3fa9a380e654b86af429e0934a32f7d/idna-3.10.tar.gz", hash = "sha256:12f65c9b470abda6dc35cf8e63cc574b1c52b11df2c86030af0ac09b01b13ea9", size = 190490 }
+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/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl", hash = "sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3", size = 70442 },
+    { 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 = "iniconfig"
-version = "2.0.0"
+name = "pyasn1"
+version = "0.6.2"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d7/4b/cbd8e699e64a6f16ca3a8220661b5f83792b3017d0f79807cb8708d33913/iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3", size = 4646 }
+sdist = { url = "https://files.pythonhosted.org/packages/fe/b6/6e630dff89739fcd427e3f72b3d905ce0acb85a45d4ec3e2678718a3487f/pyasn1-0.6.2.tar.gz", hash = "sha256:9b59a2b25ba7e4f8197db7686c09fb33e658b98339fadb826e9512629017833b", size = 146586, upload-time = "2026-01-16T18:04:18.534Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ef/a6/62565a6e1cf69e10f5727360368e451d4b7f58beeac6173dc9db836a5b46/iniconfig-2.0.0-py3-none-any.whl", hash = "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374", size = 5892 },
+    { url = "https://files.pythonhosted.org/packages/44/b5/a96872e5184f354da9c84ae119971a0a4c221fe9b27a4d94bd43f2596727/pyasn1-0.6.2-py3-none-any.whl", hash = "sha256:1eb26d860996a18e9b6ed05e7aae0e9fc21619fcee6af91cca9bad4fbea224bf", size = 83371, upload-time = "2026-01-16T18:04:17.174Z" },
 ]
 
 [[package]]
-name = "ipython"
-version = "8.12.3"
+name = "pyasn1-modules"
+version = "0.4.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "appnope", marker = "sys_platform == 'darwin'" },
-    { name = "backcall" },
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-    { name = "decorator" },
-    { name = "jedi" },
-    { name = "matplotlib-inline" },
-    { name = "pexpect", marker = "sys_platform != 'win32'" },
-    { name = "pickleshare" },
-    { name = "prompt-toolkit" },
-    { name = "pygments" },
-    { name = "stack-data" },
-    { name = "traitlets" },
+    { name = "pyasn1" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9e/6a/44ef299b1762f5a73841e87fae8a73a8cc8aee538d6dc8c77a5afe1fd2ce/ipython-8.12.3.tar.gz", hash = "sha256:3910c4b54543c2ad73d06579aa771041b7d5707b033bd488669b4cf544e3b363", size = 5470171 }
+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/8d/97/8fe103906cd81bc42d3b0175b5534a9f67dccae47d6451131cf8d0d70bb2/ipython-8.12.3-py3-none-any.whl", hash = "sha256:b0340d46a933d27c657b211a329d0be23793c36595acf9e6ef4164bc01a1804c", size = 798307 },
+    { 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 = "jedi"
-version = "0.19.2"
+name = "pycparser"
+version = "3.0"
 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 }
+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/c0/5a/9cac0c82afec3d09ccd97c8b6502d48f165f9124db81b4bcb90b4af974ee/jedi-0.19.2-py2.py3-none-any.whl", hash = "sha256:a8ef22bde8490f57fe5c7681a3c83cb58874daf72b4784de3cce5b6ef6edb5b9", size = 1572278 },
+    { 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 = "markdown-it-py"
-version = "3.0.0"
+name = "pydantic"
+version = "2.12.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "mdurl" },
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/38/71/3b932df36c1a044d397a1f92d1cf91ee0a503d91e470cbd670aa66b07ed0/markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb", size = 74596 }
+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/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1", size = 87528 },
+    { 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 = "matplotlib-inline"
-version = "0.1.7"
+name = "pydantic-core"
+version = "2.41.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "traitlets" },
+    { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/99/5b/a36a337438a14116b16480db471ad061c36c3694df7c2084a0da7ba538b7/matplotlib_inline-0.1.7.tar.gz", hash = "sha256:8423b23ec666be3d16e16b60bdd8ac4e86e840ebd1dd11a30b9f117f2fa0ab90", size = 8159 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/8f/8e/9ad090d3553c280a8060fbf6e24dc1c0c29704ee7d1c372f0c174aa59285/matplotlib_inline-0.1.7-py3-none-any.whl", hash = "sha256:df192d39a4ff8f21b1895d72e6a13f5fcc5099f00fa84384e0ea28c2cc0653ca", size = 9899 },
+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.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/e3/0d8b2b025628477c839f894e632f5197872b19df0a86b2ec30fac3b5960a/pydantic_monty-0.0.7.tar.gz", hash = "sha256:2189ea1d7aadab2f95374733d692f51d1206379a4fc7ce18ab46895512e88f92", size = 684705, upload-time = "2026-02-19T14:12:47.235Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e3/25/4f923b64c6d52e2de788b21e20feb6a1acd0063419751a4cd843aa94c3de/pydantic_monty-0.0.7-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:8a8c133e83dcea584c17d4a18f4370d702f28c030b24be4aa033a8d094212b46", size = 6265462, upload-time = "2026-02-19T14:13:08.332Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/3f/6171caec0df775992b8aa4bbb862939e63fb49cab50db4c5329afa96590b/pydantic_monty-0.0.7-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:712c8db9fa80e6695aa5a829d5ed570f00bec071fe73cf32ed20d8ad7c21f83e", size = 6158093, upload-time = "2026-02-19T14:12:51.337Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/41/cd683e3546a32a489c1a43bc1d82653c4b62690525209bea23c9e9b6f986/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7be373ba4acfcdd2047215f0675afb0cae2942ebd91f4d7f27a11ed224510432", size = 6060244, upload-time = "2026-02-19T14:14:36.326Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/f1/326a61cb35b2a26e6a1f640359f91522c8ab4868d9d9fd81ec9fe846e29a/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:98446b6cf32de3b1ad9e84b101f3db34a8799af35c95643068587d596f06b558", size = 6311667, upload-time = "2026-02-19T14:13:33.079Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/3a/67d811f258a3ccff2ab2e2669792294ff47e875e0c305536adb19c68ee74/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b725086fb5c4b7205cf85b243c19596bb53cd24c35764f09a55454a23c1f0e37", size = 6861045, upload-time = "2026-02-19T14:13:06.35Z" },
+    { url = "https://files.pythonhosted.org/packages/35/88/27cf345219b9504c58da2c53e2280fbac2b353d0c0afe7ab9d34d3ca0701/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:94a43fcdfe607f25a0ba822f325610ca7018d73de4836c3eca27dac2a23fec7a", size = 6868099, upload-time = "2026-02-19T14:14:22.68Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/ef/9ff941e2357d8ecdc577c999995055e42e9c382a13d72eff594a21d2c285/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8b123fd3ef7d4b228381678fc3292b377e2a1f729a52beb31358313b49e2dcdb", size = 6641962, upload-time = "2026-02-19T14:14:43.196Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/67/a63b73e5e0d5434e388b5c74eb7f11191afe44ccc8a4cbd6055edc708aa9/pydantic_monty-0.0.7-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c61bc830acc85a4ca875903885eaa17322e8289d53e4ca6abe6a15a4a7998bd5", size = 6690453, upload-time = "2026-02-19T14:13:55.307Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/f6/f16238540591b3bb829925f2911bd4a257da2ac5c39acaeef5f70cac8ee6/pydantic_monty-0.0.7-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:a6b71a66837ca73e107e8bf31e1a715a7fe84b2d3d3b5e760bfeb206f00e68f6", size = 6236989, upload-time = "2026-02-19T14:14:17.242Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/21/0ff2e16249157a64b60e359e4d35c82559829e281bbd1ba42693af143136/pydantic_monty-0.0.7-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:b8f9221339ff3ba95ded5f69760f974fdffdb41f19b5234b5ccf19b183667849", size = 6671096, upload-time = "2026-02-19T14:13:42.853Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/53/8545e1c059225304938cf07d29aead0c7617ae05c6b2040957cd8f039a84/pydantic_monty-0.0.7-cp310-cp310-win32.whl", hash = "sha256:c6f2b930cdaac5dafca862813c3cf192071d93d3e1f15f952902dccec106b1d1", size = 6134622, upload-time = "2026-02-19T14:12:53.517Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/de/e7247a58787f0001f5119cc385f8f3868e7850b5342974534778dbaf900d/pydantic_monty-0.0.7-cp310-cp310-win_amd64.whl", hash = "sha256:8e0fefba589a443538d4df90b2bfb4a23722bd838146f3419276f22f665aa2e0", size = 6694493, upload-time = "2026-02-19T14:14:30.997Z" },
+    { url = "https://files.pythonhosted.org/packages/83/30/7f9432e9923b9b60c732364d75bce7ea4b22a6a18c6d7345078dac27d6e2/pydantic_monty-0.0.7-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:1ff6197ef4fd71e5f03c4b8d4228e387705fcad3798b1ea19c23594f7ea26660", size = 6265108, upload-time = "2026-02-19T14:13:31.46Z" },
+    { url = "https://files.pythonhosted.org/packages/01/3f/ab7d83cf4dc0f9ac075d3edcee897f71a1efdd7659570a74abe1780cb769/pydantic_monty-0.0.7-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:649209a0a401969e86ac46014e8967636a7f5c4dbccd3bd22134eba8c3a7be6e", size = 6156865, upload-time = "2026-02-19T14:13:57.05Z" },
+    { url = "https://files.pythonhosted.org/packages/98/f9/9471a56881ba8b2b87dc6bc274194fb3e0d58ad61d1ee17a6427690c951e/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:300dc5dcaae167f61540037cc5cb66ee63edb39298e04807472afd6f14c7d4cf", size = 6059238, upload-time = "2026-02-19T14:14:48.648Z" },
+    { url = "https://files.pythonhosted.org/packages/10/6a/99c6d9eadf38e64d7b198becf481642f1352882b79d12342d29f4984098e/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6392ab97cdd1290e6dfb7bdb13c328df75b08b3a25aa2a6f84b117c8f3688428", size = 6310805, upload-time = "2026-02-19T14:14:40.343Z" },
+    { url = "https://files.pythonhosted.org/packages/11/9d/327dc638a17f1aefee843743382f0aa32efce297d6a43011025a1fc9fa7d/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ac3a30019322d328ac6217c6bdbbe7c17b24fd2dd1015b4c334094213445cd30", size = 6859696, upload-time = "2026-02-19T14:14:29.198Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/38/ae57ee792a30c1421cdb84f738573c883989215658a590010eb8012139e6/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:242d757c42ad53bab2be676588dd5b301e2e77420e79cc6f009256bf3b76472e", size = 6867309, upload-time = "2026-02-19T14:12:58.645Z" },
+    { url = "https://files.pythonhosted.org/packages/19/a2/b6bac68b3b100089dda7d45456260d73563ca76775bb83298120f2666853/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9c9edcec7e6543bc1188a299debb706a47261b28cfb6157ec8181f70a463f735", size = 6640874, upload-time = "2026-02-19T14:12:49.002Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/04/cf4847759d9f5069daad414266502c42e59b2c93b496e76478afce861121/pydantic_monty-0.0.7-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e1b2f45bbeb09f68f99fd301fcd370f7b03152f2935a5c65533c86c11b9377eb", size = 6690344, upload-time = "2026-02-19T14:13:18.926Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/e9/b3bcd311599e01c66d7821798ad926e51e02569ddeb57506c5db2df85cb0/pydantic_monty-0.0.7-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:8275e24a44c43c0125c5d558ead78f750d891d6a11995bf750eabb0781086a40", size = 6235416, upload-time = "2026-02-19T14:13:16.188Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/d8/b545fd3f3d473e47a081815b3521bab36f68788b3d921b4b03de648d4986/pydantic_monty-0.0.7-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:a1910fb89e52a2b3b8413cc4c30d3bc353f1a8a622e67e6d0c1030c5dc86931c", size = 6670652, upload-time = "2026-02-19T14:14:03.149Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/fe/e209b45ece1cdce88dad03033497e0f49525d348f5c5a2e60f7d6d78da1b/pydantic_monty-0.0.7-cp311-cp311-win32.whl", hash = "sha256:899f68f6b3a4808a6d73292f819cad85f50a4301b018322d2ce3473488c56959", size = 6133507, upload-time = "2026-02-19T14:12:55.433Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/70/6b8f6b0427b7c1bf5c1d6bffcf68c5f2902c8f31304eaf0ebed5b2d4d475/pydantic_monty-0.0.7-cp311-cp311-win_amd64.whl", hash = "sha256:12456fbf22df015a78abcdb9f8bd1f8227673a93e781263ae9b9c6e2524b5cd6", size = 6693590, upload-time = "2026-02-19T14:14:04.834Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/7e/ca0884108c3237bb15bb2a1b3f24ddd957b9c750f1ed3211801497941999/pydantic_monty-0.0.7-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:f35e18f284524d26d5f27084e2b93eb40139055bbf0cab6221a043eb5e9ce2dc", size = 6264252, upload-time = "2026-02-19T14:13:59.317Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/5b/31f70c7792a857bacbdce90b8aae4629c31a9fec35f0116d91a2fb53241b/pydantic_monty-0.0.7-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8e5d8924c65bb1ced60785a156e28c73f7f79f164b4f090dc26312c3917ffff7", size = 6133285, upload-time = "2026-02-19T14:14:46.577Z" },
+    { url = "https://files.pythonhosted.org/packages/42/56/c92216c0427e8a10a01fa98f29252f6fabd8ca80ca193e0fd30fe28e65c1/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6279a468469d5a3b80d94dd0ab6110cd291a1dfbb057fa7d6dbad1f499be855d", size = 6059856, upload-time = "2026-02-19T14:13:02.594Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/a7/bc3e67b12d8a9da65f2677d9a48bc1e055a1d853d48572ba4845a64075cf/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cb5feb69a5902d059db5dab269f90423b85a22163668422be47ccac8d7f7c44a", size = 6313780, upload-time = "2026-02-19T14:13:46.45Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/97/a9b856b17ee1e54892dafbb7ea29305520cae2dcd8aafe82a26a0edbc33c/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a2f1913e9729aa6711092ecbfce764df199a4787fe3e23a7ed74c78bf846579e", size = 6856827, upload-time = "2026-02-19T14:13:40.836Z" },
+    { url = "https://files.pythonhosted.org/packages/98/57/2d8184b9f5a0b2b3bb47fdad7061c6a182699824efe6de9d8dd19ee68c0a/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ec528f9f4194e6298757ad99e25da47f06f49ae2bc176ee26f49da5eb1dd7849", size = 6870737, upload-time = "2026-02-19T14:13:53.602Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/b3/fe3d3eff82b41e517739841a492d7a48ea2daf8e7b822299b848b5d4c0aa/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:75405b9186a9acfa49cd66aa339b5a2450d733a2d59fae20cc8be45e45204d5f", size = 6611843, upload-time = "2026-02-19T14:13:49.957Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/d2/fdd8fe135ea14e30b40adadc896dda6c805596688998c9bcdfd8d85a16cf/pydantic_monty-0.0.7-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1917e42fce4733f92f5f6ad64ae4d0e87abbf9fb284ef52589ac3e292e928bfe", size = 6692856, upload-time = "2026-02-19T14:13:00.635Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/a6/fdde6f8d76aa0cff4b53060b63d7f09dbb19da61a967cb4b3dfd972acf1c/pydantic_monty-0.0.7-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:d72a5d4f3ee7f9d2630b0379e4cfb397e181eb0b16e8c49a03f80ba6471edb89", size = 6236587, upload-time = "2026-02-19T14:14:32.602Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/7e/0580bbc001a39252b2f7da4b7504ac10572e4ca0ec967aebc5a9d752b6f7/pydantic_monty-0.0.7-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:20028220981516912f130986354ef6c926b98778146ca349560cb852e44d9ca6", size = 6672260, upload-time = "2026-02-19T14:13:26.527Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/53/578a7b781a5714db5c4b1989c6e876d30caa0adf8a5a4caad89abc306667/pydantic_monty-0.0.7-cp312-cp312-win32.whl", hash = "sha256:e28b1c3ed52892f8ac12ee0f2b535402dfe1cb1e5c18128f1cb69eb8b66c285a", size = 6131085, upload-time = "2026-02-19T14:14:13.296Z" },
+    { url = "https://files.pythonhosted.org/packages/56/98/20bd45fcd472937b1b3438b7587e209e3cfd447c30d02f654b86b44adaad/pydantic_monty-0.0.7-cp312-cp312-win_amd64.whl", hash = "sha256:031dfab63ff9d7acdc641852e0d822603038cef1c27c5060900b9fd51cc853d0", size = 6664431, upload-time = "2026-02-19T14:13:29.968Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/fe/d8cb6c30d9d7bcc7d3c8d2c349a227e2a83cd1fbe7182f4941896eb35443/pydantic_monty-0.0.7-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:55d36818f8e35872ed35e395b41df8acc460bcdbbfd471fe0c39e293a1d50db5", size = 6262596, upload-time = "2026-02-19T14:14:15.2Z" },
+    { url = "https://files.pythonhosted.org/packages/81/7a/f6b4881ca9779bd87eb8d8c0823133b56c232cf09d765c07a7f91d641490/pydantic_monty-0.0.7-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:acb437458d93d54a9658656545fb6c9b396dbe66f68633b3c57bfd2f4aa1d400", size = 6133793, upload-time = "2026-02-19T14:14:06.498Z" },
+    { url = "https://files.pythonhosted.org/packages/39/b9/dfcffd95ff233b8c98db9254242d9c10190989762016d18509aa04d43b1b/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b196345ffa1997041cb870ea693148feafe270575e2c2963532eedde0e84dedf", size = 6059400, upload-time = "2026-02-19T14:13:38.953Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/2e/d6ecef842024267ddf4128613342b8985a7444e74f3a4a312713c913a91a/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d471e3cfe77d62edaf43b7f0962b95270ee4243abea12cb8e8cf1ad972dc3612", size = 6312625, upload-time = "2026-02-19T14:13:36.901Z" },
+    { url = "https://files.pythonhosted.org/packages/75/2e/e4a2a9fbc3640bcee15b80c2f8ba0f97bf989c58c01d6da187524f71d12b/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3a67771afd385579bf3f894ce933fb9e467fba9a632ccf27246e271d448f6f5f", size = 6859902, upload-time = "2026-02-19T14:14:26.67Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/4a/7aaf5c793f52e3403892a2de1f5dd18ae38234d82111cc9b7d92443e5b0d/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bf662e1bbee4ddd318d5b8bfa9233173045029be0f67f15f816955b246bb7ec0", size = 6870524, upload-time = "2026-02-19T14:13:28.208Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/a9/c16f078864a273460923f1371b769c2719e1ce1ad86bc9031e3ed7fb3eae/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0151ff59a8a0d9e29ddb448affa33943108121e6e324795646a2f5facaf1a5d8", size = 6611960, upload-time = "2026-02-19T14:14:38.812Z" },
+    { url = "https://files.pythonhosted.org/packages/20/d3/b3ef3432558a8cc9551d8b80a028a0f51cd2a518275932e03359eac3dc39/pydantic_monty-0.0.7-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:45f17a65134d3a0031e1f54d143770699f6a0ce92a1e74f0ae4914e52370f058", size = 6691834, upload-time = "2026-02-19T14:13:34.661Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/56/1ab5d1cbc0edfb522f0c28c9f5a7fc74eea6355234f73833087524d034bf/pydantic_monty-0.0.7-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:ede6e68cb8a1f7216e26b0b2fb6cd0eae7a92104be8a49d1042e9e428de9262b", size = 6235704, upload-time = "2026-02-19T14:13:48.276Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/d1/cdebae67b0543f696ed7daff8587dc8a458e6552b52d5877cb8e55be74b4/pydantic_monty-0.0.7-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:4b2fd51eea05a0cc37bb91f326efdb1acbcd4b8262dac1c55aeb208e51254978", size = 6671530, upload-time = "2026-02-19T14:12:56.96Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/53/c0dacaec260b71050fd6b31d09570f9d74bbb2a2e9586032694e92b9fa59/pydantic_monty-0.0.7-cp313-cp313-win32.whl", hash = "sha256:40f2092970c5899ac2a2784d712a4c7e194b33cd0133315254e4baf141cd6c93", size = 6130341, upload-time = "2026-02-19T14:14:09.701Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/05/31490a7a899d8bbb2e513630ea6f591ceb8a111c91fe7573a96c9f6b6327/pydantic_monty-0.0.7-cp313-cp313-win_amd64.whl", hash = "sha256:42cee2646415bb9bd7da428d169783203618a418f960c6f75c7a74d6946d6b31", size = 6664341, upload-time = "2026-02-19T14:14:19.008Z" },
+    { url = "https://files.pythonhosted.org/packages/99/15/64aff358df0b822dd22f212fec501e3944edffe978a4ab05530ea641dc68/pydantic_monty-0.0.7-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:c97b2e1dcd0126417892595c1da724a8c4348f7dcec26ba774117bd51bde46f8", size = 6266090, upload-time = "2026-02-19T14:13:12.364Z" },
+    { url = "https://files.pythonhosted.org/packages/64/90/7b5a4292eb9993eb8be9d958b5a57764818eeda471e3e79be7da4e9b49ba/pydantic_monty-0.0.7-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:6f40e6e133b309ba733874f5980ab6cf867ec8cea2a6a389a641819cd8dcb7cd", size = 6152219, upload-time = "2026-02-19T14:13:20.734Z" },
+    { url = "https://files.pythonhosted.org/packages/43/e4/2740af0157eb3c6f10c16b0d8376b8c9cf0b910720fe90229885bccb4a91/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:57f2a327b6aa7402a2b2c3ddb3964bd45f12597f8f950dd4c5905b843b353b73", size = 6060942, upload-time = "2026-02-19T14:12:45.601Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/26/1cf235c2cc8e219a94ed8b11151280ba89e8020a475b6280c89e62f7275f/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:771f1f158af0de2480ea2a8862e4c0c7f79e9a13cc3e17529002e1abfc077f95", size = 6315477, upload-time = "2026-02-19T14:14:11.314Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/41/0faca7b9d8868822b7177ae941f193f397479bb114d3a6396466167a3198/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a4182312ee8c26d8834e76375b2b5c766cb5d86d1dcf1515aa95e02704fcad83", size = 6862130, upload-time = "2026-02-19T14:13:22.375Z" },
+    { url = "https://files.pythonhosted.org/packages/34/7b/0f2bd4105a285f50f17af721e83a76ebc1186a9f07a2a29d6d576490a232/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8751696fe66fb1bdd429d98fde3a7f4b7dce9cb45f22095e28b96b690a422a2c", size = 6872292, upload-time = "2026-02-19T14:14:08.078Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/18/4380820d62d348afb1355814ea674788e28db7a73108a486e0b8898987de/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:40b73cd1137bb4fd9bf95ed5f87e48d960f7d556c30eeafde6996f908abbf183", size = 6636567, upload-time = "2026-02-19T14:14:01.464Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/57/29e5f89a558a6409d514bb2790c72442ec65804cbf1df6a870bbc0038673/pydantic_monty-0.0.7-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c1fa45a66757de5ea45c0809e15643bc2521959dbe2bc231694b22fa189decc9", size = 6693896, upload-time = "2026-02-19T14:14:34.128Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/26/5886d0f57ddb5ddf766ee2d0a4b3032267be9efd49a7c95c4d87a0b4b6a9/pydantic_monty-0.0.7-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:ffe8122db9f0f64619a66f4cee2f577245ba59158b7d651a2eae08df691d34f9", size = 6236867, upload-time = "2026-02-19T14:14:20.704Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/72/1bb8741baf84f217d92291b862f8a8cb64d735fe4be20be2827fdf787593/pydantic_monty-0.0.7-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:2122a5b6df53843329af01f6671300747449608d9cdf88ae5f9cf9977794e7a2", size = 6673504, upload-time = "2026-02-19T14:14:24.517Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/14/a4ff2bfe46350ffde4b5edc1f293b252cff90063f1f4cece49affe5a6462/pydantic_monty-0.0.7-cp314-cp314-win32.whl", hash = "sha256:bfbea2eddb9eef186326a6dfb27d79f8de434d7a3979f36f03b04216234a0275", size = 6131872, upload-time = "2026-02-19T14:13:14.437Z" },
+    { url = "https://files.pythonhosted.org/packages/60/1f/d873f280aae5cbd27021189843fbd5f77be4262a7654ef30445d984518ab/pydantic_monty-0.0.7-cp314-cp314-win_amd64.whl", hash = "sha256:1b750afceef78f5c5d3e3e3c32a8060b3a7e1b97e3a00ac2bede5bc5e87cde8f", size = 6687125, upload-time = "2026-02-19T14:13:04.317Z" },
 ]
 
 [[package]]
-name = "mcp"
-version = "1.0.0"
+name = "pydantic-settings"
+version = "2.13.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "anyio" },
-    { name = "httpx" },
-    { name = "httpx-sse" },
     { name = "pydantic" },
-    { name = "sse-starlette" },
-    { name = "starlette" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/97/de/a9ec0a1b6439f90ea59f89004bb2e7ec6890dfaeef809751d9e6577dca7e/mcp-1.0.0.tar.gz", hash = "sha256:dba51ce0b5c6a80e25576f606760c49a91ee90210fed805b530ca165d3bbc9b7", size = 82891 }
+sdist = { url = "https://files.pythonhosted.org/packages/96/a1/ae859ffac5a3338a66b74c5e29e244fd3a3cc483c89feaf9f56c39898d75/pydantic_settings-2.13.0.tar.gz", hash = "sha256:95d875514610e8595672800a5c40b073e99e4aae467fa7c8f9c263061ea2e1fe", size = 222450, upload-time = "2026-02-15T12:11:23.476Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/56/89/900c0c8445ec001d3725e475fc553b0feb2e8a51be018f3bb7de51e683db/mcp-1.0.0-py3-none-any.whl", hash = "sha256:bbe70ffa3341cd4da78b5eb504958355c68381fb29971471cea1e642a2af5b8a", size = 36361 },
+    { url = "https://files.pythonhosted.org/packages/b0/1a/dd1b9d7e627486cf8e7523d09b70010e05a4bc41414f4ae6ce184cf0afb6/pydantic_settings-2.13.0-py3-none-any.whl", hash = "sha256:d67b576fff39cd086b595441bf9c75d4193ca9c0ed643b90360694d0f1240246", size = 58429, upload-time = "2026-02-15T12:11:22.133Z" },
 ]
 
 [[package]]
-name = "mdurl"
-version = "0.1.2"
+name = "pydocket"
+version = "0.18.0"
 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 }
+dependencies = [
+    { name = "cloudpickle" },
+    { name = "croniter" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "fakeredis", extra = ["lua"] },
+    { 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/d2/da/5f76e42214c76402e1a2b4b59610211635c1068cab85509c78f1ca49a385/pydocket-0.18.0.tar.gz", hash = "sha256:cd5b6e7386331ca05a0163401f392b08b07e61342b5333c3ece6a7ca5435f984", size = 354637, upload-time = "2026-03-02T16:22:17.356Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979 },
+    { url = "https://files.pythonhosted.org/packages/04/57/ac0d47cd3550d859138647c2c4fbd53a2db05db8729433eaa6128e9964ba/pydocket-0.18.0-py3-none-any.whl", hash = "sha256:d995d9a3c88af0402fda640c18e1b51561041b9e3af1a92dce2fdc6c8f6c7090", size = 98848, upload-time = "2026-03-02T16:22:15.792Z" },
 ]
 
 [[package]]
-name = "packaging"
-version = "24.2"
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[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.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5c/5a/b46fa56bf322901eee5b0454a34343cdbdae202cd421775a8ee4e42fd519/pyjwt-2.11.0.tar.gz", hash = "sha256:35f95c1f0fbe5d5ba6e43f00271c275f7a1a4db1dab27bf708073b75318ea623", size = 98019, upload-time = "2026-01-30T19:59:55.694Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6f/01/c26ce75ba460d5cd503da9e13b21a33804d38c2165dec7b716d06b13010c/pyjwt-2.11.0-py3-none-any.whl", hash = "sha256:94a6bde30eb5c8e04fee991062b534071fd1439ef58d2adc9ccb823e7bcd0469", size = 28224, upload-time = "2026-01-30T19:59:54.539Z" },
+]
+
+[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/d0/63/68dbb6eb2de9cb10ee4c9c14a0148804425e13c4fb20d61cce69f53106da/packaging-24.2.tar.gz", hash = "sha256:c228a6dc5e932d346bc5739379109d49e8853dd8223571c7c5b55260edc0b97f", size = 163950 }
+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/88/ef/eb23f262cca3c0c4eb7ab1933c3b1f03d021f2c48f54763065b6f0e321be/packaging-24.2-py3-none-any.whl", hash = "sha256:09abb1bccd265c01f4a3aa3f7a7db064b36514d2cba19a2f694fe6150451a759", size = 65451 },
+    { 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 = "parso"
-version = "0.8.4"
+name = "pyreadline3"
+version = "3.5.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/66/94/68e2e17afaa9169cf6412ab0f28623903be73d1b32e208d9e8e541bb086d/parso-0.8.4.tar.gz", hash = "sha256:eb3a7b58240fb99099a345571deecc0f9540ea5f4dd2fe14c2a99d6b281ab92d", size = 400609 }
+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/c6/ac/dac4a63f978e4dcb3c6d3a78c4d8e0192a113d288502a1216950c41b1027/parso-0.8.4-py2.py3-none-any.whl", hash = "sha256:a418670a20291dacd2dddc80c377c5c3791378ee1e8d12bffc35420643d43f18", size = 103650 },
+    { 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 = "pathspec"
-version = "0.12.1"
+name = "pyrepl"
+version = "0.11.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043 }
+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/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191 },
+    { 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 = "pdbpp"
-version = "0.10.3"
+name = "pytest"
+version = "9.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "fancycompleter" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
     { name = "pygments" },
-    { name = "wmctrl" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/1f/a3/c4bd048256fd4b7d28767ca669c505e156f24d16355505c62e6fce3314df/pdbpp-0.10.3.tar.gz", hash = "sha256:d9e43f4fda388eeb365f2887f4e7b66ac09dce9b6236b76f63616530e2f669f5", size = 68116 }
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/93/ee/491e63a57fffa78b9de1c337b06c97d0cd0753e88c00571c7b011680332a/pdbpp-0.10.3-py2.py3-none-any.whl", hash = "sha256:79580568e33eb3d6f6b462b1187f53e10cd8e4538f7d31495c9181e2cf9665d1", size = 23961 },
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
 ]
 
 [[package]]
-name = "pexpect"
-version = "4.9.0"
+name = "pytest-asyncio"
+version = "1.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "ptyprocess" },
+    { 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/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450 }
+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/9e/c3/059298687310d527a58bb01f3b1965787ee3b40dce76752eda8b44e9a2c5/pexpect-4.9.0-py2.py3-none-any.whl", hash = "sha256:7236d1e080e4936be2dc3e326cec0af72acf9212a7e1d060210e70a47e253523", size = 63772 },
+    { 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 = "pickleshare"
-version = "0.7.5"
+name = "pytest-cov"
+version = "7.0.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d8/b6/df3c1c9b616e9c0edbc4fbab6ddd09df9535849c64ba51fcb6531c32d4d8/pickleshare-0.7.5.tar.gz", hash = "sha256:87683d47965c1da65cdacaf31c8441d12b8044cdec9aca500cd78fc2c683afca", size = 6161 }
+dependencies = [
+    { name = "coverage", extra = ["toml"] },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/f7/c933acc76f5208b3b00089573cf6a2bc26dc80a8aece8f52bb7d6b1855ca/pytest_cov-7.0.0.tar.gz", hash = "sha256:33c97eda2e049a0c5298e91f519302a1334c26ac65c1a483d6206fd458361af1", size = 54328, upload-time = "2025-09-09T10:57:02.113Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/41/220f49aaea88bc6fa6cba8d05ecf24676326156c23b991e80b3f2fc24c77/pickleshare-0.7.5-py2.py3-none-any.whl", hash = "sha256:9649af414d74d4df115d5d718f82acb59c9d418196b7b4290ed47a12ce62df56", size = 6877 },
+    { url = "https://files.pythonhosted.org/packages/ee/49/1377b49de7d0c1ce41292161ea0f721913fa8722c19fb9c1e3aa0367eecb/pytest_cov-7.0.0-py3-none-any.whl", hash = "sha256:3b8e9558b16cc1479da72058bdecf8073661c7f57f7d3c5f22a1c23507f2d861", size = 22424, upload-time = "2025-09-09T10:57:00.695Z" },
 ]
 
 [[package]]
-name = "pluggy"
-version = "1.5.0"
+name = "pytest-env"
+version = "1.3.2"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/96/2d/02d4312c973c6050a18b314a5ad0b3210edb65a906f868e31c111dede4a6/pluggy-1.5.0.tar.gz", hash = "sha256:2cffa88e94fdc978c4c574f15f9e59b7f4201d439195c3715ca9e2486f1d0cf1", size = 67955 }
+dependencies = [
+    { name = "pytest" },
+    { name = "python-dotenv" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/ad/dd32e4614fb68ad980c949fd4299f8c6a8d4874e24ec8d222c056efb4741/pytest_env-1.3.2.tar.gz", hash = "sha256:f091a2c6a8eb91befcae2b4c1bd2905a51f33bc1c6567707b7feed4e51b76b47", size = 12009, upload-time = "2026-02-11T22:09:49.168Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/88/5f/e351af9a41f866ac3f1fac4ca0613908d9a41741cfcf2228f4ad853b697d/pluggy-1.5.0-py3-none-any.whl", hash = "sha256:44e1ad92c8ca002de6377e165f3e0f1be63266ab4d554740532335b9d75ea669", size = 20556 },
+    { url = "https://files.pythonhosted.org/packages/e8/ad/d793670b26f4fb82e974dbff20d05782ebb23490b08987976cdc62d854bb/pytest_env-1.3.2-py3-none-any.whl", hash = "sha256:e8626b776a035112a8ad58fcc9e04926868c58f15225de484de7c8af4b4b526c", size = 7864, upload-time = "2026-02-11T22:09:47.775Z" },
 ]
 
 [[package]]
-name = "prompt-toolkit"
-version = "3.0.48"
+name = "pytest-flakefinder"
+version = "1.1.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "wcwidth" },
+    { name = "pytest" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/2d/4f/feb5e137aff82f7c7f3248267b97451da3644f6cdc218edfe549fb354127/prompt_toolkit-3.0.48.tar.gz", hash = "sha256:d6623ab0477a80df74e646bdbc93621143f5caf104206aa29294d53de1a03d90", size = 424684 }
+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/a9/6a/fd08d94654f7e67c52ca30523a178b3f8ccc4237fce4be90d39c938a831a/prompt_toolkit-3.0.48-py3-none-any.whl", hash = "sha256:f49a827f90062e411f1ce1f854f2aedb3c23353244f8108b89283587397ac10e", size = 386595 },
+    { 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 = "ptyprocess"
-version = "0.7.0"
+name = "pytest-httpx"
+version = "0.36.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 }
+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/22/a6/858897256d0deac81a172289110f31629fc4cee19b6f01283303e18c8db3/ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35", size = 13993 },
+    { 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 = "pure-eval"
-version = "0.2.3"
+name = "pytest-report"
+version = "0.2.1"
 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 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/8e/37/efad0257dc6e593a18957422533ff0f87ede7c9c6ea010a2177d738fb82f/pure_eval-0.2.3-py3-none-any.whl", hash = "sha256:1db8e35b67b3d218d818ae653e27f06c3aa420901fa7b081ca98cbedc874e0d0", size = 11842 },
+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 = "pydantic"
-version = "2.10.2"
+name = "pytest-retry"
+version = "1.7.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "annotated-types" },
-    { name = "pydantic-core" },
-    { name = "typing-extensions" },
+    { name = "pytest" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/41/86/a03390cb12cf64e2a8df07c267f3eb8d5035e0f9a04bb20fb79403d2a00e/pydantic-2.10.2.tar.gz", hash = "sha256:2bc2d7f17232e0841cbba4641e65ba1eb6fafb3a08de3a091ff3ce14a197c4fa", size = 785401 }
+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/d5/74/da832196702d0c56eb86b75bfa346db9238617e29b0b7ee3b8b4eccfe654/pydantic-2.10.2-py3-none-any.whl", hash = "sha256:cfb96e45951117c3024e6b67b25cdc33a3cb7b2fa62e239f7af1378358a1d99e", size = 456364 },
+    { 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 = "pydantic-core"
-version = "2.27.1"
+name = "pytest-timeout"
+version = "2.4.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "pytest" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a6/9f/7de1f19b6aea45aeb441838782d68352e71bfa98ee6fa048d5041991b33e/pydantic_core-2.27.1.tar.gz", hash = "sha256:62a763352879b84aa31058fc931884055fd75089cccbd9d58bb6afd01141b235", size = 412785 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/6e/ce/60fd96895c09738648c83f3f00f595c807cb6735c70d3306b548cc96dd49/pydantic_core-2.27.1-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:71a5e35c75c021aaf400ac048dacc855f000bdfed91614b4a726f7432f1f3d6a", size = 1897984 },
-    { url = "https://files.pythonhosted.org/packages/fd/b9/84623d6b6be98cc209b06687d9bca5a7b966ffed008d15225dd0d20cce2e/pydantic_core-2.27.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:f82d068a2d6ecfc6e054726080af69a6764a10015467d7d7b9f66d6ed5afa23b", size = 1807491 },
-    { url = "https://files.pythonhosted.org/packages/01/72/59a70165eabbc93b1111d42df9ca016a4aa109409db04304829377947028/pydantic_core-2.27.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:121ceb0e822f79163dd4699e4c54f5ad38b157084d97b34de8b232bcaad70278", size = 1831953 },
-    { url = "https://files.pythonhosted.org/packages/7c/0c/24841136476adafd26f94b45bb718a78cb0500bd7b4f8d667b67c29d7b0d/pydantic_core-2.27.1-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:4603137322c18eaf2e06a4495f426aa8d8388940f3c457e7548145011bb68e05", size = 1856071 },
-    { url = "https://files.pythonhosted.org/packages/53/5e/c32957a09cceb2af10d7642df45d1e3dbd8596061f700eac93b801de53c0/pydantic_core-2.27.1-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a33cd6ad9017bbeaa9ed78a2e0752c5e250eafb9534f308e7a5f7849b0b1bfb4", size = 2038439 },
-    { url = "https://files.pythonhosted.org/packages/e4/8f/979ab3eccd118b638cd6d8f980fea8794f45018255a36044dea40fe579d4/pydantic_core-2.27.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:15cc53a3179ba0fcefe1e3ae50beb2784dede4003ad2dfd24f81bba4b23a454f", size = 2787416 },
-    { url = "https://files.pythonhosted.org/packages/02/1d/00f2e4626565b3b6d3690dab4d4fe1a26edd6a20e53749eb21ca892ef2df/pydantic_core-2.27.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:45d9c5eb9273aa50999ad6adc6be5e0ecea7e09dbd0d31bd0c65a55a2592ca08", size = 2134548 },
-    { url = "https://files.pythonhosted.org/packages/9d/46/3112621204128b90898adc2e721a3cd6cf5626504178d6f32c33b5a43b79/pydantic_core-2.27.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8bf7b66ce12a2ac52d16f776b31d16d91033150266eb796967a7e4621707e4f6", size = 1989882 },
-    { url = "https://files.pythonhosted.org/packages/49/ec/557dd4ff5287ffffdf16a31d08d723de6762bb1b691879dc4423392309bc/pydantic_core-2.27.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:655d7dd86f26cb15ce8a431036f66ce0318648f8853d709b4167786ec2fa4807", size = 1995829 },
-    { url = "https://files.pythonhosted.org/packages/6e/b2/610dbeb74d8d43921a7234555e4c091cb050a2bdb8cfea86d07791ce01c5/pydantic_core-2.27.1-cp310-cp310-musllinux_1_1_armv7l.whl", hash = "sha256:5556470f1a2157031e676f776c2bc20acd34c1990ca5f7e56f1ebf938b9ab57c", size = 2091257 },
-    { url = "https://files.pythonhosted.org/packages/8c/7f/4bf8e9d26a9118521c80b229291fa9558a07cdd9a968ec2d5c1026f14fbc/pydantic_core-2.27.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:f69ed81ab24d5a3bd93861c8c4436f54afdf8e8cc421562b0c7504cf3be58206", size = 2143894 },
-    { url = "https://files.pythonhosted.org/packages/1f/1c/875ac7139c958f4390f23656fe696d1acc8edf45fb81e4831960f12cd6e4/pydantic_core-2.27.1-cp310-none-win32.whl", hash = "sha256:f5a823165e6d04ccea61a9f0576f345f8ce40ed533013580e087bd4d7442b52c", size = 1816081 },
-    { url = "https://files.pythonhosted.org/packages/d7/41/55a117acaeda25ceae51030b518032934f251b1dac3704a53781383e3491/pydantic_core-2.27.1-cp310-none-win_amd64.whl", hash = "sha256:57866a76e0b3823e0b56692d1a0bf722bffb324839bb5b7226a7dbd6c9a40b17", size = 1981109 },
-    { url = "https://files.pythonhosted.org/packages/27/39/46fe47f2ad4746b478ba89c561cafe4428e02b3573df882334bd2964f9cb/pydantic_core-2.27.1-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:ac3b20653bdbe160febbea8aa6c079d3df19310d50ac314911ed8cc4eb7f8cb8", size = 1895553 },
-    { url = "https://files.pythonhosted.org/packages/1c/00/0804e84a78b7fdb394fff4c4f429815a10e5e0993e6ae0e0b27dd20379ee/pydantic_core-2.27.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a5a8e19d7c707c4cadb8c18f5f60c843052ae83c20fa7d44f41594c644a1d330", size = 1807220 },
-    { url = "https://files.pythonhosted.org/packages/01/de/df51b3bac9820d38371f5a261020f505025df732ce566c2a2e7970b84c8c/pydantic_core-2.27.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7f7059ca8d64fea7f238994c97d91f75965216bcbe5f695bb44f354893f11d52", size = 1829727 },
-    { url = "https://files.pythonhosted.org/packages/5f/d9/c01d19da8f9e9fbdb2bf99f8358d145a312590374d0dc9dd8dbe484a9cde/pydantic_core-2.27.1-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bed0f8a0eeea9fb72937ba118f9db0cb7e90773462af7962d382445f3005e5a4", size = 1854282 },
-    { url = "https://files.pythonhosted.org/packages/5f/84/7db66eb12a0dc88c006abd6f3cbbf4232d26adfd827a28638c540d8f871d/pydantic_core-2.27.1-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a3cb37038123447cf0f3ea4c74751f6a9d7afef0eb71aa07bf5f652b5e6a132c", size = 2037437 },
-    { url = "https://files.pythonhosted.org/packages/34/ac/a2537958db8299fbabed81167d58cc1506049dba4163433524e06a7d9f4c/pydantic_core-2.27.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:84286494f6c5d05243456e04223d5a9417d7f443c3b76065e75001beb26f88de", size = 2780899 },
-    { url = "https://files.pythonhosted.org/packages/4a/c1/3e38cd777ef832c4fdce11d204592e135ddeedb6c6f525478a53d1c7d3e5/pydantic_core-2.27.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:acc07b2cfc5b835444b44a9956846b578d27beeacd4b52e45489e93276241025", size = 2135022 },
-    { url = "https://files.pythonhosted.org/packages/7a/69/b9952829f80fd555fe04340539d90e000a146f2a003d3fcd1e7077c06c71/pydantic_core-2.27.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:4fefee876e07a6e9aad7a8c8c9f85b0cdbe7df52b8a9552307b09050f7512c7e", size = 1987969 },
-    { url = "https://files.pythonhosted.org/packages/05/72/257b5824d7988af43460c4e22b63932ed651fe98804cc2793068de7ec554/pydantic_core-2.27.1-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:258c57abf1188926c774a4c94dd29237e77eda19462e5bb901d88adcab6af919", size = 1994625 },
-    { url = "https://files.pythonhosted.org/packages/73/c3/78ed6b7f3278a36589bcdd01243189ade7fc9b26852844938b4d7693895b/pydantic_core-2.27.1-cp311-cp311-musllinux_1_1_armv7l.whl", hash = "sha256:35c14ac45fcfdf7167ca76cc80b2001205a8d5d16d80524e13508371fb8cdd9c", size = 2090089 },
-    { url = "https://files.pythonhosted.org/packages/8d/c8/b4139b2f78579960353c4cd987e035108c93a78371bb19ba0dc1ac3b3220/pydantic_core-2.27.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:d1b26e1dff225c31897696cab7d4f0a315d4c0d9e8666dbffdb28216f3b17fdc", size = 2142496 },
-    { url = "https://files.pythonhosted.org/packages/3e/f8/171a03e97eb36c0b51981efe0f78460554a1d8311773d3d30e20c005164e/pydantic_core-2.27.1-cp311-none-win32.whl", hash = "sha256:2cdf7d86886bc6982354862204ae3b2f7f96f21a3eb0ba5ca0ac42c7b38598b9", size = 1811758 },
-    { url = "https://files.pythonhosted.org/packages/6a/fe/4e0e63c418c1c76e33974a05266e5633e879d4061f9533b1706a86f77d5b/pydantic_core-2.27.1-cp311-none-win_amd64.whl", hash = "sha256:3af385b0cee8df3746c3f406f38bcbfdc9041b5c2d5ce3e5fc6637256e60bbc5", size = 1980864 },
-    { url = "https://files.pythonhosted.org/packages/50/fc/93f7238a514c155a8ec02fc7ac6376177d449848115e4519b853820436c5/pydantic_core-2.27.1-cp311-none-win_arm64.whl", hash = "sha256:81f2ec23ddc1b476ff96563f2e8d723830b06dceae348ce02914a37cb4e74b89", size = 1864327 },
-    { url = "https://files.pythonhosted.org/packages/be/51/2e9b3788feb2aebff2aa9dfbf060ec739b38c05c46847601134cc1fed2ea/pydantic_core-2.27.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:9cbd94fc661d2bab2bc702cddd2d3370bbdcc4cd0f8f57488a81bcce90c7a54f", size = 1895239 },
-    { url = "https://files.pythonhosted.org/packages/7b/9e/f8063952e4a7d0127f5d1181addef9377505dcce3be224263b25c4f0bfd9/pydantic_core-2.27.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:5f8c4718cd44ec1580e180cb739713ecda2bdee1341084c1467802a417fe0f02", size = 1805070 },
-    { url = "https://files.pythonhosted.org/packages/2c/9d/e1d6c4561d262b52e41b17a7ef8301e2ba80b61e32e94520271029feb5d8/pydantic_core-2.27.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:15aae984e46de8d376df515f00450d1522077254ef6b7ce189b38ecee7c9677c", size = 1828096 },
-    { url = "https://files.pythonhosted.org/packages/be/65/80ff46de4266560baa4332ae3181fffc4488ea7d37282da1a62d10ab89a4/pydantic_core-2.27.1-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:1ba5e3963344ff25fc8c40da90f44b0afca8cfd89d12964feb79ac1411a260ac", size = 1857708 },
-    { url = "https://files.pythonhosted.org/packages/d5/ca/3370074ad758b04d9562b12ecdb088597f4d9d13893a48a583fb47682cdf/pydantic_core-2.27.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:992cea5f4f3b29d6b4f7f1726ed8ee46c8331c6b4eed6db5b40134c6fe1768bb", size = 2037751 },
-    { url = "https://files.pythonhosted.org/packages/b1/e2/4ab72d93367194317b99d051947c071aef6e3eb95f7553eaa4208ecf9ba4/pydantic_core-2.27.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0325336f348dbee6550d129b1627cb8f5351a9dc91aad141ffb96d4937bd9529", size = 2733863 },
-    { url = "https://files.pythonhosted.org/packages/8a/c6/8ae0831bf77f356bb73127ce5a95fe115b10f820ea480abbd72d3cc7ccf3/pydantic_core-2.27.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7597c07fbd11515f654d6ece3d0e4e5093edc30a436c63142d9a4b8e22f19c35", size = 2161161 },
-    { url = "https://files.pythonhosted.org/packages/f1/f4/b2fe73241da2429400fc27ddeaa43e35562f96cf5b67499b2de52b528cad/pydantic_core-2.27.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:3bbd5d8cc692616d5ef6fbbbd50dbec142c7e6ad9beb66b78a96e9c16729b089", size = 1993294 },
-    { url = "https://files.pythonhosted.org/packages/77/29/4bb008823a7f4cc05828198153f9753b3bd4c104d93b8e0b1bfe4e187540/pydantic_core-2.27.1-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:dc61505e73298a84a2f317255fcc72b710b72980f3a1f670447a21efc88f8381", size = 2001468 },
-    { url = "https://files.pythonhosted.org/packages/f2/a9/0eaceeba41b9fad851a4107e0cf999a34ae8f0d0d1f829e2574f3d8897b0/pydantic_core-2.27.1-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:e1f735dc43da318cad19b4173dd1ffce1d84aafd6c9b782b3abc04a0d5a6f5bb", size = 2091413 },
-    { url = "https://files.pythonhosted.org/packages/d8/36/eb8697729725bc610fd73940f0d860d791dc2ad557faaefcbb3edbd2b349/pydantic_core-2.27.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:f4e5658dbffe8843a0f12366a4c2d1c316dbe09bb4dfbdc9d2d9cd6031de8aae", size = 2154735 },
-    { url = "https://files.pythonhosted.org/packages/52/e5/4f0fbd5c5995cc70d3afed1b5c754055bb67908f55b5cb8000f7112749bf/pydantic_core-2.27.1-cp312-none-win32.whl", hash = "sha256:672ebbe820bb37988c4d136eca2652ee114992d5d41c7e4858cdd90ea94ffe5c", size = 1833633 },
-    { url = "https://files.pythonhosted.org/packages/ee/f2/c61486eee27cae5ac781305658779b4a6b45f9cc9d02c90cb21b940e82cc/pydantic_core-2.27.1-cp312-none-win_amd64.whl", hash = "sha256:66ff044fd0bb1768688aecbe28b6190f6e799349221fb0de0e6f4048eca14c16", size = 1986973 },
-    { url = "https://files.pythonhosted.org/packages/df/a6/e3f12ff25f250b02f7c51be89a294689d175ac76e1096c32bf278f29ca1e/pydantic_core-2.27.1-cp312-none-win_arm64.whl", hash = "sha256:9a3b0793b1bbfd4146304e23d90045f2a9b5fd5823aa682665fbdaf2a6c28f3e", size = 1883215 },
-    { url = "https://files.pythonhosted.org/packages/0f/d6/91cb99a3c59d7b072bded9959fbeab0a9613d5a4935773c0801f1764c156/pydantic_core-2.27.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:f216dbce0e60e4d03e0c4353c7023b202d95cbaeff12e5fd2e82ea0a66905073", size = 1895033 },
-    { url = "https://files.pythonhosted.org/packages/07/42/d35033f81a28b27dedcade9e967e8a40981a765795c9ebae2045bcef05d3/pydantic_core-2.27.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a2e02889071850bbfd36b56fd6bc98945e23670773bc7a76657e90e6b6603c08", size = 1807542 },
-    { url = "https://files.pythonhosted.org/packages/41/c2/491b59e222ec7e72236e512108ecad532c7f4391a14e971c963f624f7569/pydantic_core-2.27.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42b0e23f119b2b456d07ca91b307ae167cc3f6c846a7b169fca5326e32fdc6cf", size = 1827854 },
-    { url = "https://files.pythonhosted.org/packages/e3/f3/363652651779113189cefdbbb619b7b07b7a67ebb6840325117cc8cc3460/pydantic_core-2.27.1-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:764be71193f87d460a03f1f7385a82e226639732214b402f9aa61f0d025f0737", size = 1857389 },
-    { url = "https://files.pythonhosted.org/packages/5f/97/be804aed6b479af5a945daec7538d8bf358d668bdadde4c7888a2506bdfb/pydantic_core-2.27.1-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1c00666a3bd2f84920a4e94434f5974d7bbc57e461318d6bb34ce9cdbbc1f6b2", size = 2037934 },
-    { url = "https://files.pythonhosted.org/packages/42/01/295f0bd4abf58902917e342ddfe5f76cf66ffabfc57c2e23c7681a1a1197/pydantic_core-2.27.1-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3ccaa88b24eebc0f849ce0a4d09e8a408ec5a94afff395eb69baf868f5183107", size = 2735176 },
-    { url = "https://files.pythonhosted.org/packages/9d/a0/cd8e9c940ead89cc37812a1a9f310fef59ba2f0b22b4e417d84ab09fa970/pydantic_core-2.27.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c65af9088ac534313e1963443d0ec360bb2b9cba6c2909478d22c2e363d98a51", size = 2160720 },
-    { url = "https://files.pythonhosted.org/packages/73/ae/9d0980e286627e0aeca4c352a60bd760331622c12d576e5ea4441ac7e15e/pydantic_core-2.27.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:206b5cf6f0c513baffaeae7bd817717140770c74528f3e4c3e1cec7871ddd61a", size = 1992972 },
-    { url = "https://files.pythonhosted.org/packages/bf/ba/ae4480bc0292d54b85cfb954e9d6bd226982949f8316338677d56541b85f/pydantic_core-2.27.1-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:062f60e512fc7fff8b8a9d680ff0ddaaef0193dba9fa83e679c0c5f5fbd018bc", size = 2001477 },
-    { url = "https://files.pythonhosted.org/packages/55/b7/e26adf48c2f943092ce54ae14c3c08d0d221ad34ce80b18a50de8ed2cba8/pydantic_core-2.27.1-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:a0697803ed7d4af5e4c1adf1670af078f8fcab7a86350e969f454daf598c4960", size = 2091186 },
-    { url = "https://files.pythonhosted.org/packages/ba/cc/8491fff5b608b3862eb36e7d29d36a1af1c945463ca4c5040bf46cc73f40/pydantic_core-2.27.1-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:58ca98a950171f3151c603aeea9303ef6c235f692fe555e883591103da709b23", size = 2154429 },
-    { url = "https://files.pythonhosted.org/packages/78/d8/c080592d80edd3441ab7f88f865f51dae94a157fc64283c680e9f32cf6da/pydantic_core-2.27.1-cp313-none-win32.whl", hash = "sha256:8065914ff79f7eab1599bd80406681f0ad08f8e47c880f17b416c9f8f7a26d05", size = 1833713 },
-    { url = "https://files.pythonhosted.org/packages/83/84/5ab82a9ee2538ac95a66e51f6838d6aba6e0a03a42aa185ad2fe404a4e8f/pydantic_core-2.27.1-cp313-none-win_amd64.whl", hash = "sha256:ba630d5e3db74c79300d9a5bdaaf6200172b107f263c98a0539eeecb857b2337", size = 1987897 },
-    { url = "https://files.pythonhosted.org/packages/df/c3/b15fb833926d91d982fde29c0624c9f225da743c7af801dace0d4e187e71/pydantic_core-2.27.1-cp313-none-win_arm64.whl", hash = "sha256:45cf8588c066860b623cd11c4ba687f8d7175d5f7ef65f7129df8a394c502de5", size = 1882983 },
-    { url = "https://files.pythonhosted.org/packages/7c/60/e5eb2d462595ba1f622edbe7b1d19531e510c05c405f0b87c80c1e89d5b1/pydantic_core-2.27.1-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:3fa80ac2bd5856580e242dbc202db873c60a01b20309c8319b5c5986fbe53ce6", size = 1894016 },
-    { url = "https://files.pythonhosted.org/packages/61/20/da7059855225038c1c4326a840908cc7ca72c7198cb6addb8b92ec81c1d6/pydantic_core-2.27.1-pp310-pypy310_pp73-macosx_11_0_arm64.whl", hash = "sha256:d950caa237bb1954f1b8c9227b5065ba6875ac9771bb8ec790d956a699b78676", size = 1771648 },
-    { url = "https://files.pythonhosted.org/packages/8f/fc/5485cf0b0bb38da31d1d292160a4d123b5977841ddc1122c671a30b76cfd/pydantic_core-2.27.1-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0e4216e64d203e39c62df627aa882f02a2438d18a5f21d7f721621f7a5d3611d", size = 1826929 },
-    { url = "https://files.pythonhosted.org/packages/a1/ff/fb1284a210e13a5f34c639efc54d51da136074ffbe25ec0c279cf9fbb1c4/pydantic_core-2.27.1-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:02a3d637bd387c41d46b002f0e49c52642281edacd2740e5a42f7017feea3f2c", size = 1980591 },
-    { url = "https://files.pythonhosted.org/packages/f1/14/77c1887a182d05af74f6aeac7b740da3a74155d3093ccc7ee10b900cc6b5/pydantic_core-2.27.1-pp310-pypy310_pp73-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:161c27ccce13b6b0c8689418da3885d3220ed2eae2ea5e9b2f7f3d48f1d52c27", size = 1981326 },
-    { url = "https://files.pythonhosted.org/packages/06/aa/6f1b2747f811a9c66b5ef39d7f02fbb200479784c75e98290d70004b1253/pydantic_core-2.27.1-pp310-pypy310_pp73-musllinux_1_1_aarch64.whl", hash = "sha256:19910754e4cc9c63bc1c7f6d73aa1cfee82f42007e407c0f413695c2f7ed777f", size = 1989205 },
-    { url = "https://files.pythonhosted.org/packages/7a/d2/8ce2b074d6835f3c88d85f6d8a399790043e9fdb3d0e43455e72d19df8cc/pydantic_core-2.27.1-pp310-pypy310_pp73-musllinux_1_1_armv7l.whl", hash = "sha256:e173486019cc283dc9778315fa29a363579372fe67045e971e89b6365cc035ed", size = 2079616 },
-    { url = "https://files.pythonhosted.org/packages/65/71/af01033d4e58484c3db1e5d13e751ba5e3d6b87cc3368533df4c50932c8b/pydantic_core-2.27.1-pp310-pypy310_pp73-musllinux_1_1_x86_64.whl", hash = "sha256:af52d26579b308921b73b956153066481f064875140ccd1dfd4e77db89dbb12f", size = 2133265 },
-    { url = "https://files.pythonhosted.org/packages/33/72/f881b5e18fbb67cf2fb4ab253660de3c6899dbb2dba409d0b757e3559e3d/pydantic_core-2.27.1-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:981fb88516bd1ae8b0cbbd2034678a39dedc98752f264ac9bc5839d3923fa04c", size = 2001864 },
+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 = "pydantic-settings"
-version = "2.6.1"
+name = "pytest-xdist"
+version = "3.8.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "pydantic" },
-    { name = "python-dotenv" },
+    { name = "execnet" },
+    { name = "pytest" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b5/d4/9dfbe238f45ad8b168f5c96ee49a3df0598ce18a0795a983b419949ce65b/pydantic_settings-2.6.1.tar.gz", hash = "sha256:e0f92546d8a9923cb8941689abf85d6601a8c19a23e97a34b2964a2e3f813ca0", size = 75646 }
+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/5e/f9/ff95fd7d760af42f647ea87f9b8a383d891cdb5e5dbd4613edaeb094252a/pydantic_settings-2.6.1-py3-none-any.whl", hash = "sha256:7fb0637c786a558d3103436278a7c4f1cfd29ba8973238a50c5bb9a55387da87", size = 28595 },
+    { 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 = "pygments"
-version = "2.18.0"
+name = "python-dateutil"
+version = "2.9.0.post0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/8e/62/8336eff65bcbc8e4cb5d05b55faf041285951b6e80f33e2bff2024788f31/pygments-2.18.0.tar.gz", hash = "sha256:786ff802f32e91311bff3889f6e9a86e81505fe99f2735bb6d60ae0c5004f199", size = 4891905 }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f7/3f/01c8b82017c199075f8f788d0d906b9ffbbc5a47dc9918a945e13d5a2bda/pygments-2.18.0-py3-none-any.whl", hash = "sha256:b8e6aca0523f3ab76fee51799c488e38782ac06eafcf95e7ba832985c8e7b13a", size = 1205513 },
+    { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
 ]
 
 [[package]]
-name = "pyperclip"
-version = "1.9.0"
+name = "python-dotenv"
+version = "1.2.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/30/23/2f0a3efc4d6a32f3b63cdff36cd398d9701d26cda58e3ab97ac79fb5e60d/pyperclip-1.9.0.tar.gz", hash = "sha256:b7de0142ddc81bfc5c7507eea19da920b92252b548b96186caf94a5e2527d310", size = 20961 }
+sdist = { url = "https://files.pythonhosted.org/packages/f0/26/19cadc79a718c5edbec86fd4919a6b6d3f681039a2f6d66d14be94e75fb9/python_dotenv-1.2.1.tar.gz", hash = "sha256:42667e897e16ab0d66954af0e60a9caa94f0fd4ecf3aaf6d2d260eec1aa36ad6", size = 44221, upload-time = "2025-10-26T15:12:10.434Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/1b/a298b06749107c305e1fe0f814c6c74aea7b2f1e10989cb30f544a1b3253/python_dotenv-1.2.1-py3-none-any.whl", hash = "sha256:b81ee9561e9ca4004139c6cbba3a238c32b03e4894671e181b671e8cb8425d61", size = 21230, upload-time = "2025-10-26T15:12:09.109Z" },
+]
 
 [[package]]
-name = "pyreadline"
-version = "2.1"
+name = "python-json-logger"
+version = "4.0.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/bc/7c/d724ef1ec3ab2125f38a1d53285745445ec4a8f19b9bb0761b4064316679/pyreadline-2.1.zip", hash = "sha256:4530592fc2e85b25b1a9f79664433da09237c1a270e4d78ea5aa3a2c7229e2d1", size = 109189 }
+sdist = { url = "https://files.pythonhosted.org/packages/29/bf/eca6a3d43db1dae7070f70e160ab20b807627ba953663ba07928cdd3dc58/python_json_logger-4.0.0.tar.gz", hash = "sha256:f58e68eb46e1faed27e0f574a55a0455eecd7b8a5b88b85a784519ba3cff047f", size = 17683, upload-time = "2025-10-06T04:15:18.984Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/e5/fecf13f06e5e5f67e8837d777d1bc43fac0ed2b77a676804df5c34744727/python_json_logger-4.0.0-py3-none-any.whl", hash = "sha256:af09c9daf6a813aa4cc7180395f50f2a9e5fa056034c9953aec92e381c5ba1e2", size = 15548, upload-time = "2025-10-06T04:15:17.553Z" },
+]
 
 [[package]]
-name = "pyrepl"
-version = "0.9.0"
+name = "python-multipart"
+version = "0.0.22"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/05/1b/ea40363be0056080454cdbabe880773c3c5bd66d7b13f0c8b8b8c8da1e0c/pyrepl-0.9.0.tar.gz", hash = "sha256:292570f34b5502e871bbb966d639474f2b57fbfcd3373c2d6a2f3d56e681a775", size = 48744 }
+sdist = { url = "https://files.pythonhosted.org/packages/94/01/979e98d542a70714b0cb2b6728ed0b7c46792b695e3eaec3e20711271ca3/python_multipart-0.0.22.tar.gz", hash = "sha256:7340bef99a7e0032613f56dc36027b959fd3b30a787ed62d310e951f7c3a3a58", size = 37612, upload-time = "2026-01-25T10:15:56.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1b/d0/397f9626e711ff749a95d96b7af99b9c566a9bb5129b8e4c10fc4d100304/python_multipart-0.0.22-py3-none-any.whl", hash = "sha256:2b2cd894c83d21bf49d702499531c7bafd057d730c201782048f7945d82de155", size = 24579, upload-time = "2026-01-25T10:15:54.811Z" },
+]
 
 [[package]]
-name = "pytest"
-version = "8.3.3"
+name = "pytz"
+version = "2025.2"
 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 = "tomli", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/8b/6c/62bbd536103af674e227c41a8f3dcd022d591f6eed5facb5a0f31ee33bbc/pytest-8.3.3.tar.gz", hash = "sha256:70b98107bd648308a7952b06e6ca9a50bc660be218d53c257cc1fc94fda10181", size = 1442487 }
+sdist = { url = "https://files.pythonhosted.org/packages/f8/bf/abbd3cdfb8fbc7fb3d4d38d320f2441b1e7cbe29be4f23797b4a2b5d8aac/pytz-2025.2.tar.gz", hash = "sha256:360b9e3dbb49a209c21ad61809c7fb453643e048b38924c765813546746e81c3", size = 320884, upload-time = "2025-03-25T02:25:00.538Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl", hash = "sha256:a6853c7375b2663155079443d2e45de913a911a11d669df02a50814944db57b2", size = 342341 },
+    { url = "https://files.pythonhosted.org/packages/81/c4/34e93fe5f5429d7570ec1fa436f1986fb1f00c3e0f43a589fe2bbcd22c3f/pytz-2025.2-py2.py3-none-any.whl", hash = "sha256:5ddf76296dd8c44c26eb8f4b6f35488f3ccbf6fbbd7adee0b7262d43f0ec2f00", size = 509225, upload-time = "2025-03-25T02:24:58.468Z" },
 ]
 
 [[package]]
-name = "pytest-asyncio"
-version = "0.24.0"
+name = "pywin32"
+version = "311"
 source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pytest" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/52/6d/c6cf50ce320cf8611df7a1254d86233b3df7cc07f9b5f5cbcb82e08aa534/pytest_asyncio-0.24.0.tar.gz", hash = "sha256:d081d828e576d85f875399194281e92bf8a68d60d72d1a2faf2feddb6c46b276", size = 49855 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/96/31/6607dab48616902f76885dfcf62c08d929796fc3b2d2318faf9fd54dbed9/pytest_asyncio-0.24.0-py3-none-any.whl", hash = "sha256:a811296ed596b69bf0b6f3dc40f83bcaf341b155a269052d82efa2b25ac7037b", size = 18024 },
+    { 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 = "pytest-xdist"
-version = "3.6.1"
+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.2.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "execnet" },
-    { name = "pytest" },
+    { name = "async-timeout", marker = "python_full_version < '3.11.3'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/41/c4/3c310a19bc1f1e9ef50075582652673ef2bfc8cd62afef9585683821902f/pytest_xdist-3.6.1.tar.gz", hash = "sha256:ead156a4db231eec769737f57668ef58a2084a34b2e55c4a8fa20d861107300d", size = 84060 }
+sdist = { url = "https://files.pythonhosted.org/packages/9f/32/6fac13a11e73e1bc67a2ae821a72bfe4c2d8c4c48f0267e4a952be0f1bae/redis-7.2.0.tar.gz", hash = "sha256:4dd5bf4bd4ae80510267f14185a15cba2a38666b941aff68cccf0256b51c1f26", size = 4901247, upload-time = "2026-02-16T17:16:22.797Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6d/82/1d96bf03ee4c0fdc3c0cbe61470070e659ca78dc0086fb88b66c185e2449/pytest_xdist-3.6.1-py3-none-any.whl", hash = "sha256:9ed4adfb68a016610848639bb7e02c9352d5d9f03d04809919e2dafc3be4cca7", size = 46108 },
+    { url = "https://files.pythonhosted.org/packages/86/cf/f6180b67f99688d83e15c84c5beda831d1d341e95872d224f87ccafafe61/redis-7.2.0-py3-none-any.whl", hash = "sha256:01f591f8598e483f1842d429e8ae3a820804566f1c73dca1b80e23af9fba0497", size = 394898, upload-time = "2026-02-16T17:16:20.693Z" },
 ]
 
 [[package]]
-name = "python-dotenv"
-version = "1.0.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/bc/57/e84d88dfe0aec03b7a2d4327012c1627ab5f03652216c63d49846d7a6c58/python-dotenv-1.0.1.tar.gz", hash = "sha256:e324ee90a023d808f1959c46bcbc04446a10ced277783dc6ee09987c37ec10ca", size = 39115 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/6a/3e/b68c118422ec867fa7ab88444e1274aa40681c606d59ac27de5a5588f082/python_dotenv-1.0.1-py3-none-any.whl", hash = "sha256:f7b63ef50f1b690dddf550d03497b66d609393b40b564ed0d674909a68ebf16a", size = 19863 },
-]
-
-[[package]]
-name = "regex"
-version = "2024.11.6"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/8e/5f/bd69653fbfb76cf8604468d3b4ec4c403197144c7bfe0e6a5fc9e02a07cb/regex-2024.11.6.tar.gz", hash = "sha256:7ab159b063c52a0333c884e4679f8d7a85112ee3078fe3d9004b2dd875585519", size = 399494 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/95/3c/4651f6b130c6842a8f3df82461a8950f923925db8b6961063e82744bddcc/regex-2024.11.6-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:ff590880083d60acc0433f9c3f713c51f7ac6ebb9adf889c79a261ecf541aa91", size = 482674 },
-    { url = "https://files.pythonhosted.org/packages/15/51/9f35d12da8434b489c7b7bffc205c474a0a9432a889457026e9bc06a297a/regex-2024.11.6-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:658f90550f38270639e83ce492f27d2c8d2cd63805c65a13a14d36ca126753f0", size = 287684 },
-    { url = "https://files.pythonhosted.org/packages/bd/18/b731f5510d1b8fb63c6b6d3484bfa9a59b84cc578ac8b5172970e05ae07c/regex-2024.11.6-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:164d8b7b3b4bcb2068b97428060b2a53be050085ef94eca7f240e7947f1b080e", size = 284589 },
-    { url = "https://files.pythonhosted.org/packages/78/a2/6dd36e16341ab95e4c6073426561b9bfdeb1a9c9b63ab1b579c2e96cb105/regex-2024.11.6-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d3660c82f209655a06b587d55e723f0b813d3a7db2e32e5e7dc64ac2a9e86fde", size = 782511 },
-    { url = "https://files.pythonhosted.org/packages/1b/2b/323e72d5d2fd8de0d9baa443e1ed70363ed7e7b2fb526f5950c5cb99c364/regex-2024.11.6-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d22326fcdef5e08c154280b71163ced384b428343ae16a5ab2b3354aed12436e", size = 821149 },
-    { url = "https://files.pythonhosted.org/packages/90/30/63373b9ea468fbef8a907fd273e5c329b8c9535fee36fc8dba5fecac475d/regex-2024.11.6-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f1ac758ef6aebfc8943560194e9fd0fa18bcb34d89fd8bd2af18183afd8da3a2", size = 809707 },
-    { url = "https://files.pythonhosted.org/packages/f2/98/26d3830875b53071f1f0ae6d547f1d98e964dd29ad35cbf94439120bb67a/regex-2024.11.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:997d6a487ff00807ba810e0f8332c18b4eb8d29463cfb7c820dc4b6e7562d0cf", size = 781702 },
-    { url = "https://files.pythonhosted.org/packages/87/55/eb2a068334274db86208ab9d5599ffa63631b9f0f67ed70ea7c82a69bbc8/regex-2024.11.6-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:02a02d2bb04fec86ad61f3ea7f49c015a0681bf76abb9857f945d26159d2968c", size = 771976 },
-    { url = "https://files.pythonhosted.org/packages/74/c0/be707bcfe98254d8f9d2cff55d216e946f4ea48ad2fd8cf1428f8c5332ba/regex-2024.11.6-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:f02f93b92358ee3f78660e43b4b0091229260c5d5c408d17d60bf26b6c900e86", size = 697397 },
-    { url = "https://files.pythonhosted.org/packages/49/dc/bb45572ceb49e0f6509f7596e4ba7031f6819ecb26bc7610979af5a77f45/regex-2024.11.6-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:06eb1be98df10e81ebaded73fcd51989dcf534e3c753466e4b60c4697a003b67", size = 768726 },
-    { url = "https://files.pythonhosted.org/packages/5a/db/f43fd75dc4c0c2d96d0881967897926942e935d700863666f3c844a72ce6/regex-2024.11.6-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:040df6fe1a5504eb0f04f048e6d09cd7c7110fef851d7c567a6b6e09942feb7d", size = 775098 },
-    { url = "https://files.pythonhosted.org/packages/99/d7/f94154db29ab5a89d69ff893159b19ada89e76b915c1293e98603d39838c/regex-2024.11.6-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:fdabbfc59f2c6edba2a6622c647b716e34e8e3867e0ab975412c5c2f79b82da2", size = 839325 },
-    { url = "https://files.pythonhosted.org/packages/f7/17/3cbfab1f23356fbbf07708220ab438a7efa1e0f34195bf857433f79f1788/regex-2024.11.6-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:8447d2d39b5abe381419319f942de20b7ecd60ce86f16a23b0698f22e1b70008", size = 843277 },
-    { url = "https://files.pythonhosted.org/packages/7e/f2/48b393b51900456155de3ad001900f94298965e1cad1c772b87f9cfea011/regex-2024.11.6-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:da8f5fc57d1933de22a9e23eec290a0d8a5927a5370d24bda9a6abe50683fe62", size = 773197 },
-    { url = "https://files.pythonhosted.org/packages/45/3f/ef9589aba93e084cd3f8471fded352826dcae8489b650d0b9b27bc5bba8a/regex-2024.11.6-cp310-cp310-win32.whl", hash = "sha256:b489578720afb782f6ccf2840920f3a32e31ba28a4b162e13900c3e6bd3f930e", size = 261714 },
-    { url = "https://files.pythonhosted.org/packages/42/7e/5f1b92c8468290c465fd50c5318da64319133231415a8aa6ea5ab995a815/regex-2024.11.6-cp310-cp310-win_amd64.whl", hash = "sha256:5071b2093e793357c9d8b2929dfc13ac5f0a6c650559503bb81189d0a3814519", size = 274042 },
-    { url = "https://files.pythonhosted.org/packages/58/58/7e4d9493a66c88a7da6d205768119f51af0f684fe7be7bac8328e217a52c/regex-2024.11.6-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5478c6962ad548b54a591778e93cd7c456a7a29f8eca9c49e4f9a806dcc5d638", size = 482669 },
-    { url = "https://files.pythonhosted.org/packages/34/4c/8f8e631fcdc2ff978609eaeef1d6994bf2f028b59d9ac67640ed051f1218/regex-2024.11.6-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:2c89a8cc122b25ce6945f0423dc1352cb9593c68abd19223eebbd4e56612c5b7", size = 287684 },
-    { url = "https://files.pythonhosted.org/packages/c5/1b/f0e4d13e6adf866ce9b069e191f303a30ab1277e037037a365c3aad5cc9c/regex-2024.11.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:94d87b689cdd831934fa3ce16cc15cd65748e6d689f5d2b8f4f4df2065c9fa20", size = 284589 },
-    { url = "https://files.pythonhosted.org/packages/25/4d/ab21047f446693887f25510887e6820b93f791992994f6498b0318904d4a/regex-2024.11.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1062b39a0a2b75a9c694f7a08e7183a80c63c0d62b301418ffd9c35f55aaa114", size = 792121 },
-    { url = "https://files.pythonhosted.org/packages/45/ee/c867e15cd894985cb32b731d89576c41a4642a57850c162490ea34b78c3b/regex-2024.11.6-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:167ed4852351d8a750da48712c3930b031f6efdaa0f22fa1933716bfcd6bf4a3", size = 831275 },
-    { url = "https://files.pythonhosted.org/packages/b3/12/b0f480726cf1c60f6536fa5e1c95275a77624f3ac8fdccf79e6727499e28/regex-2024.11.6-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2d548dafee61f06ebdb584080621f3e0c23fff312f0de1afc776e2a2ba99a74f", size = 818257 },
-    { url = "https://files.pythonhosted.org/packages/bf/ce/0d0e61429f603bac433910d99ef1a02ce45a8967ffbe3cbee48599e62d88/regex-2024.11.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f2a19f302cd1ce5dd01a9099aaa19cae6173306d1302a43b627f62e21cf18ac0", size = 792727 },
-    { url = "https://files.pythonhosted.org/packages/e4/c1/243c83c53d4a419c1556f43777ccb552bccdf79d08fda3980e4e77dd9137/regex-2024.11.6-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:bec9931dfb61ddd8ef2ebc05646293812cb6b16b60cf7c9511a832b6f1854b55", size = 780667 },
-    { url = "https://files.pythonhosted.org/packages/c5/f4/75eb0dd4ce4b37f04928987f1d22547ddaf6c4bae697623c1b05da67a8aa/regex-2024.11.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:9714398225f299aa85267fd222f7142fcb5c769e73d7733344efc46f2ef5cf89", size = 776963 },
-    { url = "https://files.pythonhosted.org/packages/16/5d/95c568574e630e141a69ff8a254c2f188b4398e813c40d49228c9bbd9875/regex-2024.11.6-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:202eb32e89f60fc147a41e55cb086db2a3f8cb82f9a9a88440dcfc5d37faae8d", size = 784700 },
-    { url = "https://files.pythonhosted.org/packages/8e/b5/f8495c7917f15cc6fee1e7f395e324ec3e00ab3c665a7dc9d27562fd5290/regex-2024.11.6-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:4181b814e56078e9b00427ca358ec44333765f5ca1b45597ec7446d3a1ef6e34", size = 848592 },
-    { url = "https://files.pythonhosted.org/packages/1c/80/6dd7118e8cb212c3c60b191b932dc57db93fb2e36fb9e0e92f72a5909af9/regex-2024.11.6-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:068376da5a7e4da51968ce4c122a7cd31afaaec4fccc7856c92f63876e57b51d", size = 852929 },
-    { url = "https://files.pythonhosted.org/packages/11/9b/5a05d2040297d2d254baf95eeeb6df83554e5e1df03bc1a6687fc4ba1f66/regex-2024.11.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ac10f2c4184420d881a3475fb2c6f4d95d53a8d50209a2500723d831036f7c45", size = 781213 },
-    { url = "https://files.pythonhosted.org/packages/26/b7/b14e2440156ab39e0177506c08c18accaf2b8932e39fb092074de733d868/regex-2024.11.6-cp311-cp311-win32.whl", hash = "sha256:c36f9b6f5f8649bb251a5f3f66564438977b7ef8386a52460ae77e6070d309d9", size = 261734 },
-    { url = "https://files.pythonhosted.org/packages/80/32/763a6cc01d21fb3819227a1cc3f60fd251c13c37c27a73b8ff4315433a8e/regex-2024.11.6-cp311-cp311-win_amd64.whl", hash = "sha256:02e28184be537f0e75c1f9b2f8847dc51e08e6e171c6bde130b2687e0c33cf60", size = 274052 },
-    { url = "https://files.pythonhosted.org/packages/ba/30/9a87ce8336b172cc232a0db89a3af97929d06c11ceaa19d97d84fa90a8f8/regex-2024.11.6-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:52fb28f528778f184f870b7cf8f225f5eef0a8f6e3778529bdd40c7b3920796a", size = 483781 },
-    { url = "https://files.pythonhosted.org/packages/01/e8/00008ad4ff4be8b1844786ba6636035f7ef926db5686e4c0f98093612add/regex-2024.11.6-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:fdd6028445d2460f33136c55eeb1f601ab06d74cb3347132e1c24250187500d9", size = 288455 },
-    { url = "https://files.pythonhosted.org/packages/60/85/cebcc0aff603ea0a201667b203f13ba75d9fc8668fab917ac5b2de3967bc/regex-2024.11.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:805e6b60c54bf766b251e94526ebad60b7de0c70f70a4e6210ee2891acb70bf2", size = 284759 },
-    { url = "https://files.pythonhosted.org/packages/94/2b/701a4b0585cb05472a4da28ee28fdfe155f3638f5e1ec92306d924e5faf0/regex-2024.11.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b85c2530be953a890eaffde05485238f07029600e8f098cdf1848d414a8b45e4", size = 794976 },
-    { url = "https://files.pythonhosted.org/packages/4b/bf/fa87e563bf5fee75db8915f7352e1887b1249126a1be4813837f5dbec965/regex-2024.11.6-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:bb26437975da7dc36b7efad18aa9dd4ea569d2357ae6b783bf1118dabd9ea577", size = 833077 },
-    { url = "https://files.pythonhosted.org/packages/a1/56/7295e6bad94b047f4d0834e4779491b81216583c00c288252ef625c01d23/regex-2024.11.6-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:abfa5080c374a76a251ba60683242bc17eeb2c9818d0d30117b4486be10c59d3", size = 823160 },
-    { url = "https://files.pythonhosted.org/packages/fb/13/e3b075031a738c9598c51cfbc4c7879e26729c53aa9cca59211c44235314/regex-2024.11.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:70b7fa6606c2881c1db9479b0eaa11ed5dfa11c8d60a474ff0e095099f39d98e", size = 796896 },
-    { url = "https://files.pythonhosted.org/packages/24/56/0b3f1b66d592be6efec23a795b37732682520b47c53da5a32c33ed7d84e3/regex-2024.11.6-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0c32f75920cf99fe6b6c539c399a4a128452eaf1af27f39bce8909c9a3fd8cbe", size = 783997 },
-    { url = "https://files.pythonhosted.org/packages/f9/a1/eb378dada8b91c0e4c5f08ffb56f25fcae47bf52ad18f9b2f33b83e6d498/regex-2024.11.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:982e6d21414e78e1f51cf595d7f321dcd14de1f2881c5dc6a6e23bbbbd68435e", size = 781725 },
-    { url = "https://files.pythonhosted.org/packages/83/f2/033e7dec0cfd6dda93390089864732a3409246ffe8b042e9554afa9bff4e/regex-2024.11.6-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:a7c2155f790e2fb448faed6dd241386719802296ec588a8b9051c1f5c481bc29", size = 789481 },
-    { url = "https://files.pythonhosted.org/packages/83/23/15d4552ea28990a74e7696780c438aadd73a20318c47e527b47a4a5a596d/regex-2024.11.6-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:149f5008d286636e48cd0b1dd65018548944e495b0265b45e1bffecce1ef7f39", size = 852896 },
-    { url = "https://files.pythonhosted.org/packages/e3/39/ed4416bc90deedbfdada2568b2cb0bc1fdb98efe11f5378d9892b2a88f8f/regex-2024.11.6-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:e5364a4502efca094731680e80009632ad6624084aff9a23ce8c8c6820de3e51", size = 860138 },
-    { url = "https://files.pythonhosted.org/packages/93/2d/dd56bb76bd8e95bbce684326302f287455b56242a4f9c61f1bc76e28360e/regex-2024.11.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:0a86e7eeca091c09e021db8eb72d54751e527fa47b8d5787caf96d9831bd02ad", size = 787692 },
-    { url = "https://files.pythonhosted.org/packages/0b/55/31877a249ab7a5156758246b9c59539abbeba22461b7d8adc9e8475ff73e/regex-2024.11.6-cp312-cp312-win32.whl", hash = "sha256:32f9a4c643baad4efa81d549c2aadefaeba12249b2adc5af541759237eee1c54", size = 262135 },
-    { url = "https://files.pythonhosted.org/packages/38/ec/ad2d7de49a600cdb8dd78434a1aeffe28b9d6fc42eb36afab4a27ad23384/regex-2024.11.6-cp312-cp312-win_amd64.whl", hash = "sha256:a93c194e2df18f7d264092dc8539b8ffb86b45b899ab976aa15d48214138e81b", size = 273567 },
-    { url = "https://files.pythonhosted.org/packages/90/73/bcb0e36614601016552fa9344544a3a2ae1809dc1401b100eab02e772e1f/regex-2024.11.6-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a6ba92c0bcdf96cbf43a12c717eae4bc98325ca3730f6b130ffa2e3c3c723d84", size = 483525 },
-    { url = "https://files.pythonhosted.org/packages/0f/3f/f1a082a46b31e25291d830b369b6b0c5576a6f7fb89d3053a354c24b8a83/regex-2024.11.6-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:525eab0b789891ac3be914d36893bdf972d483fe66551f79d3e27146191a37d4", size = 288324 },
-    { url = "https://files.pythonhosted.org/packages/09/c9/4e68181a4a652fb3ef5099e077faf4fd2a694ea6e0f806a7737aff9e758a/regex-2024.11.6-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:086a27a0b4ca227941700e0b31425e7a28ef1ae8e5e05a33826e17e47fbfdba0", size = 284617 },
-    { url = "https://files.pythonhosted.org/packages/fc/fd/37868b75eaf63843165f1d2122ca6cb94bfc0271e4428cf58c0616786dce/regex-2024.11.6-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bde01f35767c4a7899b7eb6e823b125a64de314a8ee9791367c9a34d56af18d0", size = 795023 },
-    { url = "https://files.pythonhosted.org/packages/c4/7c/d4cd9c528502a3dedb5c13c146e7a7a539a3853dc20209c8e75d9ba9d1b2/regex-2024.11.6-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b583904576650166b3d920d2bcce13971f6f9e9a396c673187f49811b2769dc7", size = 833072 },
-    { url = "https://files.pythonhosted.org/packages/4f/db/46f563a08f969159c5a0f0e722260568425363bea43bb7ae370becb66a67/regex-2024.11.6-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1c4de13f06a0d54fa0d5ab1b7138bfa0d883220965a29616e3ea61b35d5f5fc7", size = 823130 },
-    { url = "https://files.pythonhosted.org/packages/db/60/1eeca2074f5b87df394fccaa432ae3fc06c9c9bfa97c5051aed70e6e00c2/regex-2024.11.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3cde6e9f2580eb1665965ce9bf17ff4952f34f5b126beb509fee8f4e994f143c", size = 796857 },
-    { url = "https://files.pythonhosted.org/packages/10/db/ac718a08fcee981554d2f7bb8402f1faa7e868c1345c16ab1ebec54b0d7b/regex-2024.11.6-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0d7f453dca13f40a02b79636a339c5b62b670141e63efd511d3f8f73fba162b3", size = 784006 },
-    { url = "https://files.pythonhosted.org/packages/c2/41/7da3fe70216cea93144bf12da2b87367590bcf07db97604edeea55dac9ad/regex-2024.11.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:59dfe1ed21aea057a65c6b586afd2a945de04fc7db3de0a6e3ed5397ad491b07", size = 781650 },
-    { url = "https://files.pythonhosted.org/packages/a7/d5/880921ee4eec393a4752e6ab9f0fe28009435417c3102fc413f3fe81c4e5/regex-2024.11.6-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:b97c1e0bd37c5cd7902e65f410779d39eeda155800b65fc4d04cc432efa9bc6e", size = 789545 },
-    { url = "https://files.pythonhosted.org/packages/dc/96/53770115e507081122beca8899ab7f5ae28ae790bfcc82b5e38976df6a77/regex-2024.11.6-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f9d1e379028e0fc2ae3654bac3cbbef81bf3fd571272a42d56c24007979bafb6", size = 853045 },
-    { url = "https://files.pythonhosted.org/packages/31/d3/1372add5251cc2d44b451bd94f43b2ec78e15a6e82bff6a290ef9fd8f00a/regex-2024.11.6-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:13291b39131e2d002a7940fb176e120bec5145f3aeb7621be6534e46251912c4", size = 860182 },
-    { url = "https://files.pythonhosted.org/packages/ed/e3/c446a64984ea9f69982ba1a69d4658d5014bc7a0ea468a07e1a1265db6e2/regex-2024.11.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4f51f88c126370dcec4908576c5a627220da6c09d0bff31cfa89f2523843316d", size = 787733 },
-    { url = "https://files.pythonhosted.org/packages/2b/f1/e40c8373e3480e4f29f2692bd21b3e05f296d3afebc7e5dcf21b9756ca1c/regex-2024.11.6-cp313-cp313-win32.whl", hash = "sha256:63b13cfd72e9601125027202cad74995ab26921d8cd935c25f09c630436348ff", size = 262122 },
-    { url = "https://files.pythonhosted.org/packages/45/94/bc295babb3062a731f52621cdc992d123111282e291abaf23faa413443ea/regex-2024.11.6-cp313-cp313-win_amd64.whl", hash = "sha256:2b3361af3198667e99927da8b84c1b010752fa4b1115ee30beaa332cabc3ef1a", size = 273545 },
+name = "referencing"
+version = "0.36.2"
+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/2f/db/98b5c277be99dd18bfd91dd04e1b759cad18d1a338188c936e92f921c7e2/referencing-0.36.2.tar.gz", hash = "sha256:df2e89862cd09deabbdba16944cc3f10feb6b3e6f18e902f7cc25609a34775aa", size = 74744, upload-time = "2025-01-25T08:48:16.138Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/b1/3baf80dc6d2b7bc27a95a67752d0208e410351e3feb4eb78de5f77454d8d/referencing-0.36.2-py3-none-any.whl", hash = "sha256:e8699adbbf8b5c7de96d8ffa0eb5c158b3beafce084968e2ea8bb08c6794dcd0", size = 26775, upload-time = "2025-01-25T08:48:14.241Z" },
 ]
 
 [[package]]
 name = "requests"
-version = "2.32.3"
+version = "2.32.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "certifi" },
@@ -803,73 +2600,256 @@ dependencies = [
     { name = "idna" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/63/70/2bf7780ad2d390a8d301ad0b550f1581eadbd9a20f896afe06353c2a2913/requests-2.32.3.tar.gz", hash = "sha256:55365417734eb18255590a9ff9eb97e9e1da868d4ccd6402399eaf68af20a760", size = 131218 }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f9/9b/335f9764261e915ed497fcdeb11df5dfd6f7bf257d4a6a2a686d80da4d54/requests-2.32.3-py3-none-any.whl", hash = "sha256:70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6", size = 64928 },
+    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
 ]
 
 [[package]]
 name = "rich"
-version = "13.9.4"
+version = "14.3.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "markdown-it-py" },
     { name = "pygments" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ab/3a/0316b28d0761c6734d6bc14e770d85506c986c85ffb239e688eeaab2c2bc/rich-13.9.4.tar.gz", hash = "sha256:439594978a49a09530cff7ebc4b5c7103ef57baf48d5ea3184f21d9a2befa098", size = 223149 }
+sdist = { url = "https://files.pythonhosted.org/packages/74/99/a4cab2acbb884f80e558b0771e97e21e939c5dfb460f488d19df485e8298/rich-14.3.2.tar.gz", hash = "sha256:e712f11c1a562a11843306f5ed999475f09ac31ffb64281f73ab29ffdda8b3b8", size = 230143, upload-time = "2026-02-01T16:20:47.908Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ef/45/615f5babd880b4bd7d405cc0dc348234c5ffb6ed1ea33e152ede08b2072d/rich-14.3.2-py3-none-any.whl", hash = "sha256:08e67c3e90884651da3239ea668222d19bea7b589149d8014a21c633420dbb69", size = 309963, upload-time = "2026-02-01T16:20:46.078Z" },
+]
+
+[[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 = "rsa"
+version = "4.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyasn1" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/da/8a/22b7beea3ee0d44b1916c0c1cb0ee3af23b700b6da9f04991899d0c555d4/rsa-4.9.1.tar.gz", hash = "sha256:e7bdbfdb5497da4c07dfd35530e1a902659db6ff241e39d9953cad06ebd0ae75", size = 29034, upload-time = "2025-04-16T09:51:18.218Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/64/8d/0133e4eb4beed9e425d9a98ed6e081a55d195481b7632472be1af08d2f6b/rsa-4.9.1-py3-none-any.whl", hash = "sha256:68635866661c6836b8d39430f97a996acbd61bfa49406748ea243539fe239762", size = 34696, upload-time = "2025-04-16T09:51:17.142Z" },
+]
+
+[[package]]
+name = "ruff"
+version = "0.15.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/dc/4e6ac71b511b141cf626357a3946679abeba4cf67bc7cc5a17920f31e10d/ruff-0.15.1.tar.gz", hash = "sha256:c590fe13fb57c97141ae975c03a1aedb3d3156030cabd740d6ff0b0d601e203f", size = 4540855, upload-time = "2026-02-12T23:09:09.998Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/23/bf/e6e4324238c17f9d9120a9d60aa99a7daaa21204c07fcd84e2ef03bb5fd1/ruff-0.15.1-py3-none-linux_armv6l.whl", hash = "sha256:b101ed7cf4615bda6ffe65bdb59f964e9f4a0d3f85cbf0e54f0ab76d7b90228a", size = 10367819, upload-time = "2026-02-12T23:09:03.598Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/ea/c8f89d32e7912269d38c58f3649e453ac32c528f93bb7f4219258be2e7ed/ruff-0.15.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:939c995e9277e63ea632cc8d3fae17aa758526f49a9a850d2e7e758bfef46602", size = 10798618, upload-time = "2026-02-12T23:09:22.928Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/0f/1d0d88bc862624247d82c20c10d4c0f6bb2f346559d8af281674cf327f15/ruff-0.15.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:1d83466455fdefe60b8d9c8df81d3c1bbb2115cede53549d3b522ce2bc703899", size = 10148518, upload-time = "2026-02-12T23:08:58.339Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/c8/291c49cefaa4a9248e986256df2ade7add79388fe179e0691be06fae6f37/ruff-0.15.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a9457e3c3291024866222b96108ab2d8265b477e5b1534c7ddb1810904858d16", size = 10518811, upload-time = "2026-02-12T23:09:31.865Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/1a/f5707440e5ae43ffa5365cac8bbb91e9665f4a883f560893829cf16a606b/ruff-0.15.1-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:92c92b003e9d4f7fbd33b1867bb15a1b785b1735069108dfc23821ba045b29bc", size = 10196169, upload-time = "2026-02-12T23:09:17.306Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/ff/26ddc8c4da04c8fd3ee65a89c9fb99eaa5c30394269d424461467be2271f/ruff-0.15.1-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1fe5c41ab43e3a06778844c586251eb5a510f67125427625f9eb2b9526535779", size = 10990491, upload-time = "2026-02-12T23:09:25.503Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/00/50920cb385b89413f7cdb4bb9bc8fc59c1b0f30028d8bccc294189a54955/ruff-0.15.1-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:66a6dd6df4d80dc382c6484f8ce1bcceb55c32e9f27a8b94c32f6c7331bf14fb", size = 11843280, upload-time = "2026-02-12T23:09:19.88Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/6d/2f5cad8380caf5632a15460c323ae326f1e1a2b5b90a6ee7519017a017ca/ruff-0.15.1-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6a4a42cbb8af0bda9bcd7606b064d7c0bc311a88d141d02f78920be6acb5aa83", size = 11274336, upload-time = "2026-02-12T23:09:14.907Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/1d/5f56cae1d6c40b8a318513599b35ea4b075d7dc1cd1d04449578c29d1d75/ruff-0.15.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4ab064052c31dddada35079901592dfba2e05f5b1e43af3954aafcbc1096a5b2", size = 11137288, upload-time = "2026-02-12T23:09:07.475Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/20/6f8d7d8f768c93b0382b33b9306b3b999918816da46537d5a61635514635/ruff-0.15.1-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:5631c940fe9fe91f817a4c2ea4e81f47bee3ca4aa646134a24374f3c19ad9454", size = 11070681, upload-time = "2026-02-12T23:08:55.43Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/67/d640ac76069f64cdea59dba02af2e00b1fa30e2103c7f8d049c0cff4cafd/ruff-0.15.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:68138a4ba184b4691ccdc39f7795c66b3c68160c586519e7e8444cf5a53e1b4c", size = 10486401, upload-time = "2026-02-12T23:09:27.927Z" },
+    { url = "https://files.pythonhosted.org/packages/65/3d/e1429f64a3ff89297497916b88c32a5cc88eeca7e9c787072d0e7f1d3e1e/ruff-0.15.1-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:518f9af03bfc33c03bdb4cb63fabc935341bb7f54af500f92ac309ecfbba6330", size = 10197452, upload-time = "2026-02-12T23:09:12.147Z" },
+    { url = "https://files.pythonhosted.org/packages/78/83/e2c3bade17dad63bf1e1c2ffaf11490603b760be149e1419b07049b36ef2/ruff-0.15.1-py3-none-musllinux_1_2_i686.whl", hash = "sha256:da79f4d6a826caaea95de0237a67e33b81e6ec2e25fc7e1993a4015dffca7c61", size = 10693900, upload-time = "2026-02-12T23:09:34.418Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/27/fdc0e11a813e6338e0706e8b39bb7a1d61ea5b36873b351acee7e524a72a/ruff-0.15.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:3dd86dccb83cd7d4dcfac303ffc277e6048600dfc22e38158afa208e8bf94a1f", size = 11227302, upload-time = "2026-02-12T23:09:36.536Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/58/ac864a75067dcbd3b95be5ab4eb2b601d7fbc3d3d736a27e391a4f92a5c1/ruff-0.15.1-py3-none-win32.whl", hash = "sha256:660975d9cb49b5d5278b12b03bb9951d554543a90b74ed5d366b20e2c57c2098", size = 10462555, upload-time = "2026-02-12T23:09:29.899Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/5e/d4ccc8a27ecdb78116feac4935dfc39d1304536f4296168f91ed3ec00cd2/ruff-0.15.1-py3-none-win_amd64.whl", hash = "sha256:c820fef9dd5d4172a6570e5721704a96c6679b80cf7be41659ed439653f62336", size = 11599956, upload-time = "2026-02-12T23:09:01.157Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/07/5bda6a85b220c64c65686bc85bd0bbb23b29c62b3a9f9433fa55f17cda93/ruff-0.15.1-py3-none-win_arm64.whl", hash = "sha256:5ff7d5f0f88567850f45081fac8f4ec212be8d0b963e385c3f7d0d2eb4899416", size = 10874604, upload-time = "2026-02-12T23:09:05.515Z" },
+]
+
+[[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/19/71/39c7c0d87f8d4e6c020a393182060eaefeeae6c01dab6a84ec346f2567df/rich-13.9.4-py3-none-any.whl", hash = "sha256:6049d5e6ec054bf2779ab3358186963bac2ea89175919d699e378b99738c2a90", size = 242424 },
+    { 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 }
+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 },
+    { 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 = "six"
-version = "1.16.0"
+version = "1.17.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/71/39/171f1c67cd00715f190ba0b100d606d440a28c93c7714febeca8b79af85e/six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926", size = 34041 }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d9/5a/e7c31adbe875f2abbb91bd84cf2dc52d792b5a01506781dbcf25c91daf11/six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254", size = 11053 },
+    { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
 ]
 
 [[package]]
-name = "smmap"
-version = "5.0.1"
+name = "sniffio"
+version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/88/04/b5bf6d21dc4041000ccba7eb17dd3055feb237e7ffc2c20d3fae3af62baa/smmap-5.0.1.tar.gz", hash = "sha256:dceeb6c0028fdb6734471eb07c0cd2aae706ccaecab45965ee83f11c8d3b1f62", size = 22291 }
+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/a7/a5/10f97f73544edcdef54409f1d839f6049a0d79df68adbc1ceb24d1aaca42/smmap-5.0.1-py3-none-any.whl", hash = "sha256:e6d8668fa5f93e706934a62d7b4db19c8d9eb8cf2adbb75ef1b675aa332b69da", size = 24282 },
+    { 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 = "sniffio"
-version = "1.3.1"
+name = "sortedcontainers"
+version = "2.4.0"
 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 }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/c4/ba2f8066cceb6f23394729afe52f3bf7adec04bf9ed2c820b39e19299111/sortedcontainers-2.4.0.tar.gz", hash = "sha256:25caa5a06cc30b6b83d11423433f65d1f9d76c4c6a0c90e3379eaa43b9bfdb88", size = 30594, upload-time = "2021-05-16T22:03:42.897Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235 },
+    { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" },
 ]
 
 [[package]]
 name = "sse-starlette"
-version = "2.1.3"
+version = "3.2.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
     { name = "starlette" },
-    { name = "uvicorn" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/72/fc/56ab9f116b2133521f532fce8d03194cf04dcac25f583cf3d839be4c0496/sse_starlette-2.1.3.tar.gz", hash = "sha256:9cd27eb35319e1414e3d2558ee7414487f9529ce3b3cf9b21434fd110e017169", size = 19678 }
+sdist = { url = "https://files.pythonhosted.org/packages/8b/8d/00d280c03ffd39aaee0e86ec81e2d3b9253036a0f93f51d10503adef0e65/sse_starlette-3.2.0.tar.gz", hash = "sha256:8127594edfb51abe44eac9c49e59b0b01f1039d0c7461c6fd91d4e03b70da422", size = 27253, upload-time = "2026-01-17T13:11:05.62Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/52/aa/36b271bc4fa1d2796311ee7c7283a3a1c348bad426d37293609ca4300eef/sse_starlette-2.1.3-py3-none-any.whl", hash = "sha256:8ec846438b4665b9e8c560fcdea6bc8081a3abf7942faa95e5a744999d219772", size = 9383 },
+    { url = "https://files.pythonhosted.org/packages/96/7f/832f015020844a8b8f7a9cbc103dd76ba8e3875004c41e08440ea3a2b41a/sse_starlette-3.2.0-py3-none-any.whl", hash = "sha256:5876954bd51920fc2cd51baee47a080eb88a37b5b784e615abb0b283f801cdbf", size = 12763, upload-time = "2026-01-17T13:11:03.775Z" },
 ]
 
 [[package]]
@@ -881,171 +2861,407 @@ dependencies = [
     { 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 }
+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 },
+    { 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 = "0.41.3"
+version = "0.52.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/1a/4c/9b5764bd22eec91c4039ef4c55334e9187085da2d8a2df7bd570869aae18/starlette-0.41.3.tar.gz", hash = "sha256:0e4ab3d16522a255be6b28260b938eae2482f98ce5cc934cb08dce8dc3ba5835", size = 2574159 }
+sdist = { url = "https://files.pythonhosted.org/packages/c4/68/79977123bb7be889ad680d79a40f339082c1978b5cfcf62c2d8d196873ac/starlette-0.52.1.tar.gz", hash = "sha256:834edd1b0a23167694292e94f597773bc3f89f362be6effee198165a35d62933", size = 2653702, upload-time = "2026-01-18T13:34:11.062Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/96/00/2b325970b3060c7cecebab6d295afe763365822b1306a12eeab198f74323/starlette-0.41.3-py3-none-any.whl", hash = "sha256:44cedb2b7c77a9de33a8b74b2b90e9f50d11fcf25d8270ea525ad71a25374ff7", size = 73225 },
+    { url = "https://files.pythonhosted.org/packages/81/0d/13d1d239a25cbfb19e740db83143e95c772a1fe10202dda4b76792b114dd/starlette-0.52.1-py3-none-any.whl", hash = "sha256:0029d43eb3d273bc4f83a08720b4912ea4b071087a3b48db01b7c839f7954d74", size = 74272, upload-time = "2026-01-18T13:34:09.188Z" },
 ]
 
 [[package]]
-name = "tiktoken"
-version = "0.8.0"
+name = "taskgroup"
+version = "0.2.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "regex" },
-    { name = "requests" },
+    { 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" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/37/02/576ff3a6639e755c4f70997b2d315f56d6d71e0d046f4fb64cb81a3fb099/tiktoken-0.8.0.tar.gz", hash = "sha256:9ccbb2740f24542534369c5635cfd9b2b3c2490754a78ac8831d99f89f94eeb2", size = 35107 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/c9/ba/a35fad753bbca8ba0cc1b0f3402a70256a110ced7ac332cf84ba89fc87ab/tiktoken-0.8.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:b07e33283463089c81ef1467180e3e00ab00d46c2c4bbcef0acab5f771d6695e", size = 1039905 },
-    { url = "https://files.pythonhosted.org/packages/91/05/13dab8fd7460391c387b3e69e14bf1e51ff71fe0a202cd2933cc3ea93fb6/tiktoken-0.8.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9269348cb650726f44dd3bbb3f9110ac19a8dcc8f54949ad3ef652ca22a38e21", size = 982417 },
-    { url = "https://files.pythonhosted.org/packages/e9/98/18ec4a8351a6cf4537e40cd6e19a422c10cce1ef00a2fcb716e0a96af58b/tiktoken-0.8.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e13f37bc4ef2d012731e93e0fef21dc3b7aea5bb9009618de9a4026844e560", size = 1144915 },
-    { url = "https://files.pythonhosted.org/packages/2e/28/cf3633018cbcc6deb7805b700ccd6085c9a5a7f72b38974ee0bffd56d311/tiktoken-0.8.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f13d13c981511331eac0d01a59b5df7c0d4060a8be1e378672822213da51e0a2", size = 1177221 },
-    { url = "https://files.pythonhosted.org/packages/57/81/8a5be305cbd39d4e83a794f9e80c7f2c84b524587b7feb27c797b2046d51/tiktoken-0.8.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:6b2ddbc79a22621ce8b1166afa9f9a888a664a579350dc7c09346a3b5de837d9", size = 1237398 },
-    { url = "https://files.pythonhosted.org/packages/dc/da/8d1cc3089a83f5cf11c2e489332752981435280285231924557350523a59/tiktoken-0.8.0-cp310-cp310-win_amd64.whl", hash = "sha256:d8c2d0e5ba6453a290b86cd65fc51fedf247e1ba170191715b049dac1f628005", size = 884215 },
-    { url = "https://files.pythonhosted.org/packages/f6/1e/ca48e7bfeeccaf76f3a501bd84db1fa28b3c22c9d1a1f41af9fb7579c5f6/tiktoken-0.8.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:d622d8011e6d6f239297efa42a2657043aaed06c4f68833550cac9e9bc723ef1", size = 1039700 },
-    { url = "https://files.pythonhosted.org/packages/8c/f8/f0101d98d661b34534769c3818f5af631e59c36ac6d07268fbfc89e539ce/tiktoken-0.8.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2efaf6199717b4485031b4d6edb94075e4d79177a172f38dd934d911b588d54a", size = 982413 },
-    { url = "https://files.pythonhosted.org/packages/ac/3c/2b95391d9bd520a73830469f80a96e3790e6c0a5ac2444f80f20b4b31051/tiktoken-0.8.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5637e425ce1fc49cf716d88df3092048359a4b3bbb7da762840426e937ada06d", size = 1144242 },
-    { url = "https://files.pythonhosted.org/packages/01/c4/c4a4360de845217b6aa9709c15773484b50479f36bb50419c443204e5de9/tiktoken-0.8.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9fb0e352d1dbe15aba082883058b3cce9e48d33101bdaac1eccf66424feb5b47", size = 1176588 },
-    { url = "https://files.pythonhosted.org/packages/f8/a3/ef984e976822cd6c2227c854f74d2e60cf4cd6fbfca46251199914746f78/tiktoken-0.8.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:56edfefe896c8f10aba372ab5706b9e3558e78db39dd497c940b47bf228bc419", size = 1237261 },
-    { url = "https://files.pythonhosted.org/packages/1e/86/eea2309dc258fb86c7d9b10db536434fc16420feaa3b6113df18b23db7c2/tiktoken-0.8.0-cp311-cp311-win_amd64.whl", hash = "sha256:326624128590def898775b722ccc327e90b073714227175ea8febbc920ac0a99", size = 884537 },
-    { url = "https://files.pythonhosted.org/packages/c1/22/34b2e136a6f4af186b6640cbfd6f93400783c9ef6cd550d9eab80628d9de/tiktoken-0.8.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:881839cfeae051b3628d9823b2e56b5cc93a9e2efb435f4cf15f17dc45f21586", size = 1039357 },
-    { url = "https://files.pythonhosted.org/packages/04/d2/c793cf49c20f5855fd6ce05d080c0537d7418f22c58e71f392d5e8c8dbf7/tiktoken-0.8.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fe9399bdc3f29d428f16a2f86c3c8ec20be3eac5f53693ce4980371c3245729b", size = 982616 },
-    { url = "https://files.pythonhosted.org/packages/b3/a1/79846e5ef911cd5d75c844de3fa496a10c91b4b5f550aad695c5df153d72/tiktoken-0.8.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9a58deb7075d5b69237a3ff4bb51a726670419db6ea62bdcd8bd80c78497d7ab", size = 1144011 },
-    { url = "https://files.pythonhosted.org/packages/26/32/e0e3a859136e95c85a572e4806dc58bf1ddf651108ae8b97d5f3ebe1a244/tiktoken-0.8.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2908c0d043a7d03ebd80347266b0e58440bdef5564f84f4d29fb235b5df3b04", size = 1175432 },
-    { url = "https://files.pythonhosted.org/packages/c7/89/926b66e9025b97e9fbabeaa59048a736fe3c3e4530a204109571104f921c/tiktoken-0.8.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:294440d21a2a51e12d4238e68a5972095534fe9878be57d905c476017bff99fc", size = 1236576 },
-    { url = "https://files.pythonhosted.org/packages/45/e2/39d4aa02a52bba73b2cd21ba4533c84425ff8786cc63c511d68c8897376e/tiktoken-0.8.0-cp312-cp312-win_amd64.whl", hash = "sha256:d8f3192733ac4d77977432947d563d7e1b310b96497acd3c196c9bddb36ed9db", size = 883824 },
-    { url = "https://files.pythonhosted.org/packages/e3/38/802e79ba0ee5fcbf240cd624143f57744e5d411d2e9d9ad2db70d8395986/tiktoken-0.8.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:02be1666096aff7da6cbd7cdaa8e7917bfed3467cd64b38b1f112e96d3b06a24", size = 1039648 },
-    { url = "https://files.pythonhosted.org/packages/b1/da/24cdbfc302c98663fbea66f5866f7fa1048405c7564ab88483aea97c3b1a/tiktoken-0.8.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c94ff53c5c74b535b2cbf431d907fc13c678bbd009ee633a2aca269a04389f9a", size = 982763 },
-    { url = "https://files.pythonhosted.org/packages/e4/f0/0ecf79a279dfa41fc97d00adccf976ecc2556d3c08ef3e25e45eb31f665b/tiktoken-0.8.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6b231f5e8982c245ee3065cd84a4712d64692348bc609d84467c57b4b72dcbc5", size = 1144417 },
-    { url = "https://files.pythonhosted.org/packages/ab/d3/155d2d4514f3471a25dc1d6d20549ef254e2aa9bb5b1060809b1d3b03d3a/tiktoken-0.8.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4177faa809bd55f699e88c96d9bb4635d22e3f59d635ba6fd9ffedf7150b9953", size = 1175108 },
-    { url = "https://files.pythonhosted.org/packages/19/eb/5989e16821ee8300ef8ee13c16effc20dfc26c777d05fbb6825e3c037b81/tiktoken-0.8.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5376b6f8dc4753cd81ead935c5f518fa0fbe7e133d9e25f648d8c4dabdd4bad7", size = 1236520 },
-    { url = "https://files.pythonhosted.org/packages/40/59/14b20465f1d1cb89cfbc96ec27e5617b2d41c79da12b5e04e96d689be2a7/tiktoken-0.8.0-cp313-cp313-win_amd64.whl", hash = "sha256:18228d624807d66c87acd8f25fc135665617cab220671eb65b50f5d70fa51f69", size = 883849 },
+
+[[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.2.1"
+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 = "tqdm"
+version = "4.67.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/18/87/302344fed471e44a87289cf4967697d07e532f2421fdaf868a303cbae4ff/tomli-2.2.1.tar.gz", hash = "sha256:cd45e1dc79c835ce60f7404ec8119f2eb06d38b1deba146f07ced3bbc44505ff", size = 17175 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/43/ca/75707e6efa2b37c77dadb324ae7d9571cb424e61ea73fad7c56c2d14527f/tomli-2.2.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:678e4fa69e4575eb77d103de3df8a895e1591b48e740211bd1067378c69e8249", size = 131077 },
-    { url = "https://files.pythonhosted.org/packages/c7/16/51ae563a8615d472fdbffc43a3f3d46588c264ac4f024f63f01283becfbb/tomli-2.2.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:023aa114dd824ade0100497eb2318602af309e5a55595f76b626d6d9f3b7b0a6", size = 123429 },
-    { url = "https://files.pythonhosted.org/packages/f1/dd/4f6cd1e7b160041db83c694abc78e100473c15d54620083dbd5aae7b990e/tomli-2.2.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ece47d672db52ac607a3d9599a9d48dcb2f2f735c6c2d1f34130085bb12b112a", size = 226067 },
-    { url = "https://files.pythonhosted.org/packages/a9/6b/c54ede5dc70d648cc6361eaf429304b02f2871a345bbdd51e993d6cdf550/tomli-2.2.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6972ca9c9cc9f0acaa56a8ca1ff51e7af152a9f87fb64623e31d5c83700080ee", size = 236030 },
-    { url = "https://files.pythonhosted.org/packages/1f/47/999514fa49cfaf7a92c805a86c3c43f4215621855d151b61c602abb38091/tomli-2.2.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:c954d2250168d28797dd4e3ac5cf812a406cd5a92674ee4c8f123c889786aa8e", size = 240898 },
-    { url = "https://files.pythonhosted.org/packages/73/41/0a01279a7ae09ee1573b423318e7934674ce06eb33f50936655071d81a24/tomli-2.2.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:8dd28b3e155b80f4d54beb40a441d366adcfe740969820caf156c019fb5c7ec4", size = 229894 },
-    { url = "https://files.pythonhosted.org/packages/55/18/5d8bc5b0a0362311ce4d18830a5d28943667599a60d20118074ea1b01bb7/tomli-2.2.1-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:e59e304978767a54663af13c07b3d1af22ddee3bb2fb0618ca1593e4f593a106", size = 245319 },
-    { url = "https://files.pythonhosted.org/packages/92/a3/7ade0576d17f3cdf5ff44d61390d4b3febb8a9fc2b480c75c47ea048c646/tomli-2.2.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:33580bccab0338d00994d7f16f4c4ec25b776af3ffaac1ed74e0b3fc95e885a8", size = 238273 },
-    { url = "https://files.pythonhosted.org/packages/72/6f/fa64ef058ac1446a1e51110c375339b3ec6be245af9d14c87c4a6412dd32/tomli-2.2.1-cp311-cp311-win32.whl", hash = "sha256:465af0e0875402f1d226519c9904f37254b3045fc5084697cefb9bdde1ff99ff", size = 98310 },
-    { url = "https://files.pythonhosted.org/packages/6a/1c/4a2dcde4a51b81be3530565e92eda625d94dafb46dbeb15069df4caffc34/tomli-2.2.1-cp311-cp311-win_amd64.whl", hash = "sha256:2d0f2fdd22b02c6d81637a3c95f8cd77f995846af7414c5c4b8d0545afa1bc4b", size = 108309 },
-    { url = "https://files.pythonhosted.org/packages/52/e1/f8af4c2fcde17500422858155aeb0d7e93477a0d59a98e56cbfe75070fd0/tomli-2.2.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4a8f6e44de52d5e6c657c9fe83b562f5f4256d8ebbfe4ff922c495620a7f6cea", size = 132762 },
-    { url = "https://files.pythonhosted.org/packages/03/b8/152c68bb84fc00396b83e7bbddd5ec0bd3dd409db4195e2a9b3e398ad2e3/tomli-2.2.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8d57ca8095a641b8237d5b079147646153d22552f1c637fd3ba7f4b0b29167a8", size = 123453 },
-    { url = "https://files.pythonhosted.org/packages/c8/d6/fc9267af9166f79ac528ff7e8c55c8181ded34eb4b0e93daa767b8841573/tomli-2.2.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4e340144ad7ae1533cb897d406382b4b6fede8890a03738ff1683af800d54192", size = 233486 },
-    { url = "https://files.pythonhosted.org/packages/5c/51/51c3f2884d7bab89af25f678447ea7d297b53b5a3b5730a7cb2ef6069f07/tomli-2.2.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:db2b95f9de79181805df90bedc5a5ab4c165e6ec3fe99f970d0e302f384ad222", size = 242349 },
-    { url = "https://files.pythonhosted.org/packages/ab/df/bfa89627d13a5cc22402e441e8a931ef2108403db390ff3345c05253935e/tomli-2.2.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:40741994320b232529c802f8bc86da4e1aa9f413db394617b9a256ae0f9a7f77", size = 252159 },
-    { url = "https://files.pythonhosted.org/packages/9e/6e/fa2b916dced65763a5168c6ccb91066f7639bdc88b48adda990db10c8c0b/tomli-2.2.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:400e720fe168c0f8521520190686ef8ef033fb19fc493da09779e592861b78c6", size = 237243 },
-    { url = "https://files.pythonhosted.org/packages/b4/04/885d3b1f650e1153cbb93a6a9782c58a972b94ea4483ae4ac5cedd5e4a09/tomli-2.2.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:02abe224de6ae62c19f090f68da4e27b10af2b93213d36cf44e6e1c5abd19fdd", size = 259645 },
-    { url = "https://files.pythonhosted.org/packages/9c/de/6b432d66e986e501586da298e28ebeefd3edc2c780f3ad73d22566034239/tomli-2.2.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b82ebccc8c8a36f2094e969560a1b836758481f3dc360ce9a3277c65f374285e", size = 244584 },
-    { url = "https://files.pythonhosted.org/packages/1c/9a/47c0449b98e6e7d1be6cbac02f93dd79003234ddc4aaab6ba07a9a7482e2/tomli-2.2.1-cp312-cp312-win32.whl", hash = "sha256:889f80ef92701b9dbb224e49ec87c645ce5df3fa2cc548664eb8a25e03127a98", size = 98875 },
-    { url = "https://files.pythonhosted.org/packages/ef/60/9b9638f081c6f1261e2688bd487625cd1e660d0a85bd469e91d8db969734/tomli-2.2.1-cp312-cp312-win_amd64.whl", hash = "sha256:7fc04e92e1d624a4a63c76474610238576942d6b8950a2d7f908a340494e67e4", size = 109418 },
-    { url = "https://files.pythonhosted.org/packages/04/90/2ee5f2e0362cb8a0b6499dc44f4d7d48f8fff06d28ba46e6f1eaa61a1388/tomli-2.2.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:f4039b9cbc3048b2416cc57ab3bda989a6fcf9b36cf8937f01a6e731b64f80d7", size = 132708 },
-    { url = "https://files.pythonhosted.org/packages/c0/ec/46b4108816de6b385141f082ba99e315501ccd0a2ea23db4a100dd3990ea/tomli-2.2.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:286f0ca2ffeeb5b9bd4fcc8d6c330534323ec51b2f52da063b11c502da16f30c", size = 123582 },
-    { url = "https://files.pythonhosted.org/packages/a0/bd/b470466d0137b37b68d24556c38a0cc819e8febe392d5b199dcd7f578365/tomli-2.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a92ef1a44547e894e2a17d24e7557a5e85a9e1d0048b0b5e7541f76c5032cb13", size = 232543 },
-    { url = "https://files.pythonhosted.org/packages/d9/e5/82e80ff3b751373f7cead2815bcbe2d51c895b3c990686741a8e56ec42ab/tomli-2.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9316dc65bed1684c9a98ee68759ceaed29d229e985297003e494aa825ebb0281", size = 241691 },
-    { url = "https://files.pythonhosted.org/packages/05/7e/2a110bc2713557d6a1bfb06af23dd01e7dde52b6ee7dadc589868f9abfac/tomli-2.2.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e85e99945e688e32d5a35c1ff38ed0b3f41f43fad8df0bdf79f72b2ba7bc5272", size = 251170 },
-    { url = "https://files.pythonhosted.org/packages/64/7b/22d713946efe00e0adbcdfd6d1aa119ae03fd0b60ebed51ebb3fa9f5a2e5/tomli-2.2.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ac065718db92ca818f8d6141b5f66369833d4a80a9d74435a268c52bdfa73140", size = 236530 },
-    { url = "https://files.pythonhosted.org/packages/38/31/3a76f67da4b0cf37b742ca76beaf819dca0ebef26d78fc794a576e08accf/tomli-2.2.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:d920f33822747519673ee656a4b6ac33e382eca9d331c87770faa3eef562aeb2", size = 258666 },
-    { url = "https://files.pythonhosted.org/packages/07/10/5af1293da642aded87e8a988753945d0cf7e00a9452d3911dd3bb354c9e2/tomli-2.2.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a198f10c4d1b1375d7687bc25294306e551bf1abfa4eace6650070a5c1ae2744", size = 243954 },
-    { url = "https://files.pythonhosted.org/packages/5b/b9/1ed31d167be802da0fc95020d04cd27b7d7065cc6fbefdd2f9186f60d7bd/tomli-2.2.1-cp313-cp313-win32.whl", hash = "sha256:d3f5614314d758649ab2ab3a62d4f2004c825922f9e370b29416484086b264ec", size = 98724 },
-    { url = "https://files.pythonhosted.org/packages/c7/32/b0963458706accd9afcfeb867c0f9175a741bf7b19cd424230714d722198/tomli-2.2.1-cp313-cp313-win_amd64.whl", hash = "sha256:a38aa0308e754b0e3c67e344754dff64999ff9b513e691d0e786265c93583c69", size = 109383 },
-    { url = "https://files.pythonhosted.org/packages/6e/c2/61d3e0f47e2b74ef40a68b9e6ad5984f6241a942f7cd3bbfbdbd03861ea9/tomli-2.2.1-py3-none-any.whl", hash = "sha256:cb55c73c5f4408779d0cf3eef9f762b9c9f147a77de7b258bef0a5628adc85cc", size = 14257 },
+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 }
+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.20"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/56/95/8de69bb98417227b01f1b1d743c819d6456c9fd140255b6124b05b17dfd6/ty-0.0.20.tar.gz", hash = "sha256:ebba6be7974c14efbb2a9adda6ac59848f880d7259f089dfa72a093039f1dcc6", size = 5262529, upload-time = "2026-03-02T15:51:36.587Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/00/c0/8f5d070730d7836adc9c9b6408dec68c6ced86b304a9b26a14df072a6e8c/traitlets-5.14.3-py3-none-any.whl", hash = "sha256:b74e89e397b1ed28cc831db7aea759ba6640cb3de13090ca145426688ff1ac4f", size = 85359 },
+    { url = "https://files.pythonhosted.org/packages/0b/2c/718abe48393e521bf852cd6b0f984766869b09c258d6e38a118768a91731/ty-0.0.20-py3-none-linux_armv6l.whl", hash = "sha256:7cc12769c169c9709a829c2248ee2826b7aae82e92caeac813d856f07c021eae", size = 10333656, upload-time = "2026-03-02T15:51:56.461Z" },
+    { url = "https://files.pythonhosted.org/packages/41/0e/eb1c4cc4a12862e2327b72657bcebb10b7d9f17046f1bdcd6457a0211615/ty-0.0.20-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:3b777c1bf13bc0a95985ebb8a324b8668a4a9b2e514dde5ccf09e4d55d2ff232", size = 10168505, upload-time = "2026-03-02T15:51:51.895Z" },
+    { url = "https://files.pythonhosted.org/packages/89/7f/10230798e673f0dd3094dfd16e43bfd90e9494e7af6e8e7db516fb431ddf/ty-0.0.20-py3-none-macosx_11_0_arm64.whl", hash = "sha256:b2a4a7db48bf8cba30365001bc2cad7fd13c1a5aacdd704cc4b7925de8ca5eb3", size = 9678510, upload-time = "2026-03-02T15:51:48.451Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/3d/59d9159577494edd1728f7db77b51bb07884bd21384f517963114e3ab5f6/ty-0.0.20-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6846427b8b353a43483e9c19936dc6a25612573b44c8f7d983dfa317e7f00d4c", size = 10162926, upload-time = "2026-03-02T15:51:40.558Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/a8/b7273eec3e802f78eb913fbe0ce0c16ef263723173e06a5776a8359b2c66/ty-0.0.20-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:245ceef5bd88df366869385cf96411cb14696334f8daa75597cf7e41c3012eb8", size = 10171702, upload-time = "2026-03-02T15:51:44.069Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/32/5f1144f2f04a275109db06e3498450c4721554215b80ae73652ef412eeab/ty-0.0.20-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:c4d21d1cdf67a444d3c37583c17291ddba9382a9871021f3f5d5735e09e85efe", size = 10682552, upload-time = "2026-03-02T15:51:33.102Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/db/9f1f637310792f12bd6ed37d5fc8ab39ba1a9b0c6c55a33865e9f1cad840/ty-0.0.20-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:bd4ffd907d1bd70e46af9e9a2f88622f215e1bf44658ea43b32c2c0b357299e4", size = 11242605, upload-time = "2026-03-02T15:51:34.895Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/68/cc9cae2e732fcfd20ccdffc508407905a023fc8493b8771c392d915528dc/ty-0.0.20-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b6594b58d8b0e9d16a22b3045fc1305db4b132c8d70c17784ab8c7a7cc986807", size = 10974655, upload-time = "2026-03-02T15:51:46.011Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/c1/b9e3e3f28fe63486331e653f6aeb4184af8b1fe80542fcf74d2dda40a93d/ty-0.0.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3662f890518ce6cf4d7568f57d03906912d2afbf948a01089a28e325b1ef198c", size = 10761325, upload-time = "2026-03-02T15:51:26.818Z" },
+    { url = "https://files.pythonhosted.org/packages/39/9e/67db935bdedf219a00fb69ec5437ba24dab66e0f2e706dd54a4eca234b84/ty-0.0.20-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0e3ffbae58f9f0d17cdc4ac6d175ceae560b7ed7d54f9ddfb1c9f31054bcdc2c", size = 10145793, upload-time = "2026-03-02T15:51:38.562Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/de/b0eb815d4dc5a819c7e4faddc2a79058611169f7eef07ccc006531ce228c/ty-0.0.20-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:176e52bc8bb00b0e84efd34583962878a447a3a0e34ecc45fd7097a37554261b", size = 10189640, upload-time = "2026-03-02T15:51:50.202Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/71/63734923965cbb70df1da3e93e4b8875434e326b89e9f850611122f279bf/ty-0.0.20-py3-none-musllinux_1_2_i686.whl", hash = "sha256:b2bc73025418e976ca4143dde71fb9025a90754a08ac03e6aa9b80d4bed1294b", size = 10370568, upload-time = "2026-03-02T15:51:42.295Z" },
+    { url = "https://files.pythonhosted.org/packages/32/a0/a532c2048533347dff48e9ca98bd86d2c224356e101688a8edaf8d6973fb/ty-0.0.20-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:d52f7c9ec6e363e094b3c389c344d5a140401f14a77f0625e3f28c21918552f5", size = 10853999, upload-time = "2026-03-02T15:51:58.963Z" },
+    { url = "https://files.pythonhosted.org/packages/48/88/36c652c658fe96658043e4abc8ea97801de6fb6e63ab50aaa82807bff1d8/ty-0.0.20-py3-none-win32.whl", hash = "sha256:c7d32bfe93f8fcaa52b6eef3f1b930fd7da410c2c94e96f7412c30cfbabf1d17", size = 9744206, upload-time = "2026-03-02T15:51:54.183Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/a7/a4a13bed1d7fd9d97aaa3c5bb5e6d3e9a689e6984806cbca2ab4c9233cac/ty-0.0.20-py3-none-win_amd64.whl", hash = "sha256:a5e10f40fc4a0a1cbcb740a4aad5c7ce35d79f030836ea3183b7a28f43170248", size = 10711999, upload-time = "2026-03-02T15:51:29.212Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/7e/6bfd748a9f4ff9267ed3329b86a0f02cdf6ab49f87bc36c8a164852f99fc/ty-0.0.20-py3-none-win_arm64.whl", hash = "sha256:53f7a5c12c960e71f160b734f328eff9a35d578af4b67a36b0bb5990ac5cdc27", size = 10150143, upload-time = "2026-03-02T15:51:31.283Z" },
 ]
 
 [[package]]
 name = "typer"
-version = "0.14.0"
+version = "0.23.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
+    { name = "annotated-doc" },
     { name = "click" },
     { name = "rich" },
     { name = "shellingham" },
-    { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0d/7e/24af5b9aaa0872f9f6dc5dcf789dc3e57ceb23b4c570b852cd4db0d98f14/typer-0.14.0.tar.gz", hash = "sha256:af58f737f8d0c0c37b9f955a6d39000b9ff97813afcbeef56af5e37cf743b45a", size = 98836 }
+sdist = { url = "https://files.pythonhosted.org/packages/d3/ae/93d16574e66dfe4c2284ffdaca4b0320ade32858cb2cc586c8dd79f127c5/typer-0.23.2.tar.gz", hash = "sha256:a99706a08e54f1aef8bb6a8611503808188a4092808e86addff1828a208af0de", size = 120162, upload-time = "2026-02-16T18:52:40.354Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/bb/d8/a3ab71d5587b42b832a7ef2e65b3e51a18f8da32b6ce169637d4d21995ed/typer-0.14.0-py3-none-any.whl", hash = "sha256:f476233a25770ab3e7b2eebf7c68f3bc702031681a008b20167573a4b7018f09", size = 44707 },
+    { url = "https://files.pythonhosted.org/packages/14/2c/dee705c427875402200fe779eb8a3c00ccb349471172c41178336e9599cc/typer-0.23.2-py3-none-any.whl", hash = "sha256:e9c8dc380f82450b3c851a9b9d5a0edf95d1d6456ae70c517d8b06a50c7a9978", size = 56834, upload-time = "2026-02-16T18:52:39.308Z" },
 ]
 
 [[package]]
 name = "typing-extensions"
-version = "4.12.2"
+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/df/db/f35a00659bc03fec321ba8bce9420de607a1d37f8342eee1863174c69557/typing_extensions-4.12.2.tar.gz", hash = "sha256:1a7ead55c7e559dd4dee8856e3a88b41225abfe1ce8df57b7c13915fe121ffb8", size = 85321 }
+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/26/9f/ad63fc0248c5379346306f8668cda6e2e2e9c95e01216d2b8ffd9ff037d0/typing_extensions-4.12.2-py3-none-any.whl", hash = "sha256:04e5ca0351e0f3f85c6853954072df659d0d13fac324d0072316b67d7794700d", size = 37438 },
+    { 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.2.3"
+version = "2.6.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ed/63/22ba4ebfe7430b76388e7cd448d5478814d3032121827c12a2cc287e2260/urllib3-2.2.3.tar.gz", hash = "sha256:e7d814a81dad81e6caf2ec9fdedb284ecc9c73076b62654547cc64ccdcae26e9", size = 300677 }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ce/d9/5f4c13cecde62396b0d3fe530a50ccea91e7dfc1ccf0e09c228841bb5ba8/urllib3-2.2.3-py3-none-any.whl", hash = "sha256:ca899ca043dcb1bafa3e262d73aa25c465bfb49e0bd9dd5d59f1d0acba2f8fac", size = 126338 },
+    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
 ]
 
 [[package]]
 name = "uvicorn"
-version = "0.32.1"
+version = "0.40.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/6a/3c/21dba3e7d76138725ef307e3d7ddd29b763119b3aa459d02cc05fefcff75/uvicorn-0.32.1.tar.gz", hash = "sha256:ee9519c246a72b1c084cea8d3b44ed6026e78a4a309cbedae9c37e4cb9fbb175", size = 77630 }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/d1/8f3c683c9561a4e6689dd3b1d345c815f10f86acd044ee1fb9a4dcd0b8c5/uvicorn-0.40.0.tar.gz", hash = "sha256:839676675e87e73694518b5574fd0f24c9d97b46bea16df7b8c05ea1a51071ea", size = 81761, upload-time = "2025-12-21T14:16:22.45Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/50/c1/2d27b0a15826c2b71dcf6e2f5402181ef85acf439617bb2f1453125ce1f3/uvicorn-0.32.1-py3-none-any.whl", hash = "sha256:82ad92fd58da0d12af7482ecdb5f2470a04c9c9a53ced65b9bbb4a205377602e", size = 63828 },
+    { url = "https://files.pythonhosted.org/packages/3d/d8/2083a1daa7439a66f3a48589a57d576aa117726762618f6bb09fe3798796/uvicorn-0.40.0-py3-none-any.whl", hash = "sha256:c6c8f55bc8bf13eb6fa9ff87ad62308bbbc33d0b67f84293151efe87e0d5f2ee", size = 68502, upload-time = "2025-12-21T14:16:21.041Z" },
 ]
 
 [[package]]
-name = "wcwidth"
-version = "0.2.13"
+name = "watchfiles"
+version = "1.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6c/63/53559446a878410fc5a5974feb13d31d78d752eb18aeba59c7fef1af7598/wcwidth-0.2.13.tar.gz", hash = "sha256:72ea0c06399eb286d978fdedb6923a9eb47e1c486ce63e9b4e64fc18303972b5", size = 101301 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/fd/84/fd2ba7aafacbad3c4201d395674fc6348826569da3c0937e75505ead3528/wcwidth-0.2.13-py2.py3-none-any.whl", hash = "sha256:3da69048e4540d84af32131829ff948f1e022c1c6bdb8d6102117aac784f6859", size = 34166 },
+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 = "wmctrl"
-version = "0.5"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "attrs" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/60/d9/6625ead93412c5ce86db1f8b4f2a70b8043e0a7c1d30099ba3c6a81641ff/wmctrl-0.5.tar.gz", hash = "sha256:7839a36b6fe9e2d6fd22304e5dc372dbced2116ba41283ea938b2da57f53e962", size = 5202 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/13/ca/723e3f8185738d7947f14ee7dc663b59415c6dee43bd71575f8c7f5cd6be/wmctrl-0.5-py2.py3-none-any.whl", hash = "sha256:ae695c1863a314c899e7cf113f07c0da02a394b968c4772e1936219d9234ddd7", size = 4268 },
+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 000000000..70b64c9c7
--- /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 000000000..addbd01c3
--- /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 000000000..b1a0e8081
--- /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 000000000..c37c14c8a
--- /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 000000000..24cd6328c
--- /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 000000000..4678c426e
--- /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 000000000..fa1c0406c
--- /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