[ { "path": ".ccignore", "content": ".pre-commit-config.yaml\n.github/\ndocs/changelog.mdx\ndocs/python-sdk/\nexamples/\nsrc/fastmcp/contrib/\ntests/contrib/\n" }, { "path": ".claude/hooks/session-init.sh", "content": "#!/bin/bash\nset -e\n\n# Only run in remote/cloud environments\nif [ \"$CLAUDE_CODE_REMOTE\" != \"true\" ]; then\n exit 0\nfi\n\ncommand -v gh &> /dev/null && exit 0\n\nLOCAL_BIN=\"$HOME/.local/bin\"\nmkdir -p \"$LOCAL_BIN\"\n\nARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')\nVERSION=$(curl -fsSL https://api.github.com/repos/cli/cli/releases/latest | grep '\"tag_name\"' | cut -d'\"' -f4)\nTARBALL=\"gh_${VERSION#v}_linux_${ARCH}.tar.gz\"\n\necho \"Installing gh ${VERSION}...\"\nTEMP=$(mktemp -d)\ntrap 'rm -rf \"$TEMP\"' EXIT\ncurl -fsSL \"https://github.com/cli/cli/releases/download/${VERSION}/${TARBALL}\" | tar -xz -C \"$TEMP\"\ncp \"$TEMP\"/gh_*/bin/gh \"$LOCAL_BIN/gh\"\nchmod 755 \"$LOCAL_BIN/gh\"\n\n[ -n \"$CLAUDE_ENV_FILE\" ] && echo \"export PATH=\\\"$LOCAL_BIN:\\$PATH\\\"\" >> \"$CLAUDE_ENV_FILE\"\necho \"gh installed: $(\"$LOCAL_BIN/gh\" --version | head -1)\"\n" }, { "path": ".claude/settings.json", "content": "{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash \\\"$CLAUDE_PROJECT_DIR\\\"/.claude/hooks/session-init.sh\",\n \"timeout\": 120\n }\n ]\n }\n ]\n }\n}\n" }, { "path": ".claude/skills/code-review/SKILL.md", "content": "---\nname: reviewing-code\ndescription: 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.\n---\n\n# Code Review\n\n## Philosophy\n\nCode 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.\n\n**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.\n\nBe 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.\n\n## What to Focus On\n\n### Does this advance the codebase correctly?\n\nEven perfect code for unwanted features should be rejected.\n\n### Dependency version compatibility\n\nWhen a PR adapts code to a new version of a dependency (e.g., removing a parameter that was dropped upstream, using a new API):\n- **The version pin in `pyproject.toml` must match.** If the change breaks compatibility with the previously-pinned minimum version, the minimum version must be bumped. Otherwise users on the old version get a regression.\n- **If backwards compatibility with the old version is desired**, the code must handle both versions (e.g., try/except, version check). Simply deleting the old API usage without bumping the pin is always wrong — it silently breaks users on the old version.\n- **Lock file (`uv.lock`) changes should be scoped to the PR's purpose.** A PR fixing a ty compatibility issue should not also include unrelated dependency version bumps (anthropic, google-auth, etc.) from running `uv sync --upgrade`. These create noise and make the diff harder to review.\n\n### API design and naming\n\nIdentify confusing patterns or non-idiomatic code:\n- Parameter values that contradict defaults\n- Mutable default arguments\n- Unclear naming that will confuse future readers\n- Inconsistent patterns with the rest of the codebase\n\n### Specific improvements\n\nProvide actionable feedback, not generic observations.\n\n### User ergonomics\n\nThink about the API from a user's perspective. Is it intuitive? What's the learning curve?\n\n## For Agent Reviewers\n\n1. **Read the full context**: Examine related files, tests, and documentation before reviewing\n2. **Check against established patterns**: Look for consistency with codebase conventions\n3. **Verify functionality claims**: Understand what the code actually does, not just what it claims\n4. **Consider edge cases**: Think through error conditions and boundary scenarios\n\n## What to Avoid\n\n- Generic feedback without specifics\n- Hypothetical problems unlikely to occur\n- Nitpicking organizational choices without strong reason\n- Summarizing what the PR already describes\n- Star ratings or excessive emojis\n- Bikeshedding style preferences when functionality is correct\n- Requesting changes without suggesting solutions\n- Focusing on personal coding style over project conventions\n\n## Tone\n\n- Acknowledge good decisions: \"This API design is clean\"\n- Be direct but respectful\n- Explain impact: \"This will confuse users because...\"\n- Remember: Someone else maintains this code forever\n\n## Decision Framework\n\nBefore approving, ask:\n\n1. Does this PR achieve its stated purpose?\n2. Is that purpose aligned with where the codebase should go?\n3. Would I be comfortable maintaining this code?\n4. Have I actually understood what it does, not just what it claims?\n5. Does this change introduce technical debt?\n\nIf something needs work, your review should help it get there through specific, actionable feedback. If it's solving the wrong problem, say so clearly.\n\n## Comment Examples\n\n**Good comments:**\n\n| Instead of | Write |\n|------------|-------|\n| \"Add more tests\" | \"The `handle_timeout` method needs tests for the edge case where timeout=0\" |\n| \"This API is confusing\" | \"The parameter name `data` is ambiguous - consider `message_content` to match the MCP specification\" |\n| \"This could be better\" | \"This approach works but creates a circular dependency. Consider moving the validation to `utils/validators.py`\" |\n\n## Checklist\n\nBefore approving, verify:\n\n- [ ] All required development workflow steps completed (uv sync, prek, pytest)\n- [ ] Changes align with repository patterns and conventions\n- [ ] API changes are documented and backwards-compatible where possible\n- [ ] Error handling follows project patterns (specific exception types)\n- [ ] Tests cover new functionality and edge cases\n- [ ] The change advances the codebase in the intended direction\n" }, { "path": ".claude/skills/python-tests/SKILL.md", "content": "---\nname: testing-python\ndescription: 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.\n---\n\n# Writing Effective Python Tests\n\n## Core Principles\n\nEvery test should be **atomic**, **self-contained**, and test **single functionality**. A test that tests multiple things is harder to debug and maintain.\n\n## Test Structure\n\n### Atomic unit tests\n\nEach 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.\n\n```python\n# Good: Name tells you what's broken\ndef test_user_creation_sets_defaults():\n user = User(name=\"Alice\")\n assert user.role == \"member\"\n assert user.id is not None\n assert user.created_at is not None\n\n# Bad: If this fails, what behavior is broken?\ndef test_user():\n user = User(name=\"Alice\")\n assert user.role == \"member\"\n user.promote()\n assert user.role == \"admin\"\n assert user.can_delete_others()\n```\n\n### Use parameterization for variations of the same concept\n\n```python\nimport pytest\n\n@pytest.mark.parametrize(\"input,expected\", [\n (\"hello\", \"HELLO\"),\n (\"World\", \"WORLD\"),\n (\"\", \"\"),\n (\"123\", \"123\"),\n])\ndef test_uppercase_conversion(input, expected):\n assert input.upper() == expected\n```\n\n### Use separate tests for different functionality\n\nDon't parameterize unrelated behaviors. If the test logic differs, write separate tests.\n\n## Project-Specific Rules\n\n### No async markers needed\n\nThis project uses `asyncio_mode = \"auto\"` globally. Write async tests without decorators:\n\n```python\n# Correct\nasync def test_async_operation():\n result = await some_async_function()\n assert result == expected\n\n# Wrong - don't add this\n@pytest.mark.asyncio\nasync def test_async_operation():\n ...\n```\n\n### Imports at module level\n\nPut ALL imports at the top of the file:\n\n```python\n# Correct\nimport pytest\nfrom fastmcp import FastMCP\nfrom fastmcp.client import Client\n\nasync def test_something():\n mcp = FastMCP(\"test\")\n ...\n\n# Wrong - no local imports\nasync def test_something():\n from fastmcp import FastMCP # Don't do this\n ...\n```\n\n### Use in-memory transport for testing\n\nPass FastMCP servers directly to clients:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.client import Client\n\nmcp = FastMCP(\"TestServer\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\nasync def test_greet_tool():\n async with Client(mcp) as client:\n result = await client.call_tool(\"greet\", {\"name\": \"World\"})\n assert result[0].text == \"Hello, World!\"\n```\n\nOnly use HTTP transport when explicitly testing network features.\n\n### Inline snapshots for complex data\n\nUse `inline-snapshot` for testing JSON schemas and complex structures:\n\n```python\nfrom inline_snapshot import snapshot\n\ndef test_schema_generation():\n schema = generate_schema(MyModel)\n assert schema == snapshot() # Will auto-populate on first run\n```\n\nCommands:\n- `pytest --inline-snapshot=create` - populate empty snapshots\n- `pytest --inline-snapshot=fix` - update after intentional changes\n\n## Fixtures\n\n### Prefer function-scoped fixtures\n\n```python\n@pytest.fixture\ndef client():\n return Client()\n\nasync def test_with_client(client):\n result = await client.ping()\n assert result is not None\n```\n\n### Use `tmp_path` for file operations\n\n```python\ndef test_file_writing(tmp_path):\n file = tmp_path / \"test.txt\"\n file.write_text(\"content\")\n assert file.read_text() == \"content\"\n```\n\n## Mocking\n\n### Mock at the boundary\n\n```python\nfrom unittest.mock import patch, AsyncMock\n\nasync def test_external_api_call():\n with patch(\"mymodule.external_client.fetch\", new_callable=AsyncMock) as mock:\n mock.return_value = {\"data\": \"test\"}\n result = await my_function()\n assert result == {\"data\": \"test\"}\n```\n\n### Don't mock what you own\n\nTest your code with real implementations when possible. Mock external services, not internal classes.\n\n## Test Naming\n\nUse descriptive names that explain the scenario:\n\n```python\n# Good\ndef test_login_fails_with_invalid_password():\ndef test_user_can_update_own_profile():\ndef test_admin_can_delete_any_user():\n\n# Bad\ndef test_login():\ndef test_update():\ndef test_delete():\n```\n\n## Error Testing\n\n```python\nimport pytest\n\ndef test_raises_on_invalid_input():\n with pytest.raises(ValueError, match=\"must be positive\"):\n calculate(-1)\n\nasync def test_async_raises():\n with pytest.raises(ConnectionError):\n await connect_to_invalid_host()\n```\n\n## Running Tests\n\n```bash\nuv run pytest -n auto # Run all tests in parallel\nuv run pytest -n auto -x # Stop on first failure\nuv run pytest path/to/test.py # Run specific file\nuv run pytest -k \"test_name\" # Run tests matching pattern\nuv run pytest -m \"not integration\" # Exclude integration tests\n```\n\n## Checklist\n\nBefore submitting tests:\n- [ ] Each test tests one thing\n- [ ] No `@pytest.mark.asyncio` decorators\n- [ ] Imports at module level\n- [ ] Descriptive test names\n- [ ] Using in-memory transport (not HTTP) unless testing networking\n- [ ] Parameterization for variations of same behavior\n- [ ] Separate tests for different behaviors\n" }, { "path": ".claude/skills/review-pr/SKILL.md", "content": "---\nname: review-pr\ndescription: Monitor and respond to automated PR reviews (Codex bot). Use when pushing a PR, checking review status, or responding to bot feedback. Handles the full cycle of push -> wait for review -> evaluate comments -> fix -> re-push.\n---\n\n# PR Review Workflow\n\nThis repo has `chatgpt-codex-connector[bot]` configured as an automated reviewer. After every push to a PR branch, Codex reviews the diff and either:\n- Reacts with a thumbs-up on its review body (no suggestions — PR is clean)\n- Posts inline comments with suggestions (each tagged with a priority badge)\n\n## Checking review status\n\nAfter pushing, check whether Codex has reviewed the latest commit:\n\n```bash\n# Get the latest commit SHA on the branch\nLATEST=$(git rev-parse HEAD)\n\n# Check if Codex has reviewed that specific commit\ngh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \\\n | jq \"[.[] | select(.user.login == \\\"chatgpt-codex-connector[bot]\\\" and .commit_id == \\\"$LATEST\\\")] | length\"\n```\n\nIf the count is 0, Codex hasn't reviewed the latest push yet. Wait and check again.\n\nIf the count is > 0, check for inline comments on the latest review:\n\n```bash\n# Get the review body to check for thumbs-up\ngh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \\\n | jq '[.[] | select(.user.login == \"chatgpt-codex-connector[bot]\") | {state, body: .body[:300], commit_id: .commit_id}] | last'\n```\n\nA clean review from Codex looks like a review body that contains a thumbs-up reaction or says \"no suggestions.\" If the body contains \"Here are some automated review suggestions,\" there are inline comments to evaluate.\n\n## Evaluating Codex comments\n\nFetch all inline comments from Codex:\n\n```bash\ngh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \\\n | jq '[.[] | select(.user.login == \"chatgpt-codex-connector[bot]\") | {body, path, line, created_at}]'\n```\n\nCodex comments include priority badges:\n- `P0` (red) — Critical issue, likely a real bug\n- `P1` (orange) — Important, worth fixing\n- `P2` (yellow) — Moderate, evaluate on merit\n\n**How to evaluate Codex comments:**\n\n1. **Treat Codex as a competent but sometimes overzealous reviewer.** It catches real bugs (cache eviction ordering, silent data loss, missing validation) but also suggests scope expansions and hypothetical improvements.\n\n2. **Fix real bugs** — issues in code you actually changed where behavior is incorrect or data is silently lost.\n\n3. **Dismiss scope expansion** — if a comment points out a pre-existing limitation unrelated to your diff, note it as a potential follow-up but don't block the PR.\n\n4. **Dismiss speculative concerns** — if a comment describes a scenario that requires very specific conditions and the existing behavior is acceptable, dismiss it.\n\n5. **When fixing, be proactive** — if Codex found one instance of a pattern bug (e.g., missing role validation in one handler), check all similar code paths before pushing. Codex will find the next instance on the next review cycle, so get ahead of it.\n\n## Responding to every comment\n\n**Every Codex comment must get a visible response** — either a fix or a reply explaining why it was dismissed. The maintainer can't see your reasoning otherwise.\n\n- **If fixing**: The fix itself is the response. No reply needed unless the fix is non-obvious.\n- **If dismissing**: Reply to the comment thread with a brief explanation of why. Keep it to 1-2 sentences. Examples:\n - \"This is pre-existing behavior unrelated to this diff — the scope lookup fallback existed before caching was added. Worth a follow-up issue but not blocking this PR.\"\n - \"The AsyncExitStack handles cleanup when the session exits, so the subprocess isn't leaked — just kept alive slightly longer than necessary in this edge case.\"\n - \"Gemini supports a much wider range of media types than OpenAI/Anthropic, so a restrictive allowlist would be inaccurate here.\"\n\nUse `gh api` to reply (note: use `in_reply_to`, not a `/replies` sub-path):\n\n```bash\n# Reply to a specific review comment\ngh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \\\n -f body=\"Your reply here\" \\\n -F in_reply_to={COMMENT_ID}\n```\n\n## The fix-push-review cycle\n\nAfter evaluating comments:\n\n1. Fix all real issues in one batch\n2. Reply to all dismissed comments with reasoning\n3. Think about what patterns Codex might flag next — check similar code paths proactively\n4. Commit and push\n5. Check that Codex reviews the new commit\n6. Repeat until Codex gives a clean review (thumbs-up) or only has dismissible comments\n\n## Responding to stale comments\n\nCodex sometimes re-posts old comments that reference code you've already fixed (they appear on the old commit's diff). These are stale — verify the fix is in the latest commit and reply noting the fix is already in place.\n\n## When a PR is ready\n\nA PR is ready for human review when:\n- All Codex comments are either fixed or replied to with dismissal reasoning\n- CI checks pass\n- The diff is clean and focused on the stated purpose\n" }, { "path": ".coderabbit.yaml", "content": "reviews:\n path_filters:\n - \"!docs/python-sdk/**\"\n" }, { "path": ".cursor/rules/core-mcp-objects.mdc", "content": "---\ndescription: \nglobs: \nalwaysApply: true\n---\nThere are four major MCP object types:\n\n- Tools (src/tools/)\n- Resources (src/resources/)\n- Resource Templates (src/resources/)\n- Prompts (src/prompts)\n\nWhile 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/`." }, { "path": ".github/ISSUE_TEMPLATE/bug.yml", "content": "name: 🐛 Bug Report\ndescription: Report a bug or unexpected behavior in FastMCP\nlabels: [bug, pending]\n\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for reporting a bug!\n\n A good bug report is one of the most valuable contributions you can make — see [CONTRIBUTING.md](../../CONTRIBUTING.md). If the fix is straightforward, a PR is also welcome.\n\n ### Before you submit\n\n - Make sure you're testing on the **latest version** of FastMCP — many issues are already fixed in newer releases\n - Check if someone else has **already reported this** or if it's been fixed on the main branch\n - You **must** include a copy/pasteable, properly formatted MRE (minimal reproducible example) or your issue may be closed without response\n - **The ideal issue is a clear problem description and an MRE — that's it.** If you've done genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis. We have LLMs too, and an incorrect analysis is harder to work with than none at all.\n - **Keep it short.** A clear description plus a concise MRE is ideal — aim to fit in a single screen. Issues that include unsolicited root cause analysis, proposed fixes, or multi-section diagnostic writeups will be labeled `too-long` and not triaged until condensed.\n - **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).\n\n - type: textarea\n id: description\n attributes:\n label: What happened?\n description: |\n Describe the bug in a few sentences. What did you do, what happened, and what did you expect instead?\n\n Do NOT include root cause analysis, proposed fixes, or diagnostic writeups — just describe the problem.\n validations:\n required: true\n\n - type: textarea\n id: example\n attributes:\n label: Example Code\n description: >\n If applicable, please provide a self-contained,\n [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)\n demonstrating the bug. If possible, your example should be a single-file script.\n\n placeholder: |\n import asyncio\n from fastmcp import FastMCP, Client\n\n mcp = FastMCP()\n\n async def demo():\n async with Client(mcp) as client:\n ... # show the bug here\n\n if __name__ == \"__main__\":\n asyncio.run(demo())\n render: Python\n\n - type: textarea\n id: version\n attributes:\n label: Version Information\n description: |\n Please tell us about your FastMCP version, MCP version, Python version, and OS, as well as any other relevant details about your environment.\n\n To get the basic information, run the following command in your terminal and paste the output below:\n\n ```bash\n fastmcp version --copy\n ```\n render: Text\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: FastMCP Documentation\n url: https://gofastmcp.com\n about: Please review the documentation before opening an issue.\n - name: MCP Python SDK\n url: https://github.com/modelcontextprotocol/python-sdk/issues\n 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.\n" }, { "path": ".github/ISSUE_TEMPLATE/enhancement.yml", "content": "name: 💡 Enhancement Request\ndescription: Suggest an idea or improvement for FastMCP\nlabels: [enhancement, pending]\n\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for suggesting an improvement to FastMCP!\n\n Enhancement issues are the **primary way** features and improvements get into FastMCP. Maintainers use well-written issues to implement changes that fit the codebase's patterns and ship quickly. A clear issue here is more impactful than a PR — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for why.\n\n ### Before you submit\n\n - 🔍 **Check if this has already been requested** — search existing issues first\n - 🎯 **Describe the problem you're trying to solve**, not the solution you want — we'll figure out the best implementation\n - ✂️ **Keep it short.** A motivating description and a concrete use case is the ideal request — aim to fit in a single screen. Skip proposed implementations, API designs, or multi-option analyses — maintainers will figure out the approach. Requests that are difficult to parse will be labeled `too-long` and not triaged until condensed.\n - 🤖 **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).\n\n - type: textarea\n id: description\n attributes:\n label: Enhancement\n description: |\n What problem or use case does this solve? How does current behavior fall short?\n\n Focus on the *what* and *why* — the motivating scenario. You don't need to propose an API or implementation.\n validations:\n required: true\n" }, { "path": ".github/actions/run-claude/action.yml", "content": "# Composite Action for running Claude Code Action\n#\n# Wraps anthropics/claude-code-action with MCP server configuration.\n# Template based on elastic/ai-github-actions base action.\n#\n# Usage:\n# - uses: ./.github/actions/run-claude\n# with:\n# prompt: \"Your prompt here\"\n# claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n# github-token: ${{ steps.marvin-token.outputs.token }}\n# allowed-tools: \"Edit,Read,Write,Bash(*),mcp__github__add_issue_comment\"\n#\nname: \"Run Claude\"\ndescription: \"Run Claude Code with MCP servers\"\nauthor: \"FastMCP\"\n\nbranding:\n icon: \"cpu\"\n color: \"orange\"\n\ninputs:\n prompt:\n description: \"Prompt to pass to Claude\"\n required: true\n\n claude-oauth-token:\n description: \"Claude Code OAuth token for authentication\"\n required: true\n\n github-token:\n description: \"GitHub token for Claude to operate with\"\n required: true\n\n allowed-tools:\n description: \"Comma-separated list of allowed tools (e.g. Edit,Write,Bash(npm test))\"\n required: false\n default: \"\"\n\n model:\n description: \"Model to use for Claude\"\n required: false\n default: \"claude-opus-4-6\"\n\n allowed-bots:\n description: \"Allowed bot usernames, or '*' for all bots\"\n required: false\n default: \"\"\n\n track-progress:\n description: \"Whether Claude should track progress\"\n required: false\n default: \"true\"\n\n mcp-servers:\n description: \"MCP server configuration JSON\"\n required: false\n 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\"}}}'\n\n trigger-phrase:\n description: \"Trigger phrase (for mention workflows)\"\n required: false\n default: \"/marvin\"\n\noutputs:\n conclusion:\n description: \"The conclusion of the Claude Code run\"\n value: ${{ steps.claude.outputs.conclusion }}\n\nruns:\n using: \"composite\"\n steps:\n - name: Clean up stale Claude locks\n shell: bash\n run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true\n\n - name: Run Claude Code\n id: claude\n env:\n GITHUB_TOKEN: ${{ inputs.github-token }}\n uses: anthropics/claude-code-action@v1\n with:\n github_token: ${{ inputs.github-token }}\n claude_code_oauth_token: ${{ inputs.claude-oauth-token }}\n bot_name: \"Marvin Context Protocol\"\n trigger_phrase: ${{ inputs.trigger-phrase }}\n allowed_bots: ${{ inputs.allowed-bots }}\n track_progress: ${{ inputs.track-progress }}\n prompt: ${{ inputs.prompt }}\n claude_args: |\n ${{ (inputs.allowed-tools != '' || inputs.extra-allowed-tools != '') && format('--allowedTools {0}{1}', inputs.allowed-tools, inputs.extra-allowed-tools != '' && format(',{0}', inputs.extra-allowed-tools) || '') || '' }}\n ${{ inputs.mcp-servers != '' && format('--mcp-config ''{0}''', inputs.mcp-servers) || '' }}\n --model ${{ inputs.model }}\n settings: |\n {\"model\": \"${{ inputs.model }}\"}\n" }, { "path": ".github/actions/run-pytest/action.yml", "content": "name: \"Run Pytest\"\ndescription: \"Run pytest with appropriate flags for the test type and platform\"\n\ninputs:\n test-type:\n description: \"Type of tests to run: unit, integration, or client_process\"\n required: false\n default: \"unit\"\n\nruns:\n using: \"composite\"\n steps:\n - name: Run pytest\n shell: bash\n run: |\n if [ \"${{ inputs.test-type }}\" == \"integration\" ]; then\n MARKER=\"integration\"\n TIMEOUT=\"30\"\n MAX_PROCS=\"2\"\n EXTRA_FLAGS=\"\"\n elif [ \"${{ inputs.test-type }}\" == \"client_process\" ]; then\n MARKER=\"client_process\"\n TIMEOUT=\"5\"\n MAX_PROCS=\"0\"\n EXTRA_FLAGS=\"-x\"\n else\n MARKER=\"not integration and not client_process\"\n TIMEOUT=\"5\"\n MAX_PROCS=\"4\"\n EXTRA_FLAGS=\"\"\n fi\n\n PARALLEL_FLAGS=\"\"\n if [ \"$MAX_PROCS\" != \"0\" ] && [ \"${{ runner.os }}\" != \"Windows\" ]; then\n PARALLEL_FLAGS=\"--numprocesses auto --maxprocesses $MAX_PROCS --dist worksteal\"\n fi\n\n uv run --no-sync pytest \\\n --inline-snapshot=disable \\\n --timeout=$TIMEOUT \\\n --durations=50 \\\n -m \"$MARKER\" \\\n $PARALLEL_FLAGS \\\n $EXTRA_FLAGS \\\n tests\n" }, { "path": ".github/actions/setup-uv/action.yml", "content": "name: \"Setup UV Environment\"\ndescription: \"Install uv and dependencies (requires checkout first)\"\n\ninputs:\n python-version:\n description: \"Python version to use\"\n required: false\n default: \"3.10\"\n resolution:\n description: \"Dependency resolution: locked, upgrade, or lowest-direct\"\n required: false\n default: \"locked\"\n\nruns:\n using: \"composite\"\n steps:\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n cache-dependency-glob: \"uv.lock\"\n python-version: ${{ inputs.python-version }}\n\n - name: Install dependencies\n shell: bash\n run: |\n if [ \"${{ inputs.resolution }}\" == \"locked\" ]; then\n uv sync --locked\n elif [ \"${{ inputs.resolution }}\" == \"upgrade\" ]; then\n uv sync --upgrade\n else\n uv sync --resolution ${{ inputs.resolution }}\n fi\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: \"pip\"\n directory: \"/\"\n schedule:\n interval: \"daily\"\n labels:\n - \"dependencies\"\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n labels:\n - \"dependencies\"\n" }, { "path": ".github/pull_request_template.md", "content": "## Description\n\n\n\nCloses #\n\n## Contribution type\n\n\n\n- [ ] Bug fix (simple, well-scoped fix for a clearly broken behavior)\n- [ ] Documentation improvement\n- [ ] Enhancement (maintainers typically implement enhancements — see [CONTRIBUTING.md](../CONTRIBUTING.md))\n\n## Checklist\n\n- [ ] This PR addresses an existing issue (or fixes a self-evident bug)\n- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)\n- [ ] I have added tests that cover my changes\n- [ ] I have run `uv run prek run --all-files` and all checks pass\n- [ ] I have self-reviewed my changes\n- [ ] If I used an LLM, it followed the repo's contributing conventions (not generic output)\n" }, { "path": ".github/release.yml", "content": "changelog:\n exclude:\n labels:\n - ignore in release notes\n\n categories:\n - title: New Features 🎉\n labels:\n - feature\n\n - title: Breaking Changes ⚠️\n labels:\n - breaking change\n exclude:\n labels:\n - contrib\n - security\n\n - title: Enhancements ✨\n labels:\n - enhancement\n exclude:\n labels:\n - breaking change\n - security\n\n - title: Security 🔒\n labels:\n - security\n\n - title: Fixes 🐞\n labels:\n - bug\n exclude:\n labels:\n - contrib\n - security\n\n - title: Docs 📚\n labels:\n - documentation\n\n - title: Examples & Contrib 💡\n labels:\n - example\n - contrib\n\n - title: Dependencies 📦\n labels:\n - dependencies\n exclude:\n labels:\n - security\n\n - title: Other Changes 🦾\n labels:\n - \"*\"\n" }, { "path": ".github/scripts/mention/gh-get-review-threads.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Get PR review threads with comments via GitHub GraphQL API\n#\n# Usage:\n# gh-get-review-threads.sh [FILTER]\n#\n# Arguments:\n# FILTER - Optional: filter for unresolved threads from specific author\n#\n# Environment (set by composite action):\n# MENTION_REPO - Repository (owner/repo format)\n# MENTION_PR_NUMBER - Pull request number\n# GITHUB_TOKEN - GitHub API token\n#\n# Output:\n# JSON array of review threads with nested comments\n\n# Parse OWNER and REPO from MENTION_REPO\nREPO_FULL=\"${MENTION_REPO:?MENTION_REPO environment variable is required}\"\nOWNER=\"${REPO_FULL%/*}\"\nREPO=\"${REPO_FULL#*/}\"\nPR_NUMBER=\"${MENTION_PR_NUMBER:?MENTION_PR_NUMBER environment variable is required}\"\nFILTER=\"${1:-}\"\n\ngh api graphql -f query='\n query($owner: String!, $repo: String!, $prNumber: Int!) {\n repository(owner: $owner, name: $repo) {\n pullRequest(number: $prNumber) {\n reviewThreads(first: 100) {\n nodes {\n id\n isResolved\n isOutdated\n path\n line\n comments(first: 50) {\n nodes {\n id\n body\n author { login }\n createdAt\n }\n }\n }\n }\n }\n }\n }' -F owner=\"$OWNER\" \\\n -F repo=\"$REPO\" \\\n -F prNumber=\"$PR_NUMBER\" \\\n --jq '.data.repository.pullRequest.reviewThreads.nodes' | \\\nif [ -n \"$FILTER\" ]; then\n jq --arg author \"$FILTER\" '\n map(select(\n .isResolved == false and\n .comments.nodes | any(.author.login == $author)\n ))'\nelse\n cat\nfi\n" }, { "path": ".github/scripts/mention/gh-resolve-review-thread.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Resolve a GitHub PR review thread, optionally posting a comment first\n#\n# Usage:\n# gh-resolve-review-thread.sh THREAD_ID [COMMENT]\n#\n# Arguments:\n# THREAD_ID - The GraphQL node ID of the review thread to resolve\n# COMMENT - Optional: Comment body to post before resolving\n#\n# Environment (set by composite action):\n# MENTION_REPO - Repository (owner/repo format)\n# MENTION_PR_NUMBER - Pull request number\n# GITHUB_TOKEN - GitHub API token\n#\n# Behavior:\n# 1. If COMMENT is provided, posts it as a reply to the thread\n# 2. Resolves the thread\n\n# Validate required environment variables\n: \"${MENTION_REPO:?MENTION_REPO environment variable is required}\"\n: \"${MENTION_PR_NUMBER:?MENTION_PR_NUMBER environment variable is required}\"\nTHREAD_ID=\"${1:?Thread ID required}\"\nCOMMENT=\"${2:-}\"\n\n# Step 1: Post comment if provided\nif [ -n \"$COMMENT\" ]; then\n echo \"Posting comment to thread...\" >&2\n COMMENT_RESULT=$(gh api graphql -f query='\n mutation($threadId: ID!, $body: String!) {\n addPullRequestReviewThreadReply(input: {\n pullRequestReviewThreadId: $threadId,\n body: $body\n }) {\n comment {\n id\n }\n }\n }' -f threadId=\"$THREAD_ID\" -f body=\"$COMMENT\")\n if echo \"$COMMENT_RESULT\" | jq -e '.errors' > /dev/null 2>&1; then\n echo \"Error posting comment: $COMMENT_RESULT\" >&2\n exit 1\n fi\nfi\n\n# Step 2: Resolve the thread\necho \"Resolving thread...\" >&2\nRESOLVE_RESULT=$(gh api graphql -f query='\n mutation($threadId: ID!) {\n resolveReviewThread(input: {threadId: $threadId}) {\n thread {\n id\n isResolved\n }\n }\n }' -f threadId=\"$THREAD_ID\" --jq '.data.resolveReviewThread.thread')\n\necho \"$RESOLVE_RESULT\"\necho \"✓ Thread resolved\" >&2\n" }, { "path": ".github/scripts/pr-review/pr-comment.sh", "content": "#!/bin/bash\n# pr-comment.sh - Queue a structured inline review comment for the PR review\n#\n# Usage:\n# pr-comment.sh --severity --title --why [suggestion via stdin]\n# pr-comment.sh --severity --title --why --no-suggestion\n#\n# Arguments:\n# file File path (required)\n# line Line number (required)\n# --severity Severity level: critical, high, medium, low, nitpick (required)\n# --title Brief description for comment heading (required)\n# --why One sentence explaining the risk/impact (required)\n# --no-suggestion Explicitly skip suggestion (use for architectural issues)\n#\n# The suggestion code is read from stdin (use heredoc). If no stdin and no --no-suggestion, errors.\n#\n# Examples:\n# # With suggestion (preferred)\n# pr-comment.sh src/main.go 42 --severity high --title \"Missing error check\" --why \"Errors are silently ignored\" <<'EOF'\n# if err != nil {\n# return fmt.Errorf(\"operation failed: %w\", err)\n# }\n# EOF\n#\n# # Without suggestion (for issues requiring broader changes)\n# pr-comment.sh src/main.go 42 --severity medium --title \"Consider extracting to function\" \\\n# --why \"This logic is duplicated in 3 places\" --no-suggestion\n#\n# Environment variables (set by the composite action):\n# PR_REVIEW_REPO - Repository (owner/repo)\n# PR_REVIEW_PR_NUMBER - Pull request number\n# PR_REVIEW_COMMENTS_DIR - Directory to cache comments (default: /tmp/pr-review-comments)\n\nset -e\n\n# Configuration from environment\nREPO=\"${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}\"\nPR_NUMBER=\"${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}\"\nCOMMENTS_DIR=\"${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}\"\n\n# Severity emoji mapping\ndeclare -A SEVERITY_EMOJI=(\n [critical]=\"🔴 CRITICAL\"\n [high]=\"🟠 HIGH\"\n [medium]=\"🟡 MEDIUM\"\n [low]=\"⚪ LOW\"\n [nitpick]=\"💬 NITPICK\"\n)\n\n# Parse arguments\nFILE=\"\"\nLINE=\"\"\nSEVERITY=\"\"\nTITLE=\"\"\nWHY=\"\"\nNO_SUGGESTION=false\n\n# First two positional args are file and line\nif [ $# -lt 2 ]; then\n echo \"Error: file and line are required\"\n echo \"Usage: pr-comment.sh --severity --title --why [<<'EOF' ... EOF]\"\n exit 1\nfi\n\nFILE=\"$1\"\nLINE=\"$2\"\nshift 2\n\n# Parse named arguments\nwhile [ $# -gt 0 ]; do\n case \"$1\" in\n --severity)\n SEVERITY=\"$2\"\n shift 2\n ;;\n --title)\n TITLE=\"$2\"\n shift 2\n ;;\n --why)\n WHY=\"$2\"\n shift 2\n ;;\n --no-suggestion)\n NO_SUGGESTION=true\n shift\n ;;\n *)\n echo \"Error: Unknown argument: $1\"\n exit 1\n ;;\n esac\ndone\n\n# Read suggestion from stdin if available\nSUGGESTION=\"\"\nif [ ! -t 0 ]; then\n SUGGESTION=$(cat)\nfi\n\n# Validate required arguments\nif [ -z \"$SEVERITY\" ]; then\n echo \"Error: --severity is required (critical, high, medium, low, nitpick)\"\n exit 1\nfi\n\nif [ -z \"$TITLE\" ]; then\n echo \"Error: --title is required\"\n exit 1\nfi\n\nif [ -z \"$WHY\" ]; then\n echo \"Error: --why is required\"\n exit 1\nfi\n\n# Validate severity level\nif [ -z \"${SEVERITY_EMOJI[$SEVERITY]}\" ]; then\n echo \"Error: Invalid severity '$SEVERITY'. Must be one of: critical, high, medium, low, nitpick\"\n exit 1\nfi\n\n# Require either suggestion or explicit --no-suggestion\nif [ -z \"$SUGGESTION\" ] && [ \"$NO_SUGGESTION\" = false ]; then\n echo \"Error: Suggestion required. Provide code via stdin (heredoc) or use --no-suggestion\"\n echo \"\"\n echo \"Example with suggestion:\"\n echo \" pr-comment.sh file.go 42 --severity high --title \\\"desc\\\" --why \\\"reason\\\" <<'EOF'\"\n echo \" fixed code here\"\n echo \" EOF\"\n echo \"\"\n echo \"Example without suggestion:\"\n echo \" pr-comment.sh file.go 42 --severity medium --title \\\"desc\\\" --why \\\"reason\\\" --no-suggestion\"\n exit 1\nfi\n\n# Validate line is a positive integer (>= 1)\nif ! [[ \"$LINE\" =~ ^[1-9][0-9]*$ ]]; then\n echo \"Error: Line number must be a positive integer (>= 1), got: $LINE\"\n exit 1\nfi\n\n# Get the diff for this file to validate the comment location\nDIFF_DATA=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}/files\" --paginate | jq --arg f \"$FILE\" '.[] | select(.filename==$f)')\n\nif [ -z \"$DIFF_DATA\" ]; then\n echo \"Error: File '${FILE}' not found in PR diff\"\n echo \"\"\n echo \"Files changed in this PR:\"\n gh api \"repos/${REPO}/pulls/${PR_NUMBER}/files\" --paginate --jq '.[].filename'\n exit 1\nfi\n\nPATCH=$(echo \"$DIFF_DATA\" | jq -r '.patch // empty')\n\nif [ -z \"$PATCH\" ]; then\n echo \"Error: No patch data for file '${FILE}' (file may be binary or too large)\"\n exit 1\nfi\n\n# Verify the line exists in the diff\nLINE_IN_DIFF=$(echo \"$PATCH\" | awk -v target_line=\"$LINE\" '\nBEGIN { current_line = 0; found = 0 }\n/^@@/ {\n line = $0\n gsub(/.*\\+/, \"\", line)\n gsub(/[^0-9].*/, \"\", line)\n current_line = line - 1\n next\n}\n{\n if (substr($0, 1, 1) != \"-\") {\n current_line++\n if (current_line == target_line) {\n found = 1\n exit\n }\n }\n}\nEND { if (found) print \"1\"; else print \"0\" }\n')\n\nif [ \"$LINE_IN_DIFF\" != \"1\" ]; then\n echo \"Error: Line ${LINE} not found in the diff for '${FILE}'\"\n echo \"\"\n echo \"Note: You can only comment on lines that appear in the diff (added, modified, or context lines)\"\n echo \"\"\n echo \"First 50 lines of diff for this file:\"\n echo \"$PATCH\" | head -50\n exit 1\nfi\n\n# Create comments directory if it doesn't exist\nmkdir -p \"${COMMENTS_DIR}\"\n\n# Assemble the comment body\nSEVERITY_LABEL=\"${SEVERITY_EMOJI[$SEVERITY]}\"\n\nBODY=\"**${SEVERITY_LABEL}** ${TITLE}\n\nWhy: ${WHY}\"\n\n# Add suggestion block if provided\nif [ -n \"$SUGGESTION\" ]; then\n BODY=\"${BODY}\n\n\\`\\`\\`suggestion\n${SUGGESTION}\n\\`\\`\\`\"\nfi\n\n# Append standard footer\nFOOTER='\n\n---\nMarvin Context Protocol | Type `/marvin` to interact further\n\nGive us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.'\n\nBODY_WITH_FOOTER=\"${BODY}${FOOTER}\"\n\n# Generate unique comment ID\nCOMMENT_ID=\"comment-$(date +%s)-$(od -An -N4 -tu4 /dev/urandom | tr -d ' ')\"\nCOMMENT_FILE=\"${COMMENTS_DIR}/${COMMENT_ID}.json\"\n\n# Create the comment JSON object\njq -n \\\n --arg path \"$FILE\" \\\n --argjson line \"$LINE\" \\\n --arg side \"RIGHT\" \\\n --arg body \"$BODY_WITH_FOOTER\" \\\n --arg id \"$COMMENT_ID\" \\\n '{\n path: $path,\n line: $line,\n side: $side,\n body: $body,\n _meta: {\n id: $id,\n file: $path,\n line: $line\n }\n }' > \"${COMMENT_FILE}\"\n\necho \"✓ Queued review comment for ${FILE}:${LINE}\"\necho \" Severity: ${SEVERITY_LABEL}\"\necho \" Title: ${TITLE}\"\necho \" Comment ID: ${COMMENT_ID}\"\necho \" Comment will be submitted with pr-review.sh\"\necho \" Remove with: pr-remove-comment.sh ${FILE} ${LINE}\"\n" }, { "path": ".github/scripts/pr-review/pr-diff.sh", "content": "#!/bin/bash\n# pr-diff.sh - Show changed files or diff for a specific file\n#\n# Usage: \n# pr-diff.sh - List all changed files (shows full diff if small enough)\n# pr-diff.sh - Show diff for a specific file with line numbers\n#\n# Environment variables (set by the composite action):\n# PR_REVIEW_REPO - Repository (owner/repo)\n# PR_REVIEW_PR_NUMBER - Pull request number\n\nset -e\n\n# Configuration from environment\nREPO=\"${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}\"\nPR_NUMBER=\"${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}\"\nEXPECTED_HEAD=\"${PR_REVIEW_HEAD_SHA:-}\"\n\n# Check if HEAD has changed since review started (race condition detection)\nif [ -n \"$EXPECTED_HEAD\" ]; then\n CURRENT_HEAD=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}\" --jq '.head.sha')\n if [ \"$CURRENT_HEAD\" != \"$EXPECTED_HEAD\" ]; then\n echo \"⚠️ WARNING: PR head has changed since review started!\"\n echo \" Review started at: ${EXPECTED_HEAD:0:7}\"\n echo \" Current head: ${CURRENT_HEAD:0:7}\"\n echo \" Line numbers below may not match the commit being reviewed.\"\n echo \"\"\n fi\nfi\n\n# Thresholds for \"too big\" - show file list only if exceeded\nMAX_FILES=25\nMAX_TOTAL_LINES=1500\n\nFILE=\"$1\"\n\n# Function to add line numbers to a patch\n# Format: [LINE] +added | [LINE] context | [----] -deleted\nadd_line_numbers() {\n awk '\n BEGIN { new_line = 0 }\n /^@@/ {\n # Parse hunk header: @@ -old_start,old_count +new_start,new_count @@\n match($0, /\\+([0-9]+)/)\n new_line = substr($0, RSTART+1, RLENGTH-1) - 1\n print \"\"\n print $0\n next\n }\n /^-/ {\n # Deleted line - cannot comment on these\n printf \"[----] %s\\n\", $0\n next\n }\n /^\\+/ {\n # Added line - can comment, show line number\n new_line++\n printf \"[%4d] %s\\n\", new_line, $0\n next\n }\n {\n # Context line (space prefix) - can comment, show line number\n new_line++\n printf \"[%4d] %s\\n\", new_line, $0\n }\n '\n}\n\nif [ -z \"$FILE\" ]; then\n # Get file list with stats\n FILES_DATA=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}/files\" --paginate)\n \n FILE_COUNT=$(echo \"$FILES_DATA\" | jq 'length')\n TOTAL_ADDITIONS=$(echo \"$FILES_DATA\" | jq '[.[].additions] | add // 0')\n TOTAL_DELETIONS=$(echo \"$FILES_DATA\" | jq '[.[].deletions] | add // 0')\n TOTAL_LINES=$((TOTAL_ADDITIONS + TOTAL_DELETIONS))\n \n echo \"PR #${PR_NUMBER} Summary: ${FILE_COUNT} files changed (+${TOTAL_ADDITIONS}/-${TOTAL_DELETIONS})\"\n echo \"\"\n \n # Check if diff is too large\n if [ \"$FILE_COUNT\" -gt \"$MAX_FILES\" ] || [ \"$TOTAL_LINES\" -gt \"$MAX_TOTAL_LINES\" ]; then\n echo \"⚠️ Large diff detected (>${MAX_FILES} files or >${MAX_TOTAL_LINES} lines changed)\"\n echo \" Review files individually using: pr-diff.sh \"\n echo \"\"\n echo \"Files changed:\"\n echo \"$FILES_DATA\" | jq -r '.[] | \" \\(.filename) (+\\(.additions)/-\\(.deletions))\"'\n else\n # Small enough - show all diffs with line numbers\n echo \"Files changed:\"\n echo \"$FILES_DATA\" | jq -r '.[] | \" \\(.filename) (+\\(.additions)/-\\(.deletions))\"'\n echo \"\"\n echo \"─────────────────────────────────────────────────────────────────────\"\n echo \"\"\n \n # Show each file's diff by iterating over indices\n for i in $(seq 0 $((FILE_COUNT - 1))); do\n FNAME=$(echo \"$FILES_DATA\" | jq -r \".[$i].filename\")\n PATCH=$(echo \"$FILES_DATA\" | jq -r \".[$i].patch // empty\")\n \n if [ -n \"$PATCH\" ]; then\n echo \"## ${FNAME}\"\n echo \"Use: pr-comment.sh ${FNAME} --severity --title \\\"desc\\\" --why \\\"reason\\\" <<'EOF' ... EOF\"\n echo \"Format: [LINE] +added | [LINE] context | [----] -deleted (can't comment)\"\n echo \"$PATCH\" | add_line_numbers\n echo \"\"\n echo \"─────────────────────────────────────────────────────────────────────\"\n echo \"\"\n fi\n done\n fi\nelse\n # Show specific file diff\n PATCH=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}/files\" --paginate --jq --arg file \"$FILE\" '.[] | select(.filename==$file) | .patch')\n \n if [ -z \"$PATCH\" ]; then\n echo \"Error: File '${FILE}' not found in PR diff\"\n echo \"\"\n echo \"Files changed in this PR:\"\n gh api \"repos/${REPO}/pulls/${PR_NUMBER}/files\" --paginate --jq '.[].filename'\n exit 1\n fi\n \n echo \"## ${FILE}\"\n echo \"Use: pr-comment.sh ${FILE} --severity --title \\\"desc\\\" --why \\\"reason\\\" <<'EOF' ... EOF\"\n echo \"Format: [LINE] +added | [LINE] context | [----] -deleted (can't comment)\"\n echo \"$PATCH\" | add_line_numbers\nfi\n" }, { "path": ".github/scripts/pr-review/pr-existing-comments.sh", "content": "#!/bin/bash\n# pr-existing-comments.sh - Fetch existing review threads on a PR\n#\n# Usage:\n# pr-existing-comments.sh - Show all review threads with full details\n# pr-existing-comments.sh --summary - Show per-file summary only (for large PRs)\n# pr-existing-comments.sh --unresolved - Show only unresolved threads\n# pr-existing-comments.sh --file - Show threads for a specific file\n# pr-existing-comments.sh --full - Show full comment text (no truncation)\n#\n# Output: Formatted summary of existing review threads grouped by file,\n# showing thread status, comments, and whether issues were addressed.\n#\n# For large PRs, use --summary first to see the overview, then --file \n# to get full thread details when reviewing each file.\n#\n# Environment variables (set by the composite action):\n# PR_REVIEW_REPO - Repository (owner/repo)\n# PR_REVIEW_PR_NUMBER - Pull request number\n\nset -e\n\n# Configuration from environment\nREPO=\"${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}\"\nPR_NUMBER=\"${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}\"\n\nOWNER=\"${REPO%/*}\"\nREPO_NAME=\"${REPO#*/}\"\n\n# Parse arguments\nFILTER_UNRESOLVED=false\nFILTER_FILE=\"\"\nSUMMARY_ONLY=false\nFULL_TEXT=false\n\nwhile [ $# -gt 0 ]; do\n case \"$1\" in\n --unresolved)\n FILTER_UNRESOLVED=true\n shift\n ;;\n --file)\n FILTER_FILE=\"$2\"\n shift 2\n ;;\n --summary)\n SUMMARY_ONLY=true\n shift\n ;;\n --full)\n FULL_TEXT=true\n shift\n ;;\n *)\n echo \"Usage: pr-existing-comments.sh [--summary] [--unresolved] [--file ] [--full]\"\n exit 1\n ;;\n esac\ndone\n\n# Fetch review threads via GraphQL\nTHREADS=$(gh api graphql -f query='\n query($owner: String!, $repo: String!, $prNumber: Int!) {\n repository(owner: $owner, name: $repo) {\n pullRequest(number: $prNumber) {\n reviewThreads(first: 100) {\n nodes {\n id\n isResolved\n isOutdated\n path\n line\n originalLine\n startLine\n originalStartLine\n diffSide\n comments(first: 50) {\n nodes {\n id\n body\n author { login }\n createdAt\n originalCommit { abbreviatedOid }\n }\n }\n }\n }\n }\n }\n }' -F owner=\"$OWNER\" \\\n -F repo=\"$REPO_NAME\" \\\n -F prNumber=\"$PR_NUMBER\" \\\n --jq '.data.repository.pullRequest.reviewThreads.nodes')\n\nif [ -z \"$THREADS\" ] || [ \"$THREADS\" = \"null\" ]; then\n echo \"No existing review threads found.\"\n exit 0\nfi\n\n# Apply filters\nFILTERED=\"$THREADS\"\n\nif [ \"$FILTER_UNRESOLVED\" = true ]; then\n FILTERED=$(echo \"$FILTERED\" | jq '[.[] | select(.isResolved == false)]')\nfi\n\nif [ -n \"$FILTER_FILE\" ]; then\n FILTERED=$(echo \"$FILTERED\" | jq --arg file \"$FILTER_FILE\" '[.[] | select(.path == $file)]')\nfi\n\nTHREAD_COUNT=$(echo \"$FILTERED\" | jq 'length')\n\nif [ \"$THREAD_COUNT\" -eq 0 ]; then\n if [ \"$FILTER_UNRESOLVED\" = true ]; then\n echo \"No unresolved review threads found.\"\n elif [ -n \"$FILTER_FILE\" ]; then\n echo \"No review threads found for ${FILTER_FILE}.\"\n else\n echo \"No existing review threads found.\"\n fi\n exit 0\nfi\n\n# Count resolved vs unresolved\nRESOLVED_COUNT=$(echo \"$FILTERED\" | jq '[.[] | select(.isResolved == true)] | length')\nUNRESOLVED_COUNT=$(echo \"$FILTERED\" | jq '[.[] | select(.isResolved == false)] | length')\nOUTDATED_COUNT=$(echo \"$FILTERED\" | jq '[.[] | select(.isOutdated == true)] | length')\n\necho \"Existing review threads: ${THREAD_COUNT} total (${UNRESOLVED_COUNT} unresolved, ${RESOLVED_COUNT} resolved, ${OUTDATED_COUNT} outdated)\"\necho \"\"\n\n# Summary mode: show per-file counts only\nif [ \"$SUMMARY_ONLY\" = true ]; then\n echo \"Threads by file:\"\n echo \"$FILTERED\" | jq -r '\n group_by(.path) | .[] |\n . as $threads |\n ($threads | length) as $total |\n ([$threads[] | select(.isResolved == false)] | length) as $unresolved |\n ([$threads[] | select(.isResolved == true)] | length) as $resolved |\n ([$threads[] | select(.isOutdated == true)] | length) as $outdated |\n ([$threads[] | select(.comments.nodes | length > 1)] | length) as $has_replies |\n \" \" + $threads[0].path +\n \" — \" + ($total | tostring) + \" threads\" +\n \" (\" + ($unresolved | tostring) + \" unresolved, \" + ($resolved | tostring) + \" resolved\" +\n (if $outdated > 0 then \", \" + ($outdated | tostring) + \" outdated\" else \"\" end) +\n \")\" +\n (if $has_replies > 0 then \" ⚠️ \" + ($has_replies | tostring) + \" with replies\" else \"\" end)\n '\n echo \"\"\n echo \"Use: pr-existing-comments.sh --file to see full thread details for a file\"\n exit 0\nfi\n\n# Full detail mode: output threads grouped by file\n# Show full conversation for threads with replies\nFIRST_LIMIT=200\nREPLY_LIMIT=300\nif [ \"$FULL_TEXT\" = true ]; then\n FIRST_LIMIT=999999\n REPLY_LIMIT=999999\nfi\n\necho \"$FILTERED\" | jq -r --argjson first_limit \"$FIRST_LIMIT\" --argjson reply_limit \"$REPLY_LIMIT\" '\n group_by(.path) | .[] |\n \"## \" + .[0].path + \" (\" + (length | tostring) + \" threads)\\n\" +\n ([.[] |\n \" \" +\n (if .isResolved then \"✅ RESOLVED\" elif .isOutdated then \"⚠️ OUTDATED\" else \"🔴 UNRESOLVED\" end) +\n \" (line \" + (if .line then (.line | tostring) elif .startLine then (.startLine | tostring) elif .originalLine then (\"~\" + (.originalLine | tostring)) elif .originalStartLine then (\"~\" + (.originalStartLine | tostring)) else \"?\" end) + \")\" +\n # Show the commit the comment was originally made on\n (if .comments.nodes[0].originalCommit.abbreviatedOid then \" [\" + .comments.nodes[0].originalCommit.abbreviatedOid + \"]\" else \"\" end) +\n # Flag threads with replies — indicates a conversation happened\n (if (.comments.nodes | length) > 1 then \" ← has replies\" else \"\" end) +\n \"\\n\" +\n ([.comments.nodes | to_entries[] |\n .value as $comment |\n .key as $idx |\n ($comment.body | gsub(\"\\n\"; \" \")) as $flat |\n if $idx == 0 then\n \" @\" + ($comment.author.login // \"unknown\") + \": \" + $flat[0:$first_limit] +\n (if ($flat | length) > $first_limit then \" [truncated]\" else \"\" end)\n else\n \" ↳ @\" + ($comment.author.login // \"unknown\") + \": \" + $flat[0:$reply_limit] +\n (if ($flat | length) > $reply_limit then \" [truncated]\" else \"\" end)\n end\n ] | join(\"\\n\")) +\n \"\\n\"\n ] | join(\"\\n\"))\n'\n" }, { "path": ".github/scripts/pr-review/pr-remove-comment.sh", "content": "#!/bin/bash\n# pr-remove-comment.sh - Remove a queued review comment\n#\n# Usage:\n# pr-remove-comment.sh \n# pr-remove-comment.sh \n#\n# Examples:\n# pr-remove-comment.sh src/main.go 42\n# pr-remove-comment.sh comment-1234567890-1234567890\n#\n# This script removes a previously queued comment before it's submitted.\n# Useful if the agent realizes it made a mistake or wants to update a comment.\n#\n# Environment variables (set by the composite action):\n# PR_REVIEW_COMMENTS_DIR - Directory containing comment files (default: /tmp/pr-review-comments)\n\nset -e\n\nCOMMENTS_DIR=\"${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}\"\n\nif [ ! -d \"${COMMENTS_DIR}\" ]; then\n echo \"No comments directory found: ${COMMENTS_DIR}\"\n exit 0\nfi\n\n# Check if first argument looks like a comment ID\nif [[ \"$1\" =~ ^comment- ]]; then\n COMMENT_ID=\"$1\"\n COMMENT_FILE=\"${COMMENTS_DIR}/${COMMENT_ID}.json\"\n \n if [ -f \"${COMMENT_FILE}\" ]; then\n FILE=$(jq -r '._meta.file // .path' \"${COMMENT_FILE}\")\n LINE=$(jq -r '._meta.line // .line' \"${COMMENT_FILE}\")\n rm -f \"${COMMENT_FILE}\"\n echo \"✓ Removed comment ${COMMENT_ID} for ${FILE}:${LINE}\"\n else\n echo \"Comment not found: ${COMMENT_ID}\"\n exit 1\n fi\nelse\n # Treat as file and line number\n FILE=\"$1\"\n LINE=\"$2\"\n \n if [ -z \"$FILE\" ] || [ -z \"$LINE\" ]; then\n echo \"Usage:\"\n echo \" pr-remove-comment.sh \"\n echo \" pr-remove-comment.sh \"\n echo \"\"\n echo \"Examples:\"\n echo \" pr-remove-comment.sh src/main.go 42\"\n echo \" pr-remove-comment.sh comment-1234567890-1234567890\"\n exit 1\n fi\n \n # Validate line is a positive integer (>= 1)\n if ! [[ \"$LINE\" =~ ^[1-9][0-9]*$ ]]; then\n echo \"Error: Line number must be a positive integer (>= 1), got: $LINE\"\n exit 1\n fi\n \n # Find and remove matching comment files\n # Use nullglob to handle case where no files match\n shopt -s nullglob\n REMOVED=0\n for COMMENT_FILE in \"${COMMENTS_DIR}\"/comment-*.json; do\n \n COMMENT_FILE_PATH=$(jq -r '._meta.file // .path' \"${COMMENT_FILE}\")\n COMMENT_LINE=$(jq -r '._meta.line // .line' \"${COMMENT_FILE}\")\n \n if [ \"$COMMENT_FILE_PATH\" = \"$FILE\" ] && [ \"$COMMENT_LINE\" = \"$LINE\" ]; then\n COMMENT_ID=$(basename \"${COMMENT_FILE}\" .json)\n rm -f \"${COMMENT_FILE}\"\n echo \"✓ Removed comment ${COMMENT_ID} for ${FILE}:${LINE}\"\n REMOVED=$((REMOVED + 1))\n fi\n done\n \n if [ \"$REMOVED\" -eq 0 ]; then\n echo \"No comment found for ${FILE}:${LINE}\"\n exit 1\n fi\nfi\n" }, { "path": ".github/scripts/pr-review/pr-review.sh", "content": "#!/bin/bash\n# pr-review.sh - Submit a PR review (approve, request changes, or comment)\n#\n# Usage: pr-review.sh [review-body]\n# Example: pr-review.sh REQUEST_CHANGES \"Please fix the issues noted above\"\n#\n# This script creates and submits a review with any queued inline comments.\n# Comments are read from individual files in PR_REVIEW_COMMENTS_DIR (created by pr-comment.sh).\n#\n# The review body can contain special characters (backticks, dollar signs, etc.)\n# and will be safely passed to the GitHub API without shell interpretation.\n#\n# Environment variables (set by the composite action):\n# PR_REVIEW_REPO - Repository (owner/repo)\n# PR_REVIEW_PR_NUMBER - Pull request number\n# PR_REVIEW_HEAD_SHA - HEAD commit SHA\n# PR_REVIEW_COMMENTS_DIR - Directory containing queued comment files (default: /tmp/pr-review-comments)\n\nset -e\n\n# Configuration from environment\nREPO=\"${PR_REVIEW_REPO:?PR_REVIEW_REPO environment variable is required}\"\nPR_NUMBER=\"${PR_REVIEW_PR_NUMBER:?PR_REVIEW_PR_NUMBER environment variable is required}\"\nHEAD_SHA=\"${PR_REVIEW_HEAD_SHA:?PR_REVIEW_HEAD_SHA environment variable is required}\"\nCOMMENTS_DIR=\"${PR_REVIEW_COMMENTS_DIR:-/tmp/pr-review-comments}\"\n\n# Arguments\nEVENT=\"$1\"\nshift 2>/dev/null || true\n\n# Read body from remaining arguments\n# Join all remaining arguments with spaces, preserving the string as-is\nBODY=\"$*\"\n\nif [ -z \"$EVENT\" ]; then\n echo \"Usage: pr-review.sh [review-body]\"\n echo \"Example: pr-review.sh REQUEST_CHANGES 'Please fix the issues noted in the inline comments'\"\n exit 1\nfi\n\n# Validate event type\ncase \"$EVENT\" in\n APPROVE|REQUEST_CHANGES|COMMENT)\n ;;\n *)\n echo \"Error: Invalid event type '${EVENT}'\"\n echo \"Must be one of: APPROVE, REQUEST_CHANGES, COMMENT\"\n exit 1\n ;;\nesac\n\n# Read queued comments from individual files\nCOMMENTS=\"[]\"\nCOMMENT_COUNT=0\n\nif [ -d \"${COMMENTS_DIR}\" ]; then\n # Collect all comment files and merge into a single JSON array\n # Remove _meta fields before submitting (they're only for internal use)\n COMMENT_FILES=(\"${COMMENTS_DIR}\"/comment-*.json)\n \n if [ -f \"${COMMENT_FILES[0]}\" ]; then\n # Use jq to read all comment files, extract the comment data (without _meta), and combine\n COMMENTS=$(jq -s '[.[] | del(._meta)]' \"${COMMENTS_DIR}\"/comment-*.json)\n COMMENT_COUNT=$(echo \"$COMMENTS\" | jq 'length')\n if [ \"$COMMENT_COUNT\" -gt 0 ]; then\n echo \"Found ${COMMENT_COUNT} queued inline comment(s)\"\n fi\n fi\nfi\n\n# Append standard footer to the review body (if body is provided)\nFOOTER='\n\n---\nMarvin Context Protocol | Type `/marvin` to interact further\n\nGive us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.'\n\nif [ -n \"$BODY\" ]; then\n BODY_WITH_FOOTER=\"${BODY}${FOOTER}\"\nelse\n BODY_WITH_FOOTER=\"\"\nfi\n\n# Build the review request JSON\n# Use jq to safely construct the JSON with all special characters handled\nREVIEW_JSON=$(jq -n \\\n --arg commit_id \"$HEAD_SHA\" \\\n --arg event \"$EVENT\" \\\n --arg body \"$BODY_WITH_FOOTER\" \\\n --argjson comments \"$COMMENTS\" \\\n '{\n commit_id: $commit_id,\n event: $event,\n comments: $comments\n } + (if $body != \"\" then {body: $body} else {} end)')\n\n# Check if HEAD has changed since review started (race condition detection)\nCURRENT_HEAD=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}\" --jq '.head.sha')\nif [ \"$CURRENT_HEAD\" != \"$HEAD_SHA\" ]; then\n echo \"⚠️ WARNING: PR head has changed since review started!\"\n echo \" Review started at: ${HEAD_SHA:0:7}\"\n echo \" Current head: ${CURRENT_HEAD:0:7}\"\n echo \"\"\n echo \" New commits may have shifted line numbers. Review will be submitted\"\n echo \" against the original commit (${HEAD_SHA:0:7}) but comments may be outdated.\"\n echo \"\"\nfi\n\necho \"Submitting ${EVENT} review for commit ${HEAD_SHA:0:7}...\"\n\n# Create and submit the review in one API call\n# Use a temp file to safely pass the JSON body\nTEMP_JSON=$(mktemp)\ntrap \"rm -f ${TEMP_JSON}\" EXIT\necho \"$REVIEW_JSON\" > \"${TEMP_JSON}\"\n\nRESPONSE=$(gh api \"repos/${REPO}/pulls/${PR_NUMBER}/reviews\" \\\n -X POST \\\n --input \"${TEMP_JSON}\" 2>&1) || {\n echo \"Error submitting review:\"\n echo \"$RESPONSE\"\n exit 1\n}\n\n# Clean up the comments directory after successful submission\nif [ -d \"${COMMENTS_DIR}\" ] && [ \"$COMMENT_COUNT\" -gt 0 ]; then\n rm -f \"${COMMENTS_DIR}\"/comment-*.json\n # Remove directory if empty\n rmdir \"${COMMENTS_DIR}\" 2>/dev/null || true\nfi\n\nREVIEW_URL=$(echo \"$RESPONSE\" | jq -r '.html_url // empty')\nREVIEW_STATE=$(echo \"$RESPONSE\" | jq -r '.state // empty')\n\nif [ -n \"$REVIEW_URL\" ]; then\n echo \"✓ Review submitted (${REVIEW_STATE}): ${REVIEW_URL}\"\n if [ \"$COMMENT_COUNT\" -gt 0 ]; then\n echo \" Included ${COMMENT_COUNT} inline comment(s)\"\n fi\nelse\n echo \"✓ Review submitted successfully\"\nfi\n" }, { "path": ".github/workflows/auto-close-duplicates.yml", "content": "name: Auto-close duplicate issues\ndescription: Auto-closes issues that are duplicates of existing issues\non:\n schedule:\n - cron: \"0 9 * * *\" # Run daily at 9 AM UTC\n workflow_dispatch:\n\njobs:\n auto-close-duplicates:\n runs-on: ubuntu-latest\n timeout-minutes: 10\n permissions:\n contents: read\n issues: write\n id-token: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n\n - name: Auto-close duplicate issues\n run: uv run scripts/auto_close_duplicates.py\n env:\n GITHUB_TOKEN: ${{ steps.marvin-token.outputs.token }}\n GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}\n GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}\n" }, { "path": ".github/workflows/auto-close-needs-mre.yml", "content": "name: Auto-close needs MRE issues\ndescription: Auto-closes issues that need minimal reproducible examples after 7 days of author inactivity\non:\n schedule:\n - cron: \"0 9 * * *\" # Run daily at 9 AM UTC\n workflow_dispatch:\n\njobs:\n auto-close-needs-mre:\n runs-on: ubuntu-latest\n timeout-minutes: 10\n permissions:\n contents: read\n issues: write\n id-token: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n\n - name: Auto-close needs MRE issues\n run: uv run scripts/auto_close_needs_mre.py\n env:\n GITHUB_TOKEN: ${{ steps.marvin-token.outputs.token }}\n GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}\n GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}\n" }, { "path": ".github/workflows/martian-test-failure.yml", "content": "name: Marvin Test Failure Analysis\n\non:\n workflow_run:\n workflows: [\"Tests\", \"Run static analysis\"]\n types:\n - completed\n\nconcurrency:\n group: marvin-test-failure-${{ github.event.workflow_run.head_branch }}\n cancel-in-progress: true\n\njobs:\n martian-test-failure:\n # Only run if the test workflow failed\n if: ${{ github.event.workflow_run.conclusion == 'failure' }}\n runs-on: ubuntu-latest\n permissions:\n contents: read\n pull-requests: write\n issues: read\n id-token: write\n actions: read # Required for Claude to read CI results\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n with:\n fetch-depth: 1\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: Set up Python 3.10\n uses: actions/setup-python@v6\n with:\n python-version: \"3.10\"\n\n # Install UV package manager\n - name: Install UV\n uses: astral-sh/setup-uv@v7\n\n # Install dependencies\n - name: Install dependencies\n run: uv sync --all-packages --group dev\n\n - name: Set analysis prompt\n id: analysis-prompt\n run: |\n cat >> $GITHUB_OUTPUT << 'EOF'\n PROMPT<\n Detailed Analysis\n\n Include here:\n - Relevant log excerpts showing the failure\n - Code snippets that are causing the issue\n - Any related issues or PRs that might be relevant\n \n\n
\n Related Files\n\n List files that are relevant to the failure with brief explanations of their relevance.\n
\n\n # Important Guidelines\n - Be concise and actionable - developers want to quickly understand and fix the issue. Provide\n additional context, references, etc in collapsible details blocks to ensure that the comment you're adding\n is short and easy to read but additional information is a click away.\n - Focus on facts from the logs and code, not speculation\n - If you can't determine the root cause, say so clearly\n - If your only suggestion is a bad suggestion (disable the test, change the timeout, etc), indicate that you've run out of ideas and\n that they probably don't want to do that.\n - Provide specific file names, line numbers, and code references when possible\n - You can run make commands (e.g., `make lint`, `make typecheck`, `make sync`) to build, test, or lint the code\n - You can also run git commands (e.g., `git status`, `git log`, `git diff`) to inspect the repository\n - You can use WebSearch and WebFetch to research errors, stack traces, or related issues\n - For bash commands, you are limited to make and git commands only\n\n # CRITICAL: ANGRY USERS\n **IMPORTANT**: If the user is angry with you, the triage bot, don't respond. Just exit immediately without further action.\n If at any point in the conversation the user has asked you to stop replying to the thread, just exit immediately.\n\n If you are posting the same suggestion as you have previously made, do not post the suggestion again.\n\n # IMPORTANT: EDIT YOUR COMMENT\n Do not post a new comment every time you triage a failing workflow. If a previous comment has been posted by you (marvin)\n 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\n your comment to reflect the latest analysis. Don't worry about keeping the old content around, there's comment history for \n that.\n\n # Problems Encountered\n 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.\n PROMPT_END\n EOF\n\n - name: Setup GitHub MCP Server\n run: |\n mkdir -p /tmp/mcp-config\n cat > /tmp/mcp-config/mcp-servers.json << 'EOF'\n {\n \"mcpServers\": {\n \"repository-summary\": {\n \"type\": \"http\",\n \"url\": \"https://agents-md-generator.fastmcp.app/mcp\"\n },\n \"code-search\": {\n \"type\": \"http\",\n \"url\": \"https://public-code-search.fastmcp.app/mcp\"\n },\n \"github-research\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\n \"github-research-mcp\"\n ],\n \"env\": {\n \"DISABLE_SUMMARIES\": \"true\",\n \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${{ secrets.GITHUB_TOKEN }}\"\n }\n }\n }\n }\n EOF\n\n - name: Clean up stale Claude locks\n run: rm -rf ~/.claude/.locks ~/.local/state/claude/locks || true\n\n - name: Run Claude Code\n id: claude\n uses: anthropics/claude-code-action@v1\n with:\n github_token: ${{ steps.marvin-token.outputs.token }}\n anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY_FOR_CI }}\n bot_name: \"Marvin Context Protocol\"\n\n claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n\n additional_permissions: |\n actions: read\n\n prompt: ${{ steps.analysis-prompt.outputs.PROMPT }}\n claude_args: |\n --allowed-tools mcp__repository-summary,mcp__code-search,mcp__github-research,WebSearch,WebFetch,Bash(make:*,git:*)\n --mcp-config /tmp/mcp-config/mcp-servers.json\n" }, { "path": ".github/workflows/martian-triage-issue.yml", "content": "# Triage new issues: investigate, recommend, apply labels\n# Calls run-claude directly with triage prompt (elastic issue-triage style)\n\nname: Triage Issue\n\non:\n issues:\n types: [opened]\n\njobs:\n triage:\n if: |\n github.event.issue.user.login == 'strawgate' ||\n (github.event.issue.user.login == 'jlowin' && contains(toJSON(github.event.issue.labels.*.name), 'bug'))\n concurrency:\n group: triage-issue-${{ github.event.issue.number }}\n cancel-in-progress: true\n\n runs-on: ubuntu-latest\n timeout-minutes: 10\n permissions:\n contents: read\n issues: write\n pull-requests: read\n id-token: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n with:\n repository: ${{ github.repository }}\n ref: ${{ github.event.repository.default_branch }}\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: React to issue with eyes\n env:\n GH_TOKEN: ${{ steps.marvin-token.outputs.token }}\n run: |\n gh api \"repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/reactions\" -f content=eyes 2>/dev/null || true\n\n - name: Run Claude for Triage\n uses: ./.github/actions/run-claude\n with:\n claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n github-token: ${{ steps.marvin-token.outputs.token }}\n 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\"\n prompt: |\n \n Repository: ${{ github.repository }}\n Issue Number: #${{ github.event.issue.number }}\n Issue Title: ${{ github.event.issue.title }}\n Issue Author: ${{ github.event.issue.user.login }}\n \n\n \n ${{ github.event.issue.body }}\n \n\n \n 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.\n \n\n \n This workflow is for investigation, testing, and planning.\n\n You CANNOT: Create branches, checkout branches, commit code to the repository\n Do not push changes to the repository.\n You CAN: Read/analyze code, search repository, review git history, search for similar issues, write files, verify behavior, provide analysis and recommendations\n \n\n \n You have access to the following tools (comma-separated list):\n\n 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\n\n 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.\n \n\n \n Use `mcp__agents-md-generator__generate_agents_md` to get repository context before triaging.\n \n\n \n - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)\n - `WebSearch`: Search the web for documentation, best practices, or solutions\n - `WebFetch`: Fetch and read content from URLs\n - Git commands: You have access to git commands, but write commands (commit, push, checkout, branch creation) are blocked\n - Write: You can write files (e.g., test files, temporary files for verification)\n - Execution: See `` section above for exact list of available execution commands\n \n\n \n If execution commands are available (check `` section), you can:\n - Run tests to verify reported bugs or test proposed solutions\n - Execute scripts to understand behavior\n - Run linters or static analysis tools\n - Verify environment setup or dependencies\n - Test specific code paths or scenarios\n - Write test files to confirm behavior\n\n When executing commands:\n - Explain what you're testing and why\n - Include command output in your response when relevant\n - Use execution to validate your findings and recommendations\n - Only use commands that are explicitly listed in ``\n \n\n \n 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.\n\n In priority order your goal is to:\n 1. Provide context about the request or issue (related issues, pull requests, files, etc.)\n 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\n 3. Provide a high quality and detailed plan that a junior developer could follow to implement the recommendation\n 4. Use execution to verify findings when appropriate (check `` section for available commands)\n \n\n \n Populate the following sections in your response:\n Recommendation (or \"No recommendation\" with reason)\n Findings\n Verification (if you executed tests or commands - check `` section)\n Detailed Action Plan\n Related Items\n Related Files\n Related Webpages\n\n 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.\n\n 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
and 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.\n\n \n \n # Example output for \"Recommendation\" part of the response\n 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.\n\n
\n Findings\n ...details from the code analysis that are relevant to the issue and the recommendation...\n
\n\n
\n Verification\n I ran the existing tests (if execution commands are available in ``) and confirmed the current behavior:\n ```bash\n $ pytest test_calculator.py::test_divide_by_zero\n FAILED - raises ValueError instead of DivisionByZeroError\n ```\n This confirms the issue report is accurate.\n
\n\n
\n Detailed Action Plan\n ...a detailed plan that a junior developer could follow to implement the recommendation...\n
\n\n # Example Output for \"Related Items\" part of the response\n\n
\n Related Issues and Pull Requests\n\n | Repository | Issue or PR | Relevance |\n | --- | --- | --- |\n | 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. |\n | 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. |\n
\n\n
\n Related Files\n\n | Repository | File | Relevance | Sections |\n | --- | --- | --- | --- |\n | 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) |\n | 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) |\n
\n\n
\n Related Webpages\n\n | Name | URL | Relevance |\n | --- | --- | --- |\n | 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. |\n
\n \n\n \n Always end your comment with a new line, three dashes, and the footer message:\n \n\n ---\n Marvin Context Protocol | Type `/marvin` to interact further\n\n Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.\n \n \n\n \n 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.\n \n" }, { "path": ".github/workflows/marvin-comment-on-issue.yml", "content": "# Respond to /marvin mentions in issue comments (elastic mention-in-issue style)\n# Calls run-claude directly\n\nname: Comment on Issue\n\non:\n issue_comment:\n types: [created]\n\npermissions:\n actions: read\n contents: write\n issues: write\n pull-requests: write\n id-token: write\n\njobs:\n comment:\n if: |\n !github.event.issue.pull_request &&\n contains(github.event.comment.body, '/marvin') &&\n contains(fromJSON('[\"OWNER\", \"MEMBER\", \"COLLABORATOR\"]'), github.event.comment.author_association)\n runs-on: ubuntu-latest\n timeout-minutes: 60\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n\n - name: Install UV\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n cache-dependency-glob: \"uv.lock\"\n\n - name: Install dependencies\n run: uv sync --python 3.12\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: React to comment with eyes\n env:\n GH_TOKEN: ${{ steps.marvin-token.outputs.token }}\n run: |\n gh api \"repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions\" -f content=eyes 2>/dev/null || true\n\n - name: Run Claude for Issue Comment\n uses: ./.github/actions/run-claude\n with:\n claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n github-token: ${{ steps.marvin-token.outputs.token }}\n trigger-phrase: \"/marvin\"\n allowed-bots: \"*\"\n 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\"\n prompt: |\n \n Repository: ${{ github.repository }}\n Issue Number: #${{ github.event.issue.number }}\n Issue Title: ${{ github.event.issue.title }}\n Issue Author: ${{ github.event.issue.user.login }}\n Comment Author: ${{ github.event.comment.user.login }}\n \n\n \n ${{ github.event.comment.body }}\n \n\n \n You have been mentioned in a GitHub issue comment. Understand the request, gather context, complete the task, and respond with results.\n \n\n \n You CAN: Read/analyze code, modify files, write code, run tests, execute commands\n You CAN: Commit code, push changes, create branches, create pull requests\n\n \n\n \n You have access to the following tools (comma-separated list):\n\n 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\n\n 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.\n \n\n \n Use `mcp__agents-md-generator__generate_agents_md` to get repository context before responding.\n \n\n \n Be thorough in your investigations:\n - Understand the full context of the repository\n - Review related code, issues, and PRs\n - Consider edge cases and implications\n - Gather all relevant information before responding\n\n Available tools:\n - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)\n - `WebSearch`: Search the web for documentation, best practices, or solutions\n - `WebFetch`: Fetch and read content from URLs\n \n\n \n - Answer questions about the codebase\n - Help debug reported problems (make changes locally to test, cannot push)\n - Suggest solutions or workarounds\n - Provide code examples\n - Help clarify requirements\n - Link to relevant documentation or code\n \n\n \n - Be concise and actionable\n - If the request is unclear, ask clarifying questions\n - If the request requires actions you cannot perform (like pushing changes), explain what you can and cannot do\n - When making code changes, explain that they are local only and cannot be pushed\n \n\n \n Always end your comment with a new line, three dashes, and the footer message:\n \n\n ---\n Marvin Context Protocol | Type `/marvin` to interact further\n\n Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.\n \n \n\n \n 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.\n \n" }, { "path": ".github/workflows/marvin-comment-on-pr.yml", "content": "# Respond to /marvin mentions in PR review comments and issue comments on PRs\n# Calls run-claude directly\n\nname: Comment on PR\n\non:\n issue_comment:\n types: [created]\n\npermissions:\n contents: write\n pull-requests: write\n issues: read\n id-token: write\n\njobs:\n comment:\n if: |\n github.event.issue.pull_request &&\n contains(github.event.comment.body, '/marvin') &&\n contains(fromJSON('[\"OWNER\", \"MEMBER\", \"COLLABORATOR\"]'), github.event.comment.author_association)\n runs-on: ubuntu-latest\n timeout-minutes: 15\n\n steps:\n - name: Checkout PR head branch\n uses: actions/checkout@v6\n with:\n # do not set to pull_request.head.ref, claude will pull the branch if needed\n fetch-depth: 0\n\n - name: Install UV\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n cache-dependency-glob: \"uv.lock\"\n\n - name: Install dependencies\n run: uv sync --python 3.12\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: React to comment with eyes\n env:\n GH_TOKEN: ${{ steps.marvin-token.outputs.token }}\n run: |\n gh api \"repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions\" -f content=eyes 2>/dev/null || true\n\n - name: Get PR HEAD SHA\n id: pr-info\n env:\n GH_TOKEN: ${{ steps.marvin-token.outputs.token }}\n run: |\n PR_NUMBER=\"${{ github.event.issue.number }}\"\n HEAD_SHA=$(gh api \"repos/${{ github.repository }}/pulls/${PR_NUMBER}\" --jq '.head.sha')\n echo \"head_sha=${HEAD_SHA}\" >> \"$GITHUB_OUTPUT\"\n echo \"pr_number=${PR_NUMBER}\" >> \"$GITHUB_OUTPUT\"\n\n - name: Run Claude for PR Comment\n uses: ./.github/actions/run-claude\n env:\n MENTION_REPO: ${{ github.repository }}\n MENTION_PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}\n MENTION_SCRIPTS: ${{ github.workspace }}/.github/scripts/mention\n PR_REVIEW_REPO: ${{ github.repository }}\n PR_REVIEW_PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}\n PR_REVIEW_HEAD_SHA: ${{ steps.pr-info.outputs.head_sha }}\n PR_REVIEW_COMMENTS_DIR: /tmp/pr-review-comments\n PR_REVIEW_HELPERS_DIR: ${{ github.workspace }}/.github/scripts/pr-review\n with:\n claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n github-token: ${{ steps.marvin-token.outputs.token }}\n trigger-phrase: \"/marvin\"\n allowed-bots: \"*\"\n 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\"\n prompt: |\n \n Repository: ${{ github.repository }}\n PR Number: #${{ steps.pr-info.outputs.pr_number }}\n PR Title: ${{ github.event.issue.title }}\n PR Author: ${{ github.event.issue.user.login }}\n Comment Author: ${{ github.event.comment.user.login }}\n\n **Note**: The PR head branch has already been checked out. The workspace is ready - you can immediately start working on the PR code.\n \n\n \n ${{ github.event.comment.body }}\n \n\n \n You have been mentioned in a Pull Request comment. Understand the request, gather context, complete the task, and respond with results.\n \n\n \n This workflow allows read, write, and execute capabilities but cannot push changes.\n\n You CAN: Read/analyze code, modify files, write code, run tests, execute commands, resolve review threads\n You CANNOT: Commit code, push changes, create branches, checkout branches, create pull requests\n\n **Important**: You cannot push changes to the repository - you can only make changes locally and provide feedback or recommendations.\n \n\n \n You have access to the following tools (comma-separated list):\n\n 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\n\n 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.\n \n\n \n Use `mcp__agents-md-generator__generate_agents_md` to get repository context before responding.\n \n\n \n Be thorough in your investigations:\n - Understand the full context of the repository\n - Review related code, issues, and PRs\n - Consider edge cases and implications\n - Gather all relevant information before responding\n\n Available tools:\n - `mcp__public-code-search__search_code`: Search code in OTHER repositories (use `Grep`/`Read` for this repo)\n - `WebSearch`: Search the web for documentation, best practices, or solutions\n - `WebFetch`: Fetch and read content from URLs\n \n\n \n - Address review feedback and fix issues (make changes locally, cannot push)\n - Answer questions about the changes\n - Make additional code changes (local only)\n - Resolve review threads after addressing feedback (if changes are made separately)\n - Perform PR reviews when asked (use the PR review process below)\n \n\n \n When asked to review this PR, follow this structured review process.\n The `$PR_REVIEW_HELPERS_DIR` environment variable is pre-configured for all scripts below.\n\n \n Follow these steps in order:\n\n **Step 1: Gather context**\n - Use `mcp__agents-md-generator__generate_agents_md` to get repository context\n (if this fails, explore the repository to understand the codebase — read key files like README, CONTRIBUTING, etc.)\n - Run `$PR_REVIEW_HELPERS_DIR/pr-existing-comments.sh --summary` to see existing review threads per file\n - Run `$PR_REVIEW_HELPERS_DIR/pr-diff.sh` to see changed files with line-numbered diffs\n (for large PRs, this lists files only — review each with `pr-diff.sh `)\n\n **Step 2: Review each file**\n For each changed file:\n a. If the summary showed existing threads for this file, first run:\n `$PR_REVIEW_HELPERS_DIR/pr-existing-comments.sh --file `\n Read the full thread details. The output uses these conventions:\n - `← has replies` — a conversation happened; read carefully before commenting\n - `[truncated]` — comment was cut short; add `--full` if you need the complete text to understand the comment\n - `[abc1234]` — commit the comment was made on; use `git show abc1234` if needed\n - `~42` — approximate line from an older revision (exact line no longer maps to current diff)\n b. Review the diff. Use `Read` to see full file contents when you need more context.\n Identify issues matching review_criteria. Do NOT flag:\n - Issues in unchanged code (only review the diff)\n - Style preferences handled by linters\n - Pre-existing issues not introduced by this PR\n - Issues already covered by existing threads (see below)\n\n **Existing thread rules** (check BEFORE leaving any comment):\n - Resolved with reviewer reply → reviewer's decision is final. Do NOT re-flag.\n Examples: \"It should remain as X\", \"This is intentional\", \"No need to do this change\"\n - Resolved without reply → author likely fixed it. Do NOT re-raise unless the fix introduced a new problem.\n - Unresolved → already flagged. Do NOT re-comment. Mention in review body if you have more to add.\n - Outdated → code changed. Only re-flag if the issue still applies to the current diff.\n When in doubt, do not duplicate. Redundant comments erode trust in the review process.\n\n **Step 3: Leave comments for NEW issues only**\n For each genuinely new issue not covered by existing threads:\n ```bash\n $PR_REVIEW_HELPERS_DIR/pr-comment.sh \\\n --severity \\\n --title \"Brief description\" \\\n --why \"Risk or impact\" <<'EOF'\n corrected code here\n EOF\n ```\n Always provide suggestion code. Use `--no-suggestion` only when the fix requires\n changes across multiple locations. Broader architectural concerns belong in the\n review body, not inline comments.\n\n To remove a queued comment: `$PR_REVIEW_HELPERS_DIR/pr-remove-comment.sh `\n\n **Step 4: Submit the review**\n ```bash\n $PR_REVIEW_HELPERS_DIR/pr-review.sh \"\"\n ```\n - REQUEST_CHANGES: Any 🔴 CRITICAL or 🟠 HIGH issues found\n - COMMENT: 🟡 MEDIUM issues found (but no critical/high)\n - APPROVE: No issues, or only ⚪ LOW / 💬 NITPICK suggestions\n\n The review body should include broader architectural concerns not suited for inline comments.\n Avoid summarizing the PR or offering praise. If approving with no issues, omit the review body.\n A standard footer is automatically appended to all comments and reviews.\n \n\n \n 🔴 CRITICAL - Must fix before merge (security vulnerabilities, data corruption, production-breaking bugs)\n 🟠 HIGH - Should fix before merge (logic errors, missing validation, significant performance issues)\n 🟡 MEDIUM - Address soon, non-blocking (error handling gaps, suboptimal patterns, missing edge cases)\n ⚪ LOW - Author discretion, non-blocking (minor improvements, documentation, style not covered by linters)\n 💬 NITPICK - Truly optional (stylistic preferences, alternative approaches — safe to ignore)\n \n\n \n Focus on these categories, in priority order:\n 1. Security vulnerabilities (injection, XSS, auth bypass, secrets exposure)\n 2. Logic bugs that could cause runtime failures or incorrect behavior\n 3. Data integrity issues (race conditions, missing transactions, corruption risk)\n 4. Performance bottlenecks (N+1 queries, memory leaks, blocking operations)\n 5. Error handling gaps (unhandled exceptions, missing validation)\n 6. Breaking changes to public APIs without migration path\n 7. Missing or incorrect test coverage for critical paths\n \n \n\n \n View unresolved review threads:\n ```bash\n $MENTION_SCRIPTS/gh-get-review-threads.sh\n ```\n\n Filter for unresolved threads from a specific reviewer:\n ```bash\n $MENTION_SCRIPTS/gh-get-review-threads.sh \"reviewer-username\"\n ```\n\n Resolve a review thread after addressing feedback:\n ```bash\n $MENTION_SCRIPTS/gh-resolve-review-thread.sh \"THREAD_ID\" \"Fixed by updating the error handling\"\n ```\n - `THREAD_ID` is the GraphQL node ID from the review threads output (e.g., `PRRT_kwDOABC123`)\n - The comment is optional - use it to explain what you did\n\n Note: Since you cannot push changes, you can resolve threads to acknowledge feedback, but actual fixes would need to be applied separately.\n \n\n \n - Be concise and actionable\n - If the request is unclear, ask clarifying questions\n - If the request requires actions you cannot perform (like pushing changes), explain what you can and cannot do\n - When making code changes, explain that they are local only and cannot be pushed\n\n **When performing a PR review**: Your substantive feedback belongs in the PR review submission\n (via pr-review.sh), not in the comment response. The comment should only report:\n - That you've submitted the review (with the outcome: approved, requested changes, etc.)\n - Any issues encountered during the review process\n - Brief status updates\n\n Do NOT duplicate the review content in your comment - the review itself contains all the details.\n Keep the comment short, e.g., \"I've submitted my review requesting changes. See the review for details.\"\n \n\n \n Always end your comment with a new line, three dashes, and the footer message:\n \n\n ---\n Marvin Context Protocol | Type `/marvin` to interact further\n\n Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.\n \n \n\n \n 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.\n \n" }, { "path": ".github/workflows/marvin-dedupe-issues.yml", "content": "name: Marvin Issue Dedupe\n# description: Automatically dedupe GitHub issues using Marvin\non:\n issues:\n types: [opened]\n workflow_dispatch:\n inputs:\n issue_number:\n description: \"Issue number to process for duplicate detection\"\n required: true\n type: string\n\njobs:\n marvin-dedupe-issues:\n runs-on: ubuntu-latest\n timeout-minutes: 10\n permissions:\n contents: read\n issues: write\n id-token: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - name: Set dedupe prompt\n id: dedupe-prompt\n run: |\n cat >> $GITHUB_OUTPUT << 'EOF'\n PROMPT</dev/null \\\n || date -u -v-10M '+%Y-%m-%dT%H:%M:%SZ')\n HAS_RECENT=$(gh api \"repos/${{ github.repository }}/issues/${ISSUE}/comments?sort=created&direction=desc&per_page=10\" \\\n --jq \"[.[] | select(\n .user.type == \\\"Bot\\\" and\n (.body | test(\\\"possible duplicate issues\\\"; \\\"i\\\")) and\n .created_at >= \\\"${CUTOFF}\\\"\n )] | length\")\n if [ \"$HAS_RECENT\" -gt 0 ]; then\n gh issue edit \"$ISSUE\" --add-label \"potential-duplicate\" -R \"${{ github.repository }}\"\n echo \"Added potential-duplicate label to #${ISSUE}\"\n else\n echo \"No recent duplicate comment found, skipping label\"\n fi\n" }, { "path": ".github/workflows/marvin-label-triage.yml", "content": "name: Marvin Label Triage\n# Automatically triage GitHub issues and PRs using Marvin\n\non:\n issues:\n types: [opened]\n pull_request_target:\n types: [opened]\n workflow_dispatch:\n inputs:\n issue_number:\n description: \"Issue or PR number to triage\"\n required: true\n type: string\n\nconcurrency:\n group: triage-${{ github.event.issue.number || github.event.pull_request.number || inputs.issue_number }}\n cancel-in-progress: false\n\njobs:\n label-issue-or-pr:\n if: github.actor != 'dependabot[bot]'\n runs-on: ubuntu-latest\n timeout-minutes: 10\n permissions:\n contents: read\n issues: write\n pull-requests: write\n\n steps:\n - name: Checkout base repository\n uses: actions/checkout@v6\n with:\n repository: ${{ github.repository }}\n ref: ${{ github.event.repository.default_branch }}\n\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n owner: PrefectHQ\n\n - name: Set triage prompt\n id: triage-prompt\n run: |\n cat >> $GITHUB_OUTPUT << 'EOF'\n PROMPT<-\n (\n github.event_name == 'issue_comment' &&\n github.event.issue.pull_request &&\n contains(github.event.comment.body, '/tidy') &&\n contains(fromJSON('[\"OWNER\", \"MEMBER\", \"COLLABORATOR\"]'), github.event.comment.author_association)\n ) || (\n github.event_name != 'issue_comment' &&\n github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name\n )\n runs-on: ubuntu-latest\n steps:\n - name: Minimize resolved review comments\n uses: strawgate/minimize-resolved-pr-reviews@v0\n with:\n github-token: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/publish.yml", "content": "name: Publish FastMCP to PyPI\non:\n release:\n types: [published]\n workflow_dispatch:\n\njobs:\n pypi-publish:\n name: Upload to PyPI\n runs-on: ubuntu-latest\n permissions:\n id-token: write # For PyPI's trusted publishing\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n - name: \"Install uv\"\n uses: astral-sh/setup-uv@v7\n\n - name: Build\n run: uv build\n\n - name: Publish to PyPi\n run: uv publish -v dist/*\n" }, { "path": ".github/workflows/run-static.yml", "content": "name: Run static analysis\n\nenv:\n PY_COLORS: 1\n\non:\n push:\n branches: [\"main\"]\n paths:\n - \"src/**\"\n - \"tests/**\"\n - \"uv.lock\"\n - \"pyproject.toml\"\n - \".github/workflows/**\"\n\n # run on all pull requests because these checks are required and will block merges otherwise\n pull_request:\n\n workflow_dispatch:\n\npermissions:\n contents: read\n\njobs:\n static_analysis:\n timeout-minutes: 2\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv\n uses: ./.github/actions/setup-uv\n with:\n resolution: locked\n\n - name: Run prek\n uses: j178/prek-action@v1\n env:\n SKIP: no-commit-to-branch\n" }, { "path": ".github/workflows/run-tests.yml", "content": "name: Tests\n\nenv:\n PY_COLORS: 1\n\non:\n push:\n branches: [\"main\"]\n paths:\n - \"src/**\"\n - \"tests/**\"\n - \"uv.lock\"\n - \"pyproject.toml\"\n - \".github/workflows/**\"\n\n # run on all pull requests because these checks are required and will block merges otherwise\n pull_request:\n\n workflow_dispatch:\n\npermissions:\n contents: read\n\njobs:\n run_tests:\n name: \"Tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}\"\n runs-on: ${{ matrix.os }}\n strategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n python-version: [\"3.10\"]\n include:\n - os: ubuntu-latest\n python-version: \"3.13\"\n fail-fast: false\n timeout-minutes: 10\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv\n uses: ./.github/actions/setup-uv\n with:\n python-version: ${{ matrix.python-version }}\n resolution: locked\n\n - name: Run unit tests\n uses: ./.github/actions/run-pytest\n\n - name: Run client process tests\n uses: ./.github/actions/run-pytest\n with:\n test-type: client_process\n\n run_tests_lowest_direct:\n name: \"Tests with lowest-direct dependencies\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv (lowest-direct)\n uses: ./.github/actions/setup-uv\n with:\n resolution: lowest-direct\n\n - name: Run unit tests\n uses: ./.github/actions/run-pytest\n\n - name: Run client process tests\n uses: ./.github/actions/run-pytest\n with:\n test-type: client_process\n\n run_integration_tests:\n name: \"Integration tests\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv\n uses: ./.github/actions/setup-uv\n with:\n resolution: locked\n\n - name: Run integration tests\n uses: ./.github/actions/run-pytest\n with:\n test-type: integration\n env:\n FASTMCP_GITHUB_TOKEN: ${{ secrets.FASTMCP_GITHUB_TOKEN }}\n FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID }}\n FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET }}\n" }, { "path": ".github/workflows/run-upgrade-checks.yml", "content": "name: Upgrade checks\n\nenv:\n PY_COLORS: 1\n\non:\n push:\n branches: [\"main\"]\n paths:\n - \"src/**\"\n - \"tests/**\"\n - \"uv.lock\"\n - \"pyproject.toml\"\n - \".github/workflows/**\"\n\n schedule:\n # Run daily at 2 AM UTC\n - cron: \"0 2 * * *\"\n\n workflow_dispatch:\n\npermissions:\n contents: read\n issues: write\n\njobs:\n static_analysis:\n name: Static analysis\n timeout-minutes: 2\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv (upgrade)\n uses: ./.github/actions/setup-uv\n with:\n resolution: upgrade\n\n - name: Run prek\n uses: j178/prek-action@v1\n env:\n SKIP: no-commit-to-branch\n\n run_tests:\n name: \"Tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}\"\n runs-on: ${{ matrix.os }}\n strategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n python-version: [\"3.10\"]\n include:\n - os: ubuntu-latest\n python-version: \"3.13\"\n fail-fast: false\n timeout-minutes: 10\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv (upgrade)\n uses: ./.github/actions/setup-uv\n with:\n python-version: ${{ matrix.python-version }}\n resolution: upgrade\n\n - name: Run unit tests\n uses: ./.github/actions/run-pytest\n\n - name: Run client process tests\n uses: ./.github/actions/run-pytest\n with:\n test-type: client_process\n\n run_integration_tests:\n name: \"Integration tests\"\n runs-on: ubuntu-latest\n timeout-minutes: 10\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Setup uv (upgrade)\n uses: ./.github/actions/setup-uv\n with:\n resolution: upgrade\n\n - name: Run integration tests\n uses: ./.github/actions/run-pytest\n with:\n test-type: integration\n env:\n FASTMCP_GITHUB_TOKEN: ${{ secrets.FASTMCP_GITHUB_TOKEN }}\n FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_ID }}\n FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET: ${{ secrets.FASTMCP_TEST_AUTH_GITHUB_CLIENT_SECRET }}\n\n notify:\n name: Notify on failure\n needs: [static_analysis, run_tests, run_integration_tests]\n if: failure() && github.event.pull_request == null\n runs-on: ubuntu-latest\n\n steps:\n - name: Create or update failure issue\n uses: jayqi/failed-build-issue-action@v1\n with:\n github-token: ${{ secrets.GITHUB_TOKEN }}\n label: \"build failed\"\n title-template: \"Upgrade checks failing on main branch\"\n body-template: |\n ## Upgrade Checks Failure on Main Branch\n\n The upgrade checks workflow has failed on the main branch.\n\n **Workflow Run**: [#{{runNumber}}]({{serverUrl}}/{{repo.owner}}/{{repo.repo}}/actions/runs/{{runId}})\n **Commit**: {{sha}}\n **Branch**: {{ref}}\n **Event**: {{eventName}}\n\n ### Common causes\n\n - **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`.\n - **ruff**: New lint rules or stricter defaults in a ruff upgrade.\n - **mcp SDK**: Breaking changes in the `mcp` package (new method signatures, renamed types).\n\n ### What to do\n\n 1. Check the workflow logs to identify which job failed (static analysis vs tests)\n 2. Reproduce locally with `uv sync --upgrade && uv run prek run --all-files && uv run pytest -n auto`\n 3. Fix the code or adjust dependency constraints as needed\n\n ---\n *This issue was automatically created by a GitHub Action.*\n\n close-on-success:\n name: Close issue on success\n needs: [static_analysis, run_tests, run_integration_tests]\n if: success() && github.event.pull_request == null && github.ref == 'refs/heads/main'\n runs-on: ubuntu-latest\n\n steps:\n - name: Close resolved failure issue\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n issue=$(gh issue list \\\n --repo \"$GITHUB_REPOSITORY\" \\\n --label \"build failed\" \\\n --state open \\\n --json number \\\n --jq '.[0].number // empty')\n\n if [ -n \"$issue\" ]; then\n gh issue close \"$issue\" \\\n --repo \"$GITHUB_REPOSITORY\" \\\n --comment \"Upgrade checks are passing again as of [\\`${GITHUB_SHA::7}\\`](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA}).\"\n fi\n" }, { "path": ".github/workflows/update-config-schema.yml", "content": "name: Update MCPServerConfig Schema\n\n# Regenerates config schema on pushes to main and opens a long-lived PR\n# with the changes, so contributor PRs stay clean.\n\non:\n push:\n branches: [\"main\"]\n paths:\n - \"src/fastmcp/utilities/mcp_server_config/**\"\n - \"!src/fastmcp/utilities/mcp_server_config/v1/schema.json\"\n workflow_dispatch:\n\npermissions:\n contents: write\n pull-requests: write\n\njobs:\n update-config-schema:\n timeout-minutes: 5\n runs-on: ubuntu-latest\n\n steps:\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - uses: actions/checkout@v6\n with:\n token: ${{ steps.marvin-token.outputs.token }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n cache-dependency-glob: \"uv.lock\"\n\n - name: Install dependencies\n run: uv sync --python 3.12\n\n - name: Generate config schema\n run: |\n uv run python -c \"\n from fastmcp.utilities.mcp_server_config import generate_schema\n generate_schema('docs/public/schemas/fastmcp.json/latest.json')\n generate_schema('docs/public/schemas/fastmcp.json/v1.json')\n generate_schema('src/fastmcp/utilities/mcp_server_config/v1/schema.json')\n \"\n\n - name: Create Pull Request\n uses: peter-evans/create-pull-request@v8\n with:\n token: ${{ steps.marvin-token.outputs.token }}\n commit-message: \"chore: Update fastmcp.json schema\"\n title: \"chore: Update fastmcp.json schema\"\n body: |\n This PR updates the fastmcp.json schema files to match the current source code.\n\n The schema is automatically generated from `src/fastmcp/utilities/mcp_server_config/` to ensure consistency.\n\n **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.\n\n 🤖 Generated by Marvin\n branch: marvin/update-config-schema\n labels: |\n ignore in release notes\n delete-branch: true\n author: \"marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>\"\n committer: \"marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>\"\n" }, { "path": ".github/workflows/update-sdk-docs.yml", "content": "name: Update SDK Documentation\n\n# Regenerates SDK docs on pushes to main and opens a long-lived PR\n# with the changes, so contributor PRs stay clean.\n\non:\n push:\n branches: [\"main\"]\n paths:\n - \"src/**\"\n - \"pyproject.toml\"\n workflow_dispatch:\n\npermissions:\n contents: write\n pull-requests: write\n\njobs:\n update-sdk-docs:\n timeout-minutes: 5\n runs-on: ubuntu-latest\n\n steps:\n - name: Generate Marvin App token\n id: marvin-token\n uses: actions/create-github-app-token@v3\n with:\n app-id: ${{ secrets.MARVIN_APP_ID }}\n private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}\n\n - uses: actions/checkout@v6\n with:\n token: ${{ steps.marvin-token.outputs.token }}\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n cache-dependency-glob: \"uv.lock\"\n\n - name: Install dependencies\n run: uv sync --python 3.12\n\n - name: Install just\n uses: extractions/setup-just@v3\n\n - name: Generate SDK documentation\n run: just api-ref-all\n\n - name: Create Pull Request\n uses: peter-evans/create-pull-request@v8\n with:\n token: ${{ steps.marvin-token.outputs.token }}\n commit-message: \"chore: Update SDK documentation\"\n title: \"chore: Update SDK documentation\"\n body: |\n This PR updates the auto-generated SDK documentation to reflect the latest source code changes.\n\n 📚 Documentation is automatically generated from the source code docstrings and type annotations.\n\n **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.\n\n 🤖 Generated by Marvin\n branch: marvin/update-sdk-docs\n labels: |\n ignore in release notes\n delete-branch: true\n author: \"marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>\"\n committer: \"marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>\"\n" }, { "path": ".gitignore", "content": "# Python-generated files\n__pycache__/\n*.py[cod]\n*$py.class\nbuild/\ndist/\nwheels/\n*.egg-info/\n*.egg\nMANIFEST\n.pytest_cache/\n.loq_cache\n.coverage\nhtmlcov/\n.tox/\nnosetests.xml\ncoverage.xml\n*.cover\n\n# Virtual environments\n.venv\nvenv/\nenv/\nENV/\n.env\n\n# System files\n.DS_Store\n\n# Version file\nsrc/fastmcp/_version.py\n\n# Editors and IDEs\n.cursorrules\n.vscode/\n.idea/\n*.swp\n*.swo\n*~\n.project\n.pydevproject\n.settings/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# Type checking\n.mypy_cache/\n.dmypy.json\ndmypy.json\n.pyre/\n.pytype/\n\n# Local development\n.python-version\n.envrc\n.envrc.private\n.direnv/\n\n# Logs and databases\n*.log\n*.sqlite\n*.db\n*.ddb\n\n# Claude worktree management\n.claude-wt/worktrees\n.claude/worktrees/\n\n# Agents\n/PLAN.md\n/TODO.md\n/STATUS.md\nplans/\n\n# Common FastMCP test files\n/test.py\n/server.py\n/client.py\n/test.json\n" }, { "path": ".pre-commit-config.yaml", "content": "fail_fast: false\n\nrepos:\n - repo: https://github.com/abravalheri/validate-pyproject\n rev: v0.24.1\n hooks:\n - id: validate-pyproject\n\n - repo: https://github.com/pre-commit/mirrors-prettier\n rev: v3.1.0\n hooks:\n - id: prettier\n types_or: [yaml, json5]\n\n - repo: https://github.com/astral-sh/ruff-pre-commit\n # Ruff version.\n rev: v0.14.10\n hooks:\n # Run the linter.\n - id: ruff-check\n args: [--fix, --exit-non-zero-on-fix]\n # Run the formatter.\n - id: ruff-format\n\n - repo: local\n hooks:\n - id: ty\n name: ty check\n entry: uv run --isolated ty check\n language: system\n types: [python]\n files: ^src/|^tests/\n pass_filenames: false\n require_serial: true\n\n - id: loq\n name: loq (file size limits)\n entry: bash -c 'uv run loq || printf \"\\nloq violations not enforced... yet!\\n\"'\n language: system\n pass_filenames: false\n verbose: true\n\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v6.0.0\n hooks:\n - id: no-commit-to-branch\n name: prevent commits to main\n args: [--branch, main]\n\n - repo: https://github.com/codespell-project/codespell\n rev: v2.4.1\n hooks:\n - id: codespell # See pyproject.toml for args\n additional_dependencies:\n - tomli\n" }, { "path": "CLAUDE.md", "content": "# FastMCP Development Guidelines\n\n> **Audience**: LLM-driven engineering agents and human developers\n\n> **Note**: `AGENTS.md` is a symlink to this file. Edit `CLAUDE.md` directly.\n\nFastMCP 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.\n\n## Required Development Workflow\n\n**CRITICAL**: Always run these commands in sequence before committing.\n\n```bash\nuv sync # Install dependencies\nuv run pytest -n auto # Run full test suite\n```\n\nIn addition, you must pass static checks. This is generally done as a pre-commit hook with `prek` but you can run it manually with:\n\n```bash\nuv run prek run --all-files # Ruff + Prettier + ty\n```\n\n**Tests must pass and lint/typing must be clean before committing.**\n\n## Repository Structure\n\n| Path | Purpose |\n| ----------------- | -------------------------------------- |\n| `src/fastmcp/` | Library source code |\n| `├─server/` | Server implementation |\n| `│ ├─auth/` | Authentication providers |\n| `│ └─middleware/` | Error handling, logging, rate limiting |\n| `├─client/` | Client SDK |\n| `│ └─auth/` | Client authentication |\n| `├─tools/` | Tool definitions |\n| `├─resources/` | Resources and resource templates |\n| `├─prompts/` | Prompt templates |\n| `├─cli/` | CLI commands |\n| `└─utilities/` | Shared utilities |\n| `tests/` | Pytest suite |\n| `docs/` | Mintlify docs (gofastmcp.com) |\n\n## Core MCP Objects\n\nWhen modifying MCP functionality, changes typically need to be applied across all object types:\n\n- **Tools** (`src/tools/`)\n- **Resources** (`src/resources/`)\n- **Resource Templates** (`src/resources/`)\n- **Prompts** (`src/prompts/`)\n\n## Development Rules\n\n### Git & CI\n\n- Prek hooks are required (run automatically on commits)\n- Never amend commits to fix prek failures\n- Apply PR labels: bugs/breaking/enhancements/features\n- Improvements = enhancements (not features) unless specified\n- **NEVER** force-push on collaborative repos\n- **ALWAYS** run prek before PRs\n- **NEVER** create a release, comment on an issue, or open a PR unless specifically instructed to do so.\n\n### Commit Messages and Agent Attribution\n\n- **Agents NOT acting on behalf of @jlowin MUST identify themselves** (e.g., \"🤖 Generated with Claude Code\" in commits/PRs)\n- Keep commit messages brief - ideally just headlines, not detailed messages\n- Focus on what changed, not how or why\n- Always read issue comments for follow-up information (treat maintainers as authoritative)\n- **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.\n\n### PR Messages - Required Structure\n\n- 1-2 paragraphs: problem/tension + solution (PRs are documentation!)\n- Focused code example showing key capability\n- **Avoid:** bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language\n- **Do:** Be opinionated about why change matters, show before/after scenarios\n- Minor fixes: keep body short and concise\n- No \"test plan\" sections or testing summaries\n\n### Code Standards\n\n- Python ≥ 3.10 with full type annotations\n- Follow existing patterns and maintain consistency\n- **Prioritize readable, understandable code** - clarity over cleverness\n- Avoid obfuscated or confusing patterns even if they're shorter\n- Each feature needs corresponding tests\n\n### Module Exports\n\n- **Be intentional about re-exports** - don't blindly re-export everything to parent namespaces\n- Core types that define a module's purpose should be exported (e.g., `Middleware` from `fastmcp.server.middleware`)\n- Specialized features can live in submodules (e.g., `fastmcp.server.middleware.dynamic`)\n- Only re-export to `fastmcp.*` for the most fundamental types (e.g., `FastMCP`, `Client`)\n- When in doubt, prefer users importing from the specific submodule over re-exporting\n\n### Documentation\n\n- Uses Mintlify framework\n- Files must be in docs.json to be included\n- 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.\n- 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.\n- **Core Principle:** A feature doesn't exist unless it is documented!\n- When adding or modifying settings in `src/fastmcp/settings.py`, update `docs/more/settings.mdx` to match.\n\n### Documentation Guidelines\n\n- **Code Examples:** Explain before showing code, make blocks fully runnable (include imports)\n- **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.\n- **Structure:** Headers form navigation guide, logical H2/H3 hierarchy\n- **Content:** User-focused sections, motivate features (why) before mechanics (how)\n- **Style:** Prose over code comments for important information\n- **Docstrings:** FastMCP docstrings are automatically compiled into MDX documents. Use markdown (single backticks, fenced code blocks), not RST (no double backticks). Bare `{}` in examples will be interpreted as JSX — wrap in backticks instead.\n\n## Critical Patterns\n\n- Never use bare `except` - be specific with exception types\n- File sizes enforced by [loq](https://github.com/jakekaplan/loq). Edit `loq.toml` to raise limits; `loq baseline` to ratchet down.\n- Always `uv sync` first when debugging build issues\n- Default test timeout is 5s - optimize or mark as integration tests\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, religion, or sexual identity\nand orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n* Demonstrating empathy and kindness toward other people\n* Being respectful of differing opinions, viewpoints, and experiences\n* Giving and gracefully accepting constructive feedback\n* Accepting responsibility and apologizing to those affected by our mistakes,\n and learning from the experience\n* Focusing on what is best not just for us as individuals, but for the\n overall community\n\nExamples of unacceptable behavior include:\n\n* The use of sexualized language or imagery, and sexual attention or\n advances of any kind\n* Trolling, insulting or derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or email\n address, without their explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement at\nchris@prefect.io.\nAll complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series\nof actions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or\npermanent ban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within\nthe community.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.0, available at\nhttps://www.contributor-covenant.org/version/2/0/code_of_conduct.html.\n\nCommunity Impact Guidelines were inspired by [Mozilla's code of conduct\nenforcement ladder](https://github.com/mozilla/diversity).\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see the FAQ at\nhttps://www.contributor-covenant.org/faq. Translations are available at\nhttps://www.contributor-covenant.org/translations.\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to FastMCP\n\nFastMCP is an actively maintained, high-traffic project. We welcome contributions — but the most impactful way to contribute might not be what you expect.\n\n## The best contribution is a great issue\n\nFastMCP is an opinionated framework, and its maintainers use AI-assisted tooling that is deeply tuned to those opinions — the design philosophy, the API patterns, the way the framework is meant to evolve. A well-written issue with a clear problem description is often more valuable than a pull request, because it lets maintainers produce a solution that isn't just correct, but consistent with how the framework wants to work. That matters more than speed, though it's faster too.\n\n**A great issue looks like this:**\n\n1. A short, motivating description of the problem or gap\n2. A minimal reproducible example (for bugs) or a concrete use case (for enhancements)\n3. A brief note on expected vs. actual behavior\n\nThat's it. No need to diagnose root causes, propose API designs, or suggest implementations. If you've done genuine investigation and have a non-obvious insight, include it.\n\n## Using AI to contribute\n\nWe encourage you to use LLMs to help identify bugs, write MREs, and prepare contributions. But if you do, your LLM must take into account the conventions and contributing guidelines of this repo — including how we want issues formatted and when it's appropriate to open a PR. Generic LLM output that ignores these guidelines tells us the contribution wasn't made thoughtfully, and we will close it. A good AI-assisted contribution is indistinguishable from a good human one. A bad one is obvious.\n\n## When to open a pull request\n\n**Bug fixes** — PRs are welcome for simple, well-scoped bug fixes where the problem and solution are both straightforward. \"The function raises `TypeError` when passed `None` because of a missing guard\" is a good candidate. If the fix requires design decisions or touches multiple subsystems, open an issue instead.\n\n**Documentation** — Typo fixes, clarifications, and improvements to examples are always welcome as PRs.\n\n**Enhancements and features** — For changes that affect the behavior or design of the framework, please open an issue first. Maintainers will typically implement these themselves. FastMCP is opinionated, and enhancements need to reflect those opinions — not just solve the problem, but solve it in a way that's consistent with the framework's design. That's hard to do from the outside, and it's why a clear problem description is more useful than a proposed solution.\n\n**Integrations** — FastMCP generally does not accept PRs that add third-party integrations (custom middleware, provider-specific adapters, etc.). If you're building something for your users, ship it as a standalone package — that's a feature, not a limitation. Authentication providers are an exception, since auth is tightly coupled to the framework.\n\n## PR guidelines\n\nIf you do open a PR:\n\n- **Reference an issue.** Every PR should address a tracked issue. If there isn't one, open an issue first. This isn't a permission step — you don't need to wait for a response. But the issue gives us context on the problem, and if a maintainer is already working on it, we can let you know before you invest time in code.\n- **Keep it focused.** One logical change per PR. Don't bundle unrelated fixes or refactors.\n- **Match existing patterns.** Follow the code style, type annotation conventions, and test patterns you see in the codebase. Run `uv run prek run --all-files` before submitting.\n- **Write tests.** Bug fixes should include a test that fails without the fix. Enhancements should include tests for the new behavior.\n- **Don't submit generated boilerplate.** We review every line. PRs that read like unedited LLM output — verbose descriptions, speculative changes, shotgun-style fixes — will be closed.\n\n## What we'll close without review\n\nTo keep the project maintainable, we will close PRs that:\n\n- Don't reference an issue or address a clearly self-evident bug\n- Make sweeping changes without prior discussion\n- Add third-party integrations that belong in a separate package\n- Are difficult to review due to size, scope, or generated content\n\nThis isn't personal. FastMCP receives a high volume of contributions and we need to focus maintainer time where it has the most impact — which is why a good issue is often the best thing you can do for the project.\n" }, { "path": "LICENSE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "README.md", "content": "
\n\n\n\n\n \n \n \"FastMCP\n\n\n# FastMCP 🚀\n\nMove fast and make things.\n\n*Made with 💙 by [Prefect](https://www.prefect.io/)*\n\n[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)\n[![Discord](https://img.shields.io/badge/community-discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/uu8dJCgttd)\n[![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)\n[![Tests](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml)\n[![License](https://img.shields.io/github/license/PrefectHQ/fastmcp.svg)](https://github.com/PrefectHQ/fastmcp/blob/main/LICENSE)\n\n\"prefecthq%2Ffastmcp\n
\n\n---\n\nThe [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:\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Demo 🚀\")\n\n@mcp.tool\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n## Why FastMCP\n\nBuilding 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.**\n\n**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.\n\nFastMCP has three pillars:\n\n\n\n\n\n\n\n
\n\n\"Servers\"\n
Servers\n\n
Expose tools, resources, and prompts to LLMs.\n		\n\n\"Apps\"\n
Apps\n\n
Give your tools interactive UIs rendered directly in the conversation.\n		\n\n\"Clients\"\n
Clients\n\n
Connect to any MCP server — local or remote, programmatic or CLI.\n
\n\n**[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.\n\nReady 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.\n\n## Installation\n\nWe recommend installing FastMCP with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv pip install fastmcp\n```\n\nFor full installation instructions, including verification and upgrading, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation).\n\n**Upgrading?** We have guides for:\n- [Upgrading from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2)\n- [Upgrading from the MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)\n- [Upgrading from the low-level SDK](https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk)\n\n## 📚 Documentation\n\nFastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns.\n\nDocumentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily:\n\n- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.\n- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.\n\n**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.\n\n## Contributing\n\nWe welcome contributions! See the [Contributing Guide](https://gofastmcp.com/development/contributing) for setup instructions, testing requirements, and PR guidelines.\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\n## Supported Versions\n\n| Version | Supported |\n| ------- | ------------------ |\n| 3.x | :white_check_mark: |\n| 2.x | :x: |\n| 1.x | :x: |\n| 0.x | :x: |\n\n## Reporting a Vulnerability\n\nPlease 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.\n\n## Scope\n\nWe accept reports for vulnerabilities in FastMCP itself — the library code in this repository.\n\nThe following are **out of scope**:\n\n- Vulnerabilities in third-party dependencies or the MCP SDK itself. We'll bump version floors for known CVEs, but the fix belongs upstream.\n- Limitations of upstream identity providers that FastMCP cannot control.\n- Issues that require the attacker to already have server-side access or control of the MCP server configuration.\n\n## Disclosure Process\n\nWhen we receive a valid report:\n\n1. We triage the report and determine whether it affects FastMCP directly.\n2. We develop and test a fix on a private branch.\n3. We coordinate CVE assignment through GitHub's advisory process when warranted.\n4. We publish the advisory and release a patched version.\n5. We credit the reporter in the advisory (unless they prefer otherwise).\n" }, { "path": "docs/.ccignore", "content": "changelog.mdx\npython-sdk/\n" }, { "path": "docs/.cursor/rules/mintlify.mdc", "content": "---\ndescription: \nglobs: *.mdx\nalwaysApply: false\n---\n# Mintlify technical writing assistant\n\nYou are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.\n\n## Core writing principles\n\n### Language and style requirements\n- Use clear, direct language appropriate for technical audiences\n- Write in second person (\"you\") for instructions and procedures\n- Use active voice over passive voice\n- Employ present tense for current states, future tense for outcomes\n- Maintain consistent terminology throughout all documentation\n- Keep sentences concise while providing necessary context\n- Use parallel structure in lists, headings, and procedures\n\n### Content organization standards\n- Lead with the most important information (inverted pyramid structure)\n- Use progressive disclosure: basic concepts before advanced ones\n- Break complex procedures into numbered steps\n- Include prerequisites and context before instructions\n- Provide expected outcomes for each major step\n- End sections with next steps or related information\n- Use descriptive, keyword-rich headings for navigation and SEO\n\n### User-centered approach\n- Focus on user goals and outcomes rather than system features\n- Anticipate common questions and address them proactively\n- Include troubleshooting for likely failure points\n- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options\n\n## Mintlify component reference\n\n### Callout components\n\n#### Note - Additional helpful information\n\n\nSupplementary information that supports the main content without interrupting flow\n\n\n#### Tip - Best practices and pro tips\n\n\nExpert advice, shortcuts, or best practices that enhance user success\n\n\n#### Warning - Important cautions\n\n\nCritical information about potential issues, breaking changes, or destructive actions\n\n\n#### Info - Neutral contextual information\n\n\nBackground information, context, or neutral announcements\n\n\n#### Check - Success confirmations\n\n\nPositive confirmations, successful completions, or achievement indicators\n\n\n### Code components\n\n#### Single code block\n\n```javascript config.js\nconst apiConfig = {\nbaseURL: 'https://api.example.com',\ntimeout: 5000,\nheaders: {\n 'Authorization': `Bearer ${process.env.API_TOKEN}`\n}\n};\n```\n\n#### Code group with multiple languages\n\n\n```javascript Node.js\nconst response = await fetch('/api/endpoint', {\n headers: { Authorization: `Bearer ${apiKey}` }\n});\n```\n\n```python Python\nimport requests\nresponse = requests.get('/api/endpoint', \n headers={'Authorization': f'Bearer {api_key}'})\n```\n\n```curl cURL\ncurl -X GET '/api/endpoint' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n```\n\n\n#### Request/Response examples\n\n\n```bash cURL\ncurl -X POST 'https://api.example.com/users' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"John Doe\", \"email\": \"john@example.com\"}'\n```\n\n\n\n```json Success\n{\n \"id\": \"user_123\",\n \"name\": \"John Doe\", \n \"email\": \"john@example.com\",\n \"created_at\": \"2024-01-15T10:30:00Z\"\n}\n```\n\n\n### Structural components\n\n#### Steps for procedures\n\n\n\n Run `npm install` to install required packages.\n \n \n Verify installation by running `npm list`.\n \n\n\n\n Create a `.env` file with your API credentials.\n \n ```bash\n API_KEY=your_api_key_here\n ```\n \n \n Never commit API keys to version control.\n \n\n\n\n#### Tabs for alternative content\n\n\n\n ```bash\n brew install node\n npm install -g package-name\n ```\n\n\n\n ```powershell\n choco install nodejs\n npm install -g package-name\n ```\n\n\n\n ```bash\n sudo apt install nodejs npm\n npm install -g package-name\n ```\n\n\n\n#### Accordions for collapsible content\n\n\n\n - **Firewall blocking**: Ensure ports 80 and 443 are open\n - **Proxy configuration**: Set HTTP_PROXY environment variable\n - **DNS resolution**: Try using 8.8.8.8 as DNS server\n\n\n\n ```javascript\n const config = {\n performance: { cache: true, timeout: 30000 },\n security: { encryption: 'AES-256' }\n };\n ```\n\n\n\n### API documentation components\n\n#### Parameter fields\n\n\nUnique identifier for the user. Must be a valid UUID v4 format.\n\n\n\nUser's email address. Must be valid and unique within the system.\n\n\n\nMaximum number of results to return. Range: 1-100.\n\n\n\nBearer token for API authentication. Format: `Bearer YOUR_API_KEY`\n\n\n#### Response fields\n\n\nUnique identifier assigned to the newly created user.\n\n\n\nISO 8601 formatted timestamp of when the user was created.\n\n\n\nList of permission strings assigned to this user.\n\n\n#### Expandable nested fields\n\n\nComplete user object with all associated data.\n\n\n \n User profile information including personal details.\n \n \n \n User's first name as entered during registration.\n \n \n \n URL to user's profile picture. Returns null if no avatar is set.\n \n \n \n\n\n\n### Interactive components\n\n#### Cards for navigation\n\n\nComplete walkthrough from installation to your first API call in under 10 minutes.\n\n\n\n\n Learn how to authenticate requests using API keys or JWT tokens.\n\n\n\n Understand rate limits and best practices for high-volume usage.\n\n\n\n### Media and advanced components\n\n#### Frames for images\n\nWrap all images in frames.\n\n\n\"Main\n\n\n\n\"Analytics\n\n\n#### Tooltips and updates\n\n\nAPI\n\n\n\n## New features\n- Added bulk user import functionality\n- Improved error messages with actionable suggestions\n\n## Bug fixes\n- Fixed pagination issue with large datasets\n- Resolved authentication timeout problems\n\n\n## Required page structure\n\nEvery documentation page must begin with YAML frontmatter:\n\n```yaml\n---\ntitle: \"Clear, specific, keyword-rich title\"\ndescription: \"Concise description explaining page purpose and value\"\n---\n```\n\n## Content quality standards\n\n### Code examples requirements\n- Always include complete, runnable examples that users can copy and execute\n- Show proper error handling and edge case management\n- Use realistic data instead of placeholder values\n- Include expected outputs and results for verification\n- Test all code examples thoroughly before publishing\n- Specify language and include filename when relevant\n- Add explanatory comments for complex logic\n\n### API documentation requirements\n- Document all parameters including optional ones with clear descriptions\n- Show both success and error response examples with realistic data\n- Include rate limiting information with specific limits\n- Provide authentication examples showing proper format\n- Explain all HTTP status codes and error handling\n- Cover complete request/response cycles\n\n### Accessibility requirements\n- Include descriptive alt text for all images and diagrams\n- Use specific, actionable link text instead of \"click here\"\n- Ensure proper heading hierarchy starting with H2\n- Provide keyboard navigation considerations\n- Use sufficient color contrast in examples and visuals\n- Structure content for easy scanning with headers and lists\n\n## AI assistant instructions\n\n### Component selection logic\n- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions\n- Use **Tabs** for platform-specific content or alternative approaches\n- Use **CodeGroup** when showing the same concept in multiple languages\n- Use **Accordions** for supplementary information that might interrupt flow\n- Use **Cards and CardGroup** for navigation, feature overviews, and related resources\n- Use **RequestExample/ResponseExample** specifically for API endpoint documentation\n- Use **ParamField** for API parameters, **ResponseField** for API responses\n- Use **Expandable** for nested object properties or hierarchical information\n\n### Quality assurance checklist\n- Verify all code examples are syntactically correct and executable\n- Test all links to ensure they are functional and lead to relevant content\n- Validate Mintlify component syntax with all required properties\n- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections\n- Ensure content flows logically from basic concepts to advanced topics\n- Check for consistency in terminology, formatting, and component usage\n\n### Error prevention strategies\n- Always include realistic error handling in code examples\n- Provide dedicated troubleshooting sections for complex procedures\n- Explain prerequisites clearly before beginning instructions\n- Include verification and testing steps with expected outcomes\n- Add appropriate warnings for destructive or security-sensitive actions\n- Validate all technical information through testing before publication" }, { "path": "docs/apps/development.mdx", "content": "---\ntitle: Development\nsidebarTitle: Development\ndescription: Preview and test your app tools locally without a full MCP host.\nicon: flask\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n`fastmcp dev apps` launches a browser-based preview for your app tools. It starts your MCP server and a local dev UI side by side — you pick a tool, fill in its arguments, and see the rendered result in a new tab. No MCP host client needed.\n\nThis works with both [Prefab apps](/apps/prefab) and [custom HTML apps](/apps/low-level).\n\n## Quick Start\n\n```bash\npip install \"fastmcp[apps]\"\nfastmcp dev apps server.py\n```\n\nThe dev UI opens at `http://localhost:8080`. Your MCP server runs on port 8000 with auto-reload enabled by default — save a file and the server restarts automatically.\n\n## How It Works\n\nThe dev server does three things:\n\nThe **picker page** connects to your MCP server, finds all tools with UI metadata, and renders a form for each one. The forms are auto-generated from the tool's input schema — text fields, dropdowns, checkboxes, all wired up.\n\nWhen you submit a form, the dev server **calls your tool** via the MCP protocol and opens the result in a new tab. The result page loads the tool's UI resource (the Prefab renderer or your custom HTML) inside an AppBridge — the same protocol that real MCP hosts use.\n\nA **reverse proxy** on `/mcp` forwards requests from the browser to your MCP server, avoiding CORS issues that would otherwise block the iframe-based renderer from talking to a different port.\n\n## Options\n\n```bash\nfastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090 --no-reload\n```\n\n| Option | Flag | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| MCP Port | `--mcp-port` | `8000` | Port for your MCP server |\n| Dev Port | `--dev-port` | `8080` | Port for the dev UI |\n| Auto-Reload | `--reload` / `--no-reload` | On | Watch files and restart the server on changes |\n\n## Multiple Tools\n\nIf your server has multiple app tools, the picker shows a dropdown. Each tool gets its own form and launch button. The tool's `title` is displayed when available, falling back to the tool name.\n\n```bash\n# Server with multiple app tools\nfastmcp dev apps examples/apps/contacts/contacts_server.py\n```\n" }, { "path": "docs/apps/low-level.mdx", "content": "---\ntitle: Custom HTML Apps\nsidebarTitle: Custom HTML\ndescription: Build apps with your own HTML, CSS, and JavaScript using the MCP Apps extension directly.\nicon: code\ntag: NEW\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nThe [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.\n\nThis 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.\n\n## How It Works\n\nAn MCP App has two parts:\n\n1. A **tool** that does the work and returns data\n2. A **`ui://` resource** containing the HTML that renders that data\n\nThe 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.\n\n```python\nimport json\n\nfrom fastmcp import FastMCP\nfrom fastmcp.server.apps import AppConfig, ResourceCSP\n\nmcp = FastMCP(\"My App Server\")\n\n# The tool does the work\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\"))\ndef generate_chart(data: list[float]) -> str:\n return json.dumps({\"values\": data})\n\n# The resource provides the UI\n@mcp.resource(\"ui://my-app/view.html\")\ndef chart_view() -> str:\n return \"...\"\n```\n\n## AppConfig\n\n`AppConfig` controls how a tool or resource participates in the Apps extension. Import it from `fastmcp.server.apps`:\n\n```python\nfrom fastmcp.server.apps import AppConfig\n```\n\nOn **tools**, you'll typically set `resource_uri` to point to the UI resource:\n\n```python\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\"))\ndef my_tool() -> str:\n return \"result\"\n```\n\nYou can also pass a raw dict with camelCase keys, matching the wire format:\n\n```python\n@mcp.tool(app={\"resourceUri\": \"ui://my-app/view.html\"})\ndef my_tool() -> str:\n return \"result\"\n```\n\n### Tool Visibility\n\nThe `visibility` field controls where a tool appears:\n\n- `[\"model\"]` — visible to the LLM (the default behavior)\n- `[\"app\"]` — only callable from within the app UI, hidden from the LLM\n- `[\"model\", \"app\"]` — both\n\nThis is useful when you have tools that only make sense as part of the app's interactive flow, not as standalone LLM actions.\n\n```python\n@mcp.tool(\n app=AppConfig(\n resource_uri=\"ui://my-app/view.html\",\n visibility=[\"app\"],\n )\n)\ndef refresh_data() -> str:\n \"\"\"Only callable from the app UI, not by the LLM.\"\"\"\n return fetch_latest()\n```\n\n### AppConfig Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resource_uri` | `str` | URI of the UI resource. Tools only. |\n| `visibility` | `list[str]` | Where the tool appears: `\"model\"`, `\"app\"`, or both. Tools only. |\n| `csp` | `ResourceCSP` | Content Security Policy for the iframe. |\n| `permissions` | `ResourcePermissions` | Iframe sandbox permissions. |\n| `domain` | `str` | Stable sandbox origin for the iframe. |\n| `prefers_border` | `bool` | Whether the UI prefers a visible border. |\n\n\nOn **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.\n\n\n## UI Resources\n\nResources using the `ui://` scheme are automatically served with the MIME type `text/html;profile=mcp-app`. You don't need to set this manually.\n\n```python\n@mcp.resource(\"ui://my-app/view.html\")\ndef my_view() -> str:\n return \"...\"\n```\n\nThe 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.\n\n### Writing the App HTML\n\nYour 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:\n\n```html\n\n```\n\nThe `App` object provides:\n\n- **`app.ontoolresult`** — callback that receives tool results pushed by the host\n- **`app.callServerTool({name, arguments})`** — call a tool on the server from within the app\n- **`app.onhostcontextchanged`** — callback for host context changes (e.g., safe area insets)\n- **`app.getHostContext()`** — get current host context\n\n\nIf your HTML loads external scripts, styles, or makes API calls, you need to declare those domains in the CSP configuration. See [Security](#security) below.\n\n\n## Security\n\nApps 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.\n\n### Content Security Policy\n\nIf your app needs to load external resources (CDN scripts, API calls, embedded iframes), declare the allowed domains with `ResourceCSP`:\n\n```python\nfrom fastmcp.server.apps import AppConfig, ResourceCSP\n\n@mcp.resource(\n \"ui://my-app/view.html\",\n app=AppConfig(\n csp=ResourceCSP(\n resource_domains=[\"https://unpkg.com\", \"https://cdn.example.com\"],\n connect_domains=[\"https://api.example.com\"],\n )\n ),\n)\ndef my_view() -> str:\n return \"...\"\n```\n\n| CSP Field | Controls |\n|-----------|----------|\n| `connect_domains` | `fetch`, XHR, WebSocket (`connect-src`) |\n| `resource_domains` | Scripts, images, styles, fonts (`script-src`, etc.) |\n| `frame_domains` | Nested iframes (`frame-src`) |\n| `base_uri_domains` | Document base URI (`base-uri`) |\n\n### Permissions\n\nIf your app needs browser capabilities like camera or clipboard access, request them via `ResourcePermissions`:\n\n```python\nfrom fastmcp.server.apps import AppConfig, ResourcePermissions\n\n@mcp.resource(\n \"ui://my-app/view.html\",\n app=AppConfig(\n permissions=ResourcePermissions(\n camera={},\n clipboard_write={},\n )\n ),\n)\ndef my_view() -> str:\n return \"...\"\n```\n\nHosts may or may not grant these permissions. Your app should use JavaScript feature detection as a fallback.\n\n## Example: QR Code Server\n\nThis 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.\n\n```python expandable\nimport base64\nimport io\n\nimport qrcode\nfrom mcp import types\n\nfrom fastmcp import FastMCP\nfrom fastmcp.server.apps import AppConfig, ResourceCSP\nfrom fastmcp.tools import ToolResult\n\nmcp = FastMCP(\"QR Code Server\")\n\nVIEW_URI = \"ui://qr-server/view.html\"\n\n\n@mcp.tool(app=AppConfig(resource_uri=VIEW_URI))\ndef generate_qr(text: str = \"https://gofastmcp.com\") -> ToolResult:\n \"\"\"Generate a QR code from text.\"\"\"\n qr = qrcode.QRCode(version=1, box_size=10, border=4)\n qr.add_data(text)\n qr.make(fit=True)\n\n img = qr.make_image()\n buffer = io.BytesIO()\n img.save(buffer, format=\"PNG\")\n b64 = base64.b64encode(buffer.getvalue()).decode()\n\n return ToolResult(\n content=[types.ImageContent(type=\"image\", data=b64, mimeType=\"image/png\")]\n )\n\n\n@mcp.resource(\n VIEW_URI,\n app=AppConfig(csp=ResourceCSP(resource_domains=[\"https://unpkg.com\"])),\n)\ndef view() -> str:\n \"\"\"Interactive QR code viewer.\"\"\"\n return \"\"\"\\\n\n\n\n \n \n\n\n
\n \n\n\"\"\"\n```\n\nThe 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.\n\n## Checking Client Support\n\nNot all hosts support the Apps extension. You can check at runtime using the tool's [context](/servers/context):\n\n```python\nfrom fastmcp import Context\nfrom fastmcp.server.apps import AppConfig, UI_EXTENSION_ID\n\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\"))\nasync def my_tool(ctx: Context) -> str:\n if ctx.client_supports_extension(UI_EXTENSION_ID):\n # Return data optimized for UI rendering\n return rich_response()\n else:\n # Fall back to plain text\n return plain_text_response()\n```\n" }, { "path": "docs/apps/overview.mdx", "content": "---\ntitle: Apps\nsidebarTitle: Overview\ndescription: Give your tools interactive UIs rendered directly in the conversation.\nicon: grid-2\ntag: NEW\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nMCP 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.\n\nFastMCP implements the [MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps) and provides two approaches:\n\n## Prefab Apps (Recommended)\n\n\n\n\n[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.\n\n\n[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).\n\n```python\nfrom prefab_ui.components import Column, Heading, BarChart, ChartSeries\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Dashboard\")\n\n@mcp.tool(app=True)\ndef sales_chart(year: int) -> PrefabApp:\n \"\"\"Show sales data as an interactive chart.\"\"\"\n data = get_sales_data(year)\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(f\"{year} Sales\")\n BarChart(\n data=data,\n series=[ChartSeries(data_key=\"revenue\", label=\"Revenue\")],\n x_axis=\"month\",\n )\n\n return PrefabApp(view=view)\n```\n\nInstall with `pip install \"fastmcp[apps]\"` and see [Prefab Apps](/apps/prefab) for the integration guide.\n\n## Custom HTML Apps\n\nThe [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.\n\nThis is the right choice for custom rendering (maps, 3D, video), specific JavaScript frameworks, or capabilities beyond what the component library offers.\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.apps import AppConfig, ResourceCSP\n\nmcp = FastMCP(\"Custom App\")\n\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\"))\ndef my_tool() -> str:\n return '{\"values\": [1, 2, 3]}'\n\n@mcp.resource(\n \"ui://my-app/view.html\",\n app=AppConfig(csp=ResourceCSP(resource_domains=[\"https://unpkg.com\"])),\n)\ndef view() -> str:\n return \"...\"\n```\n\nSee [Custom HTML Apps](/apps/low-level) for the full reference.\n" }, { "path": "docs/apps/patterns.mdx", "content": "---\ntitle: Patterns\nsidebarTitle: Patterns\ndescription: Charts, tables, forms, and other common tool UIs.\nicon: grid-2-plus\ntag: SOON\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n\n[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.\n\n\nThe 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.\n\n## Charts\n\nPrefab 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.\n\n### Bar Chart\n\n```python\nfrom prefab_ui.components import Column, Heading, BarChart, ChartSeries\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Charts\")\n\n\n@mcp.tool(app=True)\ndef quarterly_revenue(year: int) -> PrefabApp:\n \"\"\"Show quarterly revenue as a bar chart.\"\"\"\n data = [\n {\"quarter\": \"Q1\", \"revenue\": 42000, \"costs\": 28000},\n {\"quarter\": \"Q2\", \"revenue\": 51000, \"costs\": 31000},\n {\"quarter\": \"Q3\", \"revenue\": 47000, \"costs\": 29000},\n {\"quarter\": \"Q4\", \"revenue\": 63000, \"costs\": 35000},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(f\"{year} Revenue vs Costs\")\n BarChart(\n data=data,\n series=[\n ChartSeries(data_key=\"revenue\", label=\"Revenue\"),\n ChartSeries(data_key=\"costs\", label=\"Costs\"),\n ],\n x_axis=\"quarter\",\n show_legend=True,\n )\n\n return PrefabApp(view=view)\n```\n\nMultiple `ChartSeries` entries plot different data keys. Add `stacked=True` to stack bars, or `horizontal=True` to flip the axes.\n\n### Area Chart\n\n`LineChart` and `AreaChart` share the same API as `BarChart`, with `curve` for interpolation (`\"linear\"`, `\"smooth\"`, `\"step\"`) and `show_dots` for data points:\n\n```python\nfrom prefab_ui.components import Column, Heading, AreaChart, ChartSeries\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Charts\")\n\n\n@mcp.tool(app=True)\ndef usage_trend() -> PrefabApp:\n \"\"\"Show API usage over time.\"\"\"\n data = [\n {\"date\": \"Feb 1\", \"requests\": 1200},\n {\"date\": \"Feb 2\", \"requests\": 1350},\n {\"date\": \"Feb 3\", \"requests\": 980},\n {\"date\": \"Feb 4\", \"requests\": 1500},\n {\"date\": \"Feb 5\", \"requests\": 1420},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"API Usage\")\n AreaChart(\n data=data,\n series=[ChartSeries(data_key=\"requests\", label=\"Requests\")],\n x_axis=\"date\",\n curve=\"smooth\",\n height=250,\n )\n\n return PrefabApp(view=view)\n```\n\n### Pie and Donut Charts\n\n`PieChart` uses `data_key` (the numeric value) and `name_key` (the label) instead of series. Set `inner_radius` for a donut:\n\n```python\nfrom prefab_ui.components import Column, Heading, PieChart\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Charts\")\n\n\n@mcp.tool(app=True)\ndef ticket_breakdown() -> PrefabApp:\n \"\"\"Show open tickets by category.\"\"\"\n data = [\n {\"category\": \"Bug\", \"count\": 23},\n {\"category\": \"Feature\", \"count\": 15},\n {\"category\": \"Docs\", \"count\": 8},\n {\"category\": \"Infra\", \"count\": 12},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"Open Tickets\")\n PieChart(\n data=data,\n data_key=\"count\",\n name_key=\"category\",\n show_legend=True,\n inner_radius=60,\n )\n\n return PrefabApp(view=view)\n```\n\n## Data Tables\n\n[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.\n\n```python\nfrom prefab_ui.components import Column, Heading, DataTable, DataTableColumn\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Directory\")\n\n\n@mcp.tool(app=True)\ndef employee_directory() -> PrefabApp:\n \"\"\"Show a searchable, sortable employee directory.\"\"\"\n employees = [\n {\"name\": \"Alice Chen\", \"department\": \"Engineering\", \"role\": \"Staff Engineer\", \"location\": \"SF\"},\n {\"name\": \"Bob Martinez\", \"department\": \"Design\", \"role\": \"Lead Designer\", \"location\": \"NYC\"},\n {\"name\": \"Carol Johnson\", \"department\": \"Engineering\", \"role\": \"Senior Engineer\", \"location\": \"London\"},\n {\"name\": \"David Kim\", \"department\": \"Product\", \"role\": \"Product Manager\", \"location\": \"SF\"},\n {\"name\": \"Eva Müller\", \"department\": \"Engineering\", \"role\": \"Engineer\", \"location\": \"Berlin\"},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"Employee Directory\")\n DataTable(\n columns=[\n DataTableColumn(key=\"name\", header=\"Name\", sortable=True),\n DataTableColumn(key=\"department\", header=\"Department\", sortable=True),\n DataTableColumn(key=\"role\", header=\"Role\"),\n DataTableColumn(key=\"location\", header=\"Office\", sortable=True),\n ],\n rows=employees,\n searchable=True,\n paginated=True,\n page_size=15,\n )\n\n return PrefabApp(view=view)\n```\n\n## Forms\n\nA 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.\n\n```python\nfrom prefab_ui.components import (\n Column, Heading, Row, Muted, Badge, Input, Select,\n Textarea, Button, Form, ForEach, Separator,\n)\nfrom prefab_ui.actions import ShowToast\nfrom prefab_ui.actions.mcp import CallTool\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Contacts\")\n\ncontacts_db: list[dict] = [\n {\"name\": \"Zaphod Beeblebrox\", \"email\": \"zaphod@galaxy.gov\", \"category\": \"Partner\"},\n]\n\n\n@mcp.tool(app=True)\ndef contact_form() -> PrefabApp:\n \"\"\"Show a contact list with a form to add new contacts.\"\"\"\n with Column(gap=6, css_class=\"p-6\") as view:\n Heading(\"Contacts\")\n\n with ForEach(\"contacts\"):\n with Row(gap=2, align=\"center\"):\n Muted(\"{{ name }}\")\n Muted(\"{{ email }}\")\n Badge(\"{{ category }}\")\n\n Separator()\n\n with Form(\n on_submit=CallTool(\n \"save_contact\",\n result_key=\"contacts\",\n on_success=ShowToast(\"Contact saved!\", variant=\"success\"),\n on_error=ShowToast(\"{{ $error }}\", variant=\"error\"),\n )\n ):\n Input(name=\"name\", label=\"Full Name\", required=True)\n Input(name=\"email\", label=\"Email\", input_type=\"email\", required=True)\n Select(\n name=\"category\",\n label=\"Category\",\n options=[\"Customer\", \"Vendor\", \"Partner\", \"Other\"],\n )\n Textarea(name=\"notes\", label=\"Notes\", placeholder=\"Optional notes...\")\n Button(\"Save Contact\")\n\n return PrefabApp(view=view, state={\"contacts\": list(contacts_db)})\n\n\n@mcp.tool\ndef save_contact(\n name: str,\n email: str,\n category: str = \"Other\",\n notes: str = \"\",\n) -> list[dict]:\n \"\"\"Save a new contact and return the updated list.\"\"\"\n contacts_db.append({\"name\": name, \"email\": email, \"category\": category, \"notes\": notes})\n return list(contacts_db)\n```\n\nWhen 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.\n\nThe `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.\n\n### Pydantic Model Forms\n\nFor complex forms, `Form.from_model()` generates the entire form from a Pydantic model — inputs, labels, validation, and submit wiring:\n\n```python\nfrom typing import Literal\n\nfrom pydantic import BaseModel, Field\nfrom prefab_ui.components import Column, Heading, Form\nfrom prefab_ui.actions.mcp import CallTool\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Bug Tracker\")\n\n\nclass BugReport(BaseModel):\n title: str = Field(title=\"Bug Title\")\n severity: Literal[\"low\", \"medium\", \"high\", \"critical\"] = Field(\n title=\"Severity\", default=\"medium\"\n )\n description: str = Field(title=\"Description\")\n steps_to_reproduce: str = Field(title=\"Steps to Reproduce\")\n\n\n@mcp.tool(app=True)\ndef report_bug() -> PrefabApp:\n \"\"\"Show a bug report form.\"\"\"\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"Report a Bug\")\n Form.from_model(BugReport, on_submit=CallTool(\"create_bug_report\"))\n\n return PrefabApp(view=view)\n\n\n@mcp.tool\ndef create_bug_report(data: dict) -> str:\n \"\"\"Create a bug report from the form submission.\"\"\"\n report = BugReport(**data)\n # save to database...\n return f\"Created bug report: {report.title}\"\n```\n\n`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.\n\n## Status Displays\n\nCards, 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.\n\n```python\nfrom prefab_ui.components import (\n Column, Row, Grid, Heading, Text, Muted, Badge,\n Card, CardContent, Progress, Separator,\n)\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Monitoring\")\n\n\n@mcp.tool(app=True)\ndef system_status() -> PrefabApp:\n \"\"\"Show current system health.\"\"\"\n services = [\n {\"name\": \"API Gateway\", \"status\": \"healthy\", \"ok\": True, \"latency_ms\": 12, \"uptime_pct\": 99.9},\n {\"name\": \"Database\", \"status\": \"healthy\", \"ok\": True, \"latency_ms\": 3, \"uptime_pct\": 99.99},\n {\"name\": \"Cache\", \"status\": \"degraded\", \"ok\": False, \"latency_ms\": 45, \"uptime_pct\": 98.2},\n {\"name\": \"Queue\", \"status\": \"healthy\", \"ok\": True, \"latency_ms\": 8, \"uptime_pct\": 99.8},\n ]\n all_ok = all(s[\"ok\"] for s in services)\n\n with Column(gap=4, css_class=\"p-6\") as view:\n with Row(gap=2, align=\"center\"):\n Heading(\"System Status\")\n Badge(\n \"All Healthy\" if all_ok else \"Degraded\",\n variant=\"success\" if all_ok else \"destructive\",\n )\n\n Separator()\n\n with Grid(columns=2, gap=4):\n for svc in services:\n with Card():\n with CardContent():\n with Row(gap=2, align=\"center\"):\n Text(svc[\"name\"], css_class=\"font-medium\")\n Badge(\n svc[\"status\"],\n variant=\"success\" if svc[\"ok\"] else \"destructive\",\n )\n Muted(f\"Response: {svc['latency_ms']}ms\")\n Progress(value=svc[\"uptime_pct\"])\n\n return PrefabApp(view=view)\n```\n\n## Conditional Content\n\n[`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.\n\n```python\nfrom prefab_ui.components import Column, Heading, Switch, Separator, Alert, If\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Flags\")\n\n\n@mcp.tool(app=True)\ndef feature_flags() -> PrefabApp:\n \"\"\"Toggle feature flags with live preview.\"\"\"\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"Feature Flags\")\n\n Switch(name=\"dark_mode\", label=\"Dark Mode\")\n Switch(name=\"beta_features\", label=\"Beta Features\")\n\n Separator()\n\n with If(\"{{ dark_mode }}\"):\n Alert(title=\"Dark mode enabled\", description=\"UI will use dark theme.\")\n with If(\"{{ beta_features }}\"):\n Alert(\n title=\"Beta features active\",\n description=\"Experimental features are now visible.\",\n variant=\"warning\",\n )\n\n return PrefabApp(view=view, state={\"dark_mode\": False, \"beta_features\": False})\n```\n\n## Tabs\n\n[Tabs](https://prefab.prefect.io/docs/components/containers/tabs) organize content into switchable views. Switching is client-side — no server round-trip.\n\n```python\nfrom prefab_ui.components import (\n Column, Heading, Text, Muted, Badge, Row,\n DataTable, DataTableColumn, Tabs, Tab, ForEach,\n)\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Projects\")\n\n\n@mcp.tool(app=True)\ndef project_overview(project_id: str) -> PrefabApp:\n \"\"\"Show project details organized in tabs.\"\"\"\n project = {\n \"name\": \"FastMCP v3\",\n \"description\": \"Next generation MCP framework with Apps support.\",\n \"status\": \"Active\",\n \"created_at\": \"2025-01-15\",\n \"members\": [\n {\"name\": \"Alice Chen\", \"role\": \"Lead\"},\n {\"name\": \"Bob Martinez\", \"role\": \"Design\"},\n ],\n \"activity\": [\n {\"timestamp\": \"2 hours ago\", \"message\": \"Merged PR #342\"},\n {\"timestamp\": \"1 day ago\", \"message\": \"Released v3.0.1\"},\n ],\n }\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(project[\"name\"])\n\n with Tabs():\n with Tab(\"Overview\"):\n Text(project[\"description\"])\n with Row(gap=4):\n Badge(project[\"status\"])\n Muted(f\"Created: {project['created_at']}\")\n\n with Tab(\"Members\"):\n DataTable(\n columns=[\n DataTableColumn(key=\"name\", header=\"Name\", sortable=True),\n DataTableColumn(key=\"role\", header=\"Role\"),\n ],\n rows=project[\"members\"],\n )\n\n with Tab(\"Activity\"):\n with ForEach(\"activity\"):\n with Row(gap=2):\n Muted(\"{{ timestamp }}\")\n Text(\"{{ message }}\")\n\n return PrefabApp(view=view, state={\"activity\": project[\"activity\"]})\n```\n\n## Accordion\n\n[Accordion](https://prefab.prefect.io/docs/components/containers/accordion) collapses sections to save space. `multiple=True` lets users expand several items at once:\n\n```python\nfrom prefab_ui.components import (\n Column, Heading, Row, Text, Badge, Progress,\n Accordion, AccordionItem,\n)\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"API Monitor\")\n\n\n@mcp.tool(app=True)\ndef api_health() -> PrefabApp:\n \"\"\"Show health details for each API endpoint.\"\"\"\n endpoints = [\n {\"path\": \"/api/users\", \"status\": 200, \"healthy\": True, \"avg_ms\": 45, \"p99_ms\": 120, \"uptime_pct\": 99.9},\n {\"path\": \"/api/orders\", \"status\": 200, \"healthy\": True, \"avg_ms\": 82, \"p99_ms\": 250, \"uptime_pct\": 99.7},\n {\"path\": \"/api/search\", \"status\": 200, \"healthy\": True, \"avg_ms\": 150, \"p99_ms\": 500, \"uptime_pct\": 99.5},\n {\"path\": \"/api/webhooks\", \"status\": 503, \"healthy\": False, \"avg_ms\": 2000, \"p99_ms\": 5000, \"uptime_pct\": 95.1},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"API Health\")\n\n with Accordion(multiple=True):\n for ep in endpoints:\n with AccordionItem(ep[\"path\"]):\n with Row(gap=4):\n Badge(\n f\"{ep['status']}\",\n variant=\"success\" if ep[\"healthy\"] else \"destructive\",\n )\n Text(f\"Avg: {ep['avg_ms']}ms\")\n Text(f\"P99: {ep['p99_ms']}ms\")\n Progress(value=ep[\"uptime_pct\"])\n\n return PrefabApp(view=view)\n```\n\n## Next Steps\n\n- **[Custom HTML Apps](/apps/low-level)** — When you need your own HTML, CSS, and JavaScript\n- **[Prefab UI Docs](https://prefab.prefect.io)** — Components, state, expressions, and actions\n" }, { "path": "docs/apps/prefab.mdx", "content": "---\ntitle: Prefab Apps\nsidebarTitle: Prefab Apps\ndescription: Build interactive tool UIs in pure Python — no HTML or JavaScript required.\nicon: palette\ntag: SOON\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n\n[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).\n\n\n[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.\n\nPrefab 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.\n\n```bash\npip install \"fastmcp[apps]\"\n```\n\n\nPrefab 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.\n\n```toml\n# pyproject.toml\ndependencies = [\n \"fastmcp[apps]\",\n \"prefab-ui==0.8.0\", # pin to a known working version\n]\n```\n\n\nHere's the simplest possible Prefab App — a tool that returns a bar chart:\n\n```python\nfrom prefab_ui.components import Column, Heading, BarChart, ChartSeries\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Dashboard\")\n\n\n@mcp.tool(app=True)\ndef revenue_chart(year: int) -> PrefabApp:\n \"\"\"Show annual revenue as an interactive bar chart.\"\"\"\n data = [\n {\"quarter\": \"Q1\", \"revenue\": 42000},\n {\"quarter\": \"Q2\", \"revenue\": 51000},\n {\"quarter\": \"Q3\", \"revenue\": 47000},\n {\"quarter\": \"Q4\", \"revenue\": 63000},\n ]\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(f\"{year} Revenue\")\n BarChart(\n data=data,\n series=[ChartSeries(data_key=\"revenue\", label=\"Revenue\")],\n x_axis=\"quarter\",\n )\n\n return PrefabApp(view=view)\n```\n\nThat'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.\n\n## What You Return\n\n### Components\n\nThe 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:\n\n```python\nfrom prefab_ui.components import Column, Heading, Badge\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Status\")\n\n\n@mcp.tool(app=True)\ndef status_badge() -> Column:\n \"\"\"Show system status.\"\"\"\n with Column(gap=2) as view:\n Heading(\"All Systems Operational\")\n Badge(\"Healthy\", variant=\"success\")\n return view\n```\n\nWant a chart? Return a chart. Want a table? Return a table. FastMCP handles the wiring.\n\n### PrefabApp\n\nWhen you need more control — setting initial state values that components can read and react to, or configuring the rendering engine — return a `PrefabApp` explicitly:\n\n```python\nfrom prefab_ui.components import Column, Heading, Text, Button, If, Badge\nfrom prefab_ui.actions import ToggleState\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Demo\")\n\n\n@mcp.tool(app=True)\ndef toggle_demo() -> PrefabApp:\n \"\"\"Interactive toggle with state.\"\"\"\n with Column(gap=4, css_class=\"p-6\") as view:\n Button(\"Toggle\", on_click=ToggleState(\"show\"))\n with If(\"{{ show }}\"):\n Badge(\"Visible!\", variant=\"success\")\n\n return PrefabApp(view=view, state={\"show\": False})\n```\n\nThe `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.\n\n### ToolResult\n\nEvery 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.\n\nIf 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:\n\n```python\nfrom prefab_ui.components import Column, Heading, BarChart, ChartSeries\nfrom prefab_ui.app import PrefabApp\nfrom fastmcp import FastMCP\nfrom fastmcp.tools import ToolResult\n\nmcp = FastMCP(\"Sales\")\n\n\n@mcp.tool(app=True)\ndef sales_overview(year: int) -> ToolResult:\n \"\"\"Show sales data visually and summarize for the model.\"\"\"\n data = get_sales_data(year)\n total = sum(row[\"revenue\"] for row in data)\n\n with Column(gap=4, css_class=\"p-6\") as view:\n Heading(\"Sales Overview\")\n BarChart(data=data, series=[ChartSeries(data_key=\"revenue\")])\n\n return ToolResult(\n content=f\"Total revenue for {year}: ${total:,} across {len(data)} quarters\",\n structured_content=view,\n )\n```\n\nThe user sees the chart. The LLM sees `\"Total revenue for 2025: $203,000 across 4 quarters\"` and can reason about it.\n\n## Type Inference\n\nIf your tool's return type annotation is a Prefab type — `PrefabApp`, `Component`, or their `Optional` variants — FastMCP detects this and enables app rendering automatically:\n\n```python\n@mcp.tool\ndef greet(name: str) -> PrefabApp:\n return PrefabApp(view=Heading(f\"Hello, {name}!\"))\n```\n\nThis 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`).\n\n## How It Works\n\nBehind the scenes, when a tool returns a Prefab component or `PrefabApp`, FastMCP:\n\n1. **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.\n2. **Wires the tool metadata** — so the host knows to load the renderer iframe when displaying the tool result.\n3. **Serializes the component tree** — your Python components become `structuredContent` on the tool result, which the renderer interprets and displays.\n\nNone of this requires any configuration. The `app=True` flag (or type inference) is the only thing you need.\n\n## Mixing with Custom HTML Apps\n\nPrefab 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:\n\n```python\nfrom fastmcp.server.apps import AppConfig\n\n@mcp.tool(app=True)\ndef team_directory() -> PrefabApp:\n ...\n\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/map.html\"))\ndef map_view() -> str:\n ...\n```\n\n## Next Steps\n\n- **[Patterns](/apps/patterns)** — Charts, tables, forms, and other common tool UIs\n- **[Development](/apps/development)** — Preview and test app tools locally with `fastmcp dev apps`\n- **[Custom HTML Apps](/apps/low-level)** — When you need your own HTML, CSS, and JavaScript\n- **[Prefab UI Docs](https://prefab.prefect.io)** — Components, state, expressions, and actions\n" }, { "path": "docs/assets/schemas/mcp_server_config/latest.json", "content": "{\n \"$defs\": {\n \"Deployment\": {\n \"description\": \"Configuration for server deployment and runtime settings.\",\n \"properties\": {\n \"transport\": {\n \"anyOf\": [\n {\n \"enum\": [\n \"stdio\",\n \"http\",\n \"sse\"\n ],\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Transport protocol to use\",\n \"title\": \"Transport\"\n },\n \"host\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Host to bind to when using HTTP transport\",\n \"examples\": [\n \"127.0.0.1\",\n \"0.0.0.0\",\n \"localhost\"\n ],\n \"title\": \"Host\"\n },\n \"port\": {\n \"anyOf\": [\n {\n \"type\": \"integer\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Port to bind to when using HTTP transport\",\n \"examples\": [\n 8000,\n 3000,\n 5000\n ],\n \"title\": \"Port\"\n },\n \"path\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"URL path for the server endpoint\",\n \"examples\": [\n \"/mcp/\",\n \"/api/mcp/\",\n \"/sse/\"\n ],\n \"title\": \"Path\"\n },\n \"log_level\": {\n \"anyOf\": [\n {\n \"enum\": [\n \"DEBUG\",\n \"INFO\",\n \"WARNING\",\n \"ERROR\",\n \"CRITICAL\"\n ],\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Log level for the server\",\n \"title\": \"Log Level\"\n },\n \"cwd\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Working directory for the server process\",\n \"examples\": [\n \".\",\n \"./src\",\n \"/app\"\n ],\n \"title\": \"Cwd\"\n },\n \"env\": {\n \"anyOf\": [\n {\n \"additionalProperties\": {\n \"type\": \"string\"\n },\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Environment variables to set when running the server\",\n \"examples\": [\n {\n \"API_KEY\": \"secret\",\n \"DEBUG\": \"true\"\n }\n ],\n \"title\": \"Env\"\n },\n \"args\": {\n \"anyOf\": [\n {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Arguments to pass to the server (after --)\",\n \"examples\": [\n [\n \"--config\",\n \"config.json\",\n \"--debug\"\n ]\n ],\n \"title\": \"Args\"\n }\n },\n \"title\": \"Deployment\",\n \"type\": \"object\"\n },\n \"Environment\": {\n \"description\": \"Configuration for Python environment setup.\",\n \"properties\": {\n \"python\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Python version constraint\",\n \"examples\": [\n \"3.10\",\n \"3.11\",\n \"3.12\"\n ],\n \"title\": \"Python\"\n },\n \"dependencies\": {\n \"anyOf\": [\n {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Python packages to install with PEP 508 specifiers\",\n \"examples\": [\n [\n \"fastmcp>=2.0,<3\",\n \"httpx\",\n \"pandas>=2.0\"\n ]\n ],\n \"title\": \"Dependencies\"\n },\n \"requirements\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Path to requirements.txt file\",\n \"examples\": [\n \"requirements.txt\",\n \"../requirements/prod.txt\"\n ],\n \"title\": \"Requirements\"\n },\n \"project\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Path to project directory containing pyproject.toml\",\n \"examples\": [\n \".\",\n \"../my-project\"\n ],\n \"title\": \"Project\"\n },\n \"editable\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Directory to install in editable mode\",\n \"examples\": [\n \".\",\n \"../my-package\"\n ],\n \"title\": \"Editable\"\n }\n },\n \"title\": \"Environment\",\n \"type\": \"object\"\n },\n \"FileSystemSource\": {\n \"description\": \"Source for local Python files.\",\n \"properties\": {\n \"type\": {\n \"const\": \"filesystem\",\n \"default\": \"filesystem\",\n \"description\": \"Source type\",\n \"title\": \"Type\",\n \"type\": \"string\"\n },\n \"path\": {\n \"description\": \"Path to Python file containing the server\",\n \"title\": \"Path\",\n \"type\": \"string\"\n },\n \"entrypoint\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Name of server instance or factory function (a no-arg function that returns a FastMCP server)\",\n \"title\": \"Entrypoint\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"title\": \"FileSystemSource\",\n \"type\": \"object\"\n }\n },\n \"description\": \"Configuration file for FastMCP servers\",\n \"properties\": {\n \"$schema\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"description\": \"JSON schema for IDE support and validation\",\n \"title\": \"$Schema\"\n },\n \"source\": {\n \"$ref\": \"#/$defs/FileSystemSource\",\n \"description\": \"Source configuration for the server\",\n \"examples\": [\n {\n \"path\": \"server.py\"\n },\n {\n \"entrypoint\": \"app\",\n \"path\": \"server.py\"\n },\n {\n \"entrypoint\": \"mcp\",\n \"path\": \"src/server.py\",\n \"type\": \"filesystem\"\n }\n ]\n },\n \"environment\": {\n \"$ref\": \"#/$defs/Environment\",\n \"description\": \"Python environment setup configuration\"\n },\n \"deployment\": {\n \"$ref\": \"#/$defs/Deployment\",\n \"description\": \"Server deployment and runtime settings\"\n }\n },\n \"required\": [\n \"source\"\n ],\n \"title\": \"FastMCP Configuration\",\n \"type\": \"object\",\n \"$id\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\"\n}\n" }, { "path": "docs/assets/schemas/mcp_server_config/v1.json", "content": "{\n \"$defs\": {\n \"Deployment\": {\n \"description\": \"Configuration for server deployment and runtime settings.\",\n \"properties\": {\n \"transport\": {\n \"anyOf\": [\n {\n \"enum\": [\n \"stdio\",\n \"http\",\n \"sse\"\n ],\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Transport protocol to use\",\n \"title\": \"Transport\"\n },\n \"host\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Host to bind to when using HTTP transport\",\n \"examples\": [\n \"127.0.0.1\",\n \"0.0.0.0\",\n \"localhost\"\n ],\n \"title\": \"Host\"\n },\n \"port\": {\n \"anyOf\": [\n {\n \"type\": \"integer\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Port to bind to when using HTTP transport\",\n \"examples\": [\n 8000,\n 3000,\n 5000\n ],\n \"title\": \"Port\"\n },\n \"path\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"URL path for the server endpoint\",\n \"examples\": [\n \"/mcp/\",\n \"/api/mcp/\",\n \"/sse/\"\n ],\n \"title\": \"Path\"\n },\n \"log_level\": {\n \"anyOf\": [\n {\n \"enum\": [\n \"DEBUG\",\n \"INFO\",\n \"WARNING\",\n \"ERROR\",\n \"CRITICAL\"\n ],\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Log level for the server\",\n \"title\": \"Log Level\"\n },\n \"cwd\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Working directory for the server process\",\n \"examples\": [\n \".\",\n \"./src\",\n \"/app\"\n ],\n \"title\": \"Cwd\"\n },\n \"env\": {\n \"anyOf\": [\n {\n \"additionalProperties\": {\n \"type\": \"string\"\n },\n \"type\": \"object\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Environment variables to set when running the server\",\n \"examples\": [\n {\n \"API_KEY\": \"secret\",\n \"DEBUG\": \"true\"\n }\n ],\n \"title\": \"Env\"\n },\n \"args\": {\n \"anyOf\": [\n {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Arguments to pass to the server (after --)\",\n \"examples\": [\n [\n \"--config\",\n \"config.json\",\n \"--debug\"\n ]\n ],\n \"title\": \"Args\"\n }\n },\n \"title\": \"Deployment\",\n \"type\": \"object\"\n },\n \"Environment\": {\n \"description\": \"Configuration for Python environment setup.\",\n \"properties\": {\n \"python\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Python version constraint\",\n \"examples\": [\n \"3.10\",\n \"3.11\",\n \"3.12\"\n ],\n \"title\": \"Python\"\n },\n \"dependencies\": {\n \"anyOf\": [\n {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Python packages to install with PEP 508 specifiers\",\n \"examples\": [\n [\n \"fastmcp>=2.0,<3\",\n \"httpx\",\n \"pandas>=2.0\"\n ]\n ],\n \"title\": \"Dependencies\"\n },\n \"requirements\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Path to requirements.txt file\",\n \"examples\": [\n \"requirements.txt\",\n \"../requirements/prod.txt\"\n ],\n \"title\": \"Requirements\"\n },\n \"project\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Path to project directory containing pyproject.toml\",\n \"examples\": [\n \".\",\n \"../my-project\"\n ],\n \"title\": \"Project\"\n },\n \"editable\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Directory to install in editable mode\",\n \"examples\": [\n \".\",\n \"../my-package\"\n ],\n \"title\": \"Editable\"\n }\n },\n \"title\": \"Environment\",\n \"type\": \"object\"\n },\n \"FileSystemSource\": {\n \"description\": \"Source for local Python files.\",\n \"properties\": {\n \"type\": {\n \"const\": \"filesystem\",\n \"default\": \"filesystem\",\n \"description\": \"Source type\",\n \"title\": \"Type\",\n \"type\": \"string\"\n },\n \"path\": {\n \"description\": \"Path to Python file containing the server\",\n \"title\": \"Path\",\n \"type\": \"string\"\n },\n \"entrypoint\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": null,\n \"description\": \"Name of server instance or factory function (a no-arg function that returns a FastMCP server)\",\n \"title\": \"Entrypoint\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"title\": \"FileSystemSource\",\n \"type\": \"object\"\n }\n },\n \"description\": \"Configuration file for FastMCP servers\",\n \"properties\": {\n \"$schema\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"default\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"description\": \"JSON schema for IDE support and validation\",\n \"title\": \"$Schema\"\n },\n \"source\": {\n \"$ref\": \"#/$defs/FileSystemSource\",\n \"description\": \"Source configuration for the server\",\n \"examples\": [\n {\n \"path\": \"server.py\"\n },\n {\n \"entrypoint\": \"app\",\n \"path\": \"server.py\"\n },\n {\n \"entrypoint\": \"mcp\",\n \"path\": \"src/server.py\",\n \"type\": \"filesystem\"\n }\n ]\n },\n \"environment\": {\n \"$ref\": \"#/$defs/Environment\",\n \"description\": \"Python environment setup configuration\"\n },\n \"deployment\": {\n \"$ref\": \"#/$defs/Deployment\",\n \"description\": \"Server deployment and runtime settings\"\n }\n },\n \"required\": [\n \"source\"\n ],\n \"title\": \"FastMCP Configuration\",\n \"type\": \"object\",\n \"$id\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\"\n}\n" }, { "path": "docs/changelog.mdx", "content": "---\ntitle: \"Changelog\"\nicon: \"list-check\"\nrss: true\ntag: NEW\n---\n\n\n\n**[v3.0.2: Threecovery Mode II](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.2)**\n\nTwo 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.\n\n### Fixes 🐞\n* 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)\n* fix: propagate origin_request_id to background task workers by [@gfortaine](https://github.com/gfortaine) in [#3175](https://github.com/PrefectHQ/fastmcp/pull/3175)\n### Docs 📚\n* Add v3.0.1 release notes by [@jlowin](https://github.com/jlowin) in [#3259](https://github.com/PrefectHQ/fastmcp/pull/3259)\n* docs: add context-aware tool factory example by [@machov](https://github.com/machov) in [#3264](https://github.com/PrefectHQ/fastmcp/pull/3264)\n\n**Full Changelog**: [v3.0.1...v3.0.2](https://github.com/PrefectHQ/fastmcp/compare/v3.0.1...v3.0.2)\n\n\n\n\n\n**[v3.0.1: Three-covery Mode](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.1)**\n\nFirst 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.\n\n### Enhancements 🔧\n* Add verify_id_token option to OIDCProxy by [@jlowin](https://github.com/jlowin) in [#3248](https://github.com/PrefectHQ/fastmcp/pull/3248)\n### Fixes 🐞\n* Fix v3.0.0 changelog compare link by [@jlowin](https://github.com/jlowin) in [#3223](https://github.com/PrefectHQ/fastmcp/pull/3223)\n* Fix MDX parse error in upgrade guide prompts by [@jlowin](https://github.com/jlowin) in [#3227](https://github.com/PrefectHQ/fastmcp/pull/3227)\n* Fix non-serializable state lost between middleware and tools by [@jlowin](https://github.com/jlowin) in [#3234](https://github.com/PrefectHQ/fastmcp/pull/3234)\n* Accept callables in Tool.from_tool() by [@jlowin](https://github.com/jlowin) in [#3235](https://github.com/PrefectHQ/fastmcp/pull/3235)\n* Preserve skill metadata through provider wrapping by [@jlowin](https://github.com/jlowin) in [#3237](https://github.com/PrefectHQ/fastmcp/pull/3237)\n* Fix circular reference crash in OpenAPI schemas by [@jlowin](https://github.com/jlowin) in [#3245](https://github.com/PrefectHQ/fastmcp/pull/3245)\n* Fix NameError with future annotations and Context/Depends parameters by [@jlowin](https://github.com/jlowin) in [#3243](https://github.com/PrefectHQ/fastmcp/pull/3243)\n* Fix ty ignore syntax in OpenAPI provider by [@jlowin](https://github.com/jlowin) in [#3253](https://github.com/PrefectHQ/fastmcp/pull/3253)\n* 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)\n* Fix ty compatibility with upgraded deps by [@jlowin](https://github.com/jlowin) in [#3257](https://github.com/PrefectHQ/fastmcp/pull/3257)\n* Fix decorator overload return types for function mode by [@jlowin](https://github.com/jlowin) in [#3258](https://github.com/PrefectHQ/fastmcp/pull/3258)\n\n\n### Docs 📚\n* Sync README with welcome.mdx, fix install count by [@jlowin](https://github.com/jlowin) in [#3224](https://github.com/PrefectHQ/fastmcp/pull/3224)\n* Document dict-to-Message prompt migration in upgrade guides by [@jlowin](https://github.com/jlowin) in [#3225](https://github.com/PrefectHQ/fastmcp/pull/3225)\n* Fix v2 upgrade guide: remove incorrect v1 import advice by [@jlowin](https://github.com/jlowin) in [#3226](https://github.com/PrefectHQ/fastmcp/pull/3226)\n* Animated banner by [@jlowin](https://github.com/jlowin) in [#3231](https://github.com/PrefectHQ/fastmcp/pull/3231)\n* Document mounted server state store isolation in upgrade guide by [@jlowin](https://github.com/jlowin) in [#3236](https://github.com/PrefectHQ/fastmcp/pull/3236)\n\n**Full Changelog**: [v3.0.0...v3.0.1](https://github.com/PrefectHQ/fastmcp/compare/v3.0.0...v3.0.1)\n\n\n\n\n\n**[v3.0.0: Three at Last](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0)**\n\nFastMCP 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.\n\nThe 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.\n\nThis 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.\n\n### Build servers from anything\n\n🔌 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.\n\n### Ship to production\n\n🔐 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.\n\n### Adapt per session\n\n💾 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.\n\n### Develop faster\n\n⚡ `--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.\n\n### Use FastMCP as a CLI\n\n🖥️ `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.\n\n### Build apps (3.1 preview)\n\n📱 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.\n\n---\n\nIf 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.\n\n```bash\npip install fastmcp -U\n```\n\n📖 [Documentation](https://gofastmcp.com)\n🚀 [Upgrade from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2)\n🔀 [Upgrade from MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk)\n\n## What's Changed\n### New Features 🎉\n* Refactor resource behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2611](https://github.com/PrefectHQ/fastmcp/pull/2611)\n* Refactor prompt behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2610](https://github.com/PrefectHQ/fastmcp/pull/2610)\n* feat: Provider abstraction for dynamic MCP components by [@jlowin](https://github.com/jlowin) in [#2622](https://github.com/PrefectHQ/fastmcp/pull/2622)\n* Unify component storage in LocalProvider by [@jlowin](https://github.com/jlowin) in [#2680](https://github.com/PrefectHQ/fastmcp/pull/2680)\n* Introduce ResourceResult as canonical resource return type by [@jlowin](https://github.com/jlowin) in [#2734](https://github.com/PrefectHQ/fastmcp/pull/2734)\n* Introduce Message and PromptResult as canonical prompt types by [@jlowin](https://github.com/jlowin) in [#2738](https://github.com/PrefectHQ/fastmcp/pull/2738)\n* Add --reload flag for auto-restart on file changes by [@jlowin](https://github.com/jlowin) in [#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)\n* Add FileSystemProvider for filesystem-based component discovery by [@jlowin](https://github.com/jlowin) in [#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)\n* Add standalone decorators and eliminate fastmcp.fs module by [@jlowin](https://github.com/jlowin) in [#2832](https://github.com/PrefectHQ/fastmcp/pull/2832)\n* Add authorization checks to components and servers by [@jlowin](https://github.com/jlowin) in [#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)\n* Decorators return functions instead of component objects by [@jlowin](https://github.com/jlowin) in [#2856](https://github.com/PrefectHQ/fastmcp/pull/2856)\n* Add transform system for modifying components in provider chains by [@jlowin](https://github.com/jlowin) in [#2836](https://github.com/PrefectHQ/fastmcp/pull/2836)\n* Add OpenTelemetry tracing support by [@chrisguidry](https://github.com/chrisguidry) in [#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)\n* Add component versioning and VersionFilter transform by [@jlowin](https://github.com/jlowin) in [#2894](https://github.com/PrefectHQ/fastmcp/pull/2894)\n* 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)\n* Refactor visibility to mark-based enabled system by [@jlowin](https://github.com/jlowin) in [#2912](https://github.com/PrefectHQ/fastmcp/pull/2912)\n* Add session-specific visibility control via Context by [@jlowin](https://github.com/jlowin) in [#2917](https://github.com/PrefectHQ/fastmcp/pull/2917)\n* 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)\n* Add MCP Apps Phase 1 — SDK compatibility (SEP-1865) by [@jlowin](https://github.com/jlowin) in [#3009](https://github.com/PrefectHQ/fastmcp/pull/3009)\n* Add `fastmcp list` and `fastmcp call` CLI commands by [@jlowin](https://github.com/jlowin) in [#3054](https://github.com/PrefectHQ/fastmcp/pull/3054)\n* Add `fastmcp generate-cli` command by [@jlowin](https://github.com/jlowin) in [#3065](https://github.com/PrefectHQ/fastmcp/pull/3065)\n* Add CIMD (Client ID Metadata Document) support for OAuth by [@jlowin](https://github.com/jlowin) in [#2871](https://github.com/PrefectHQ/fastmcp/pull/2871)\n\n\n### Enhancements 🔧\n* Convert mounted servers to MountedProvider by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)\n* Simplify .key as computed property by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)\n* Refactor MountedProvider into FastMCPProvider + TransformingProvider by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)\n* Enable background task support for custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2657](https://github.com/PrefectHQ/fastmcp/pull/2657)\n* Use CreateTaskResult for background task creation by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)\n* Refactor provider execution: components own their execution by [@jlowin](https://github.com/jlowin) in [#2663](https://github.com/PrefectHQ/fastmcp/pull/2663)\n* Add supports_tasks() method to replace string mode checks by [@jlowin](https://github.com/jlowin) in [#2664](https://github.com/PrefectHQ/fastmcp/pull/2664)\n* 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)\n* Add poll_interval to TaskConfig by [@jlowin](https://github.com/jlowin) in [#2666](https://github.com/PrefectHQ/fastmcp/pull/2666)\n* 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)\n* Refactor FastMCPProxy into ProxyProvider by [@jlowin](https://github.com/jlowin) in [#2669](https://github.com/PrefectHQ/fastmcp/pull/2669)\n* Move OpenAPI to providers/openapi submodule by [@jlowin](https://github.com/jlowin) in [#2672](https://github.com/PrefectHQ/fastmcp/pull/2672)\n* Use ergonomic provider initialization pattern by [@jlowin](https://github.com/jlowin) in [#2675](https://github.com/PrefectHQ/fastmcp/pull/2675)\n* Fix ty 0.0.5 type errors by [@jlowin](https://github.com/jlowin) in [#2676](https://github.com/PrefectHQ/fastmcp/pull/2676)\n* Remove execution methods from Provider base class by [@jlowin](https://github.com/jlowin) in [#2681](https://github.com/PrefectHQ/fastmcp/pull/2681)\n* Add type-prefixed keys for globally unique component identification by [@jlowin](https://github.com/jlowin) in [#2704](https://github.com/PrefectHQ/fastmcp/pull/2704)\n* Consolidate notification system with unified API by [@jlowin](https://github.com/jlowin) in [#2710](https://github.com/PrefectHQ/fastmcp/pull/2710)\n* Parallelize provider operations by [@jlowin](https://github.com/jlowin) in [#2716](https://github.com/PrefectHQ/fastmcp/pull/2716)\n* Consolidate get_* and _list_* methods into single API by [@jlowin](https://github.com/jlowin) in [#2719](https://github.com/PrefectHQ/fastmcp/pull/2719)\n* Consolidate execution method chains into single public API by [@jlowin](https://github.com/jlowin) in [#2728](https://github.com/PrefectHQ/fastmcp/pull/2728)\n* Parallelize list_* calls in Provider.get_tasks() by [@jlowin](https://github.com/jlowin) in [#2731](https://github.com/PrefectHQ/fastmcp/pull/2731)\n* Consistent decorator-based MCP handler registration by [@jlowin](https://github.com/jlowin) in [#2732](https://github.com/PrefectHQ/fastmcp/pull/2732)\n* Make ToolResult a BaseModel for serialization support by [@jlowin](https://github.com/jlowin) in [#2736](https://github.com/PrefectHQ/fastmcp/pull/2736)\n* Align prompt handler with resource pattern by [@jlowin](https://github.com/jlowin) in [#2740](https://github.com/PrefectHQ/fastmcp/pull/2740)\n* Update classes to inherit from FastMCPBaseModel instead of BaseModel by [@jlowin](https://github.com/jlowin) in [#2739](https://github.com/PrefectHQ/fastmcp/pull/2739)\n* Add explicit task_meta parameter to FastMCP.call_tool() by [@jlowin](https://github.com/jlowin) in [#2749](https://github.com/PrefectHQ/fastmcp/pull/2749)\n* 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)\n* 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)\n* Remove unused include_tags/exclude_tags settings by [@jlowin](https://github.com/jlowin) in [#2756](https://github.com/PrefectHQ/fastmcp/pull/2756)\n* Parallelize provider access when executing components by [@jlowin](https://github.com/jlowin) in [#2744](https://github.com/PrefectHQ/fastmcp/pull/2744)\n* Deprecate tool_serializer parameter by [@jlowin](https://github.com/jlowin) in [#2753](https://github.com/PrefectHQ/fastmcp/pull/2753)\n* Feature/supabase custom auth route by [@EloiZalczer](https://github.com/EloiZalczer) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)\n* Remove deprecated WSTransport by [@jlowin](https://github.com/jlowin) in [#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)\n* Add composable lifespans by [@jlowin](https://github.com/jlowin) in [#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)\n* Replace FastMCP.as_proxy() with create_proxy() function by [@jlowin](https://github.com/jlowin) in [#2829](https://github.com/PrefectHQ/fastmcp/pull/2829)\n* Add PingMiddleware for keepalive connections by [@jlowin](https://github.com/jlowin) in [#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)\n* Run sync tools/resources/prompts in threadpool automatically by [@jlowin](https://github.com/jlowin) in [#2865](https://github.com/PrefectHQ/fastmcp/pull/2865)\n* Add timeout parameter for tool foreground execution by [@jlowin](https://github.com/jlowin) in [#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)\n* Adopt OpenTelemetry MCP semantic conventions by [@chrisguidry](https://github.com/chrisguidry) in [#2886](https://github.com/PrefectHQ/fastmcp/pull/2886)\n* Add client_secret_post authentication to IntrospectionTokenVerifier by [@shulkx](https://github.com/shulkx) in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)\n* Add enable_rich_logging setting to disable rich formatting by [@strawgate](https://github.com/strawgate) in [#2893](https://github.com/PrefectHQ/fastmcp/pull/2893)\n* 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)\n* Refactor FastMCP to inherit from Provider by [@jlowin](https://github.com/jlowin) in [#2901](https://github.com/PrefectHQ/fastmcp/pull/2901)\n* Swap public/private method naming in Provider by [@jlowin](https://github.com/jlowin) in [#2902](https://github.com/PrefectHQ/fastmcp/pull/2902)\n* Add MCP-compliant pagination support by [@jlowin](https://github.com/jlowin) in [#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)\n* Support VersionSpec in enable/disable for range-based filtering by [@jlowin](https://github.com/jlowin) in [#2914](https://github.com/PrefectHQ/fastmcp/pull/2914)\n* Immutable transform wrapping for providers by [@jlowin](https://github.com/jlowin) in [#2913](https://github.com/PrefectHQ/fastmcp/pull/2913)\n* Unify discovery API: deduplicate at protocol layer only by [@jlowin](https://github.com/jlowin) in [#2919](https://github.com/PrefectHQ/fastmcp/pull/2919)\n* Add ResourcesAsTools transform by [@jlowin](https://github.com/jlowin) in [#2943](https://github.com/PrefectHQ/fastmcp/pull/2943)\n* Add PromptsAsTools transform by [@jlowin](https://github.com/jlowin) in [#2946](https://github.com/PrefectHQ/fastmcp/pull/2946)\n* Rename Enabled transform to Visibility by [@jlowin](https://github.com/jlowin) in [#2950](https://github.com/PrefectHQ/fastmcp/pull/2950)\n* 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)\n* 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)\n* feat: expand --reload to watch frontend file types by [@jlowin](https://github.com/jlowin) in [#3028](https://github.com/PrefectHQ/fastmcp/pull/3028)\n* Add `fastmcp install stdio` command by [@jlowin](https://github.com/jlowin) in [#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)\n* feat: Goose integration + dedicated install command by [@jlowin](https://github.com/jlowin) in [#3040](https://github.com/PrefectHQ/fastmcp/pull/3040)\n* Add `fastmcp discover` and name-based server resolution by [@jlowin](https://github.com/jlowin) in [#3055](https://github.com/PrefectHQ/fastmcp/pull/3055)\n* feat(context): Add background task support for Context by [@gfortaine](https://github.com/gfortaine) in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)\n* Add server version to banner by [@richardkmichael](https://github.com/richardkmichael) in [#3076](https://github.com/PrefectHQ/fastmcp/pull/3076)\n* Add @handle_tool_errors decorator for standardized error handling by [@dgenio](https://github.com/dgenio) in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)\n* Add ResponseLimitingMiddleware for tool response size control by [@dgenio](https://github.com/dgenio) in [#3072](https://github.com/PrefectHQ/fastmcp/pull/3072)\n* Infer MIME types from OpenAPI response definitions by [@jlowin](https://github.com/jlowin) in [#3101](https://github.com/PrefectHQ/fastmcp/pull/3101)\n* Remove require_auth in favor of scope-based authorization by [@jlowin](https://github.com/jlowin) in [#3103](https://github.com/PrefectHQ/fastmcp/pull/3103)\n* generate-cli: auto-generate SKILL.md agent skill by [@jlowin](https://github.com/jlowin) in [#3115](https://github.com/PrefectHQ/fastmcp/pull/3115)\n* Add Azure OBO dependencies, auth token injection, and documentation by [@jlowin](https://github.com/jlowin) in [#2918](https://github.com/PrefectHQ/fastmcp/pull/2918)\n* feat: add Static Client Registration by [@martimfasantos](https://github.com/martimfasantos) in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)\n* Add concurrent tool execution with sequential flag by [@strawgate](https://github.com/strawgate) in [#3022](https://github.com/PrefectHQ/fastmcp/pull/3022)\n* Add validate_output option for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#3134](https://github.com/PrefectHQ/fastmcp/pull/3134)\n* Relay task elicitation through standard MCP protocol by [@chrisguidry](https://github.com/chrisguidry) in [#3136](https://github.com/PrefectHQ/fastmcp/pull/3136)\n* Support async auth checks by [@jlowin](https://github.com/jlowin) in [#3152](https://github.com/PrefectHQ/fastmcp/pull/3152)\n* Make $ref dereferencing optional via FastMCP(dereference_refs=...) by [@jlowin](https://github.com/jlowin) in [#3151](https://github.com/PrefectHQ/fastmcp/pull/3151)\n* Expose local_provider property, deprecate FastMCP.remove_tool() by [@jlowin](https://github.com/jlowin) in [#3155](https://github.com/PrefectHQ/fastmcp/pull/3155)\n* Add helpers for converting FunctionTool and TransformedTool to SamplingTool by [@strawgate](https://github.com/strawgate) in [#3062](https://github.com/PrefectHQ/fastmcp/pull/3062)\n### Fixes 🐞\n* Let FastMCPError propagate from dependencies by [@chrisguidry](https://github.com/chrisguidry) in [#2646](https://github.com/PrefectHQ/fastmcp/pull/2646)\n* Fix task execution for tools with custom names by [@chrisguidry](https://github.com/chrisguidry) in [#2645](https://github.com/PrefectHQ/fastmcp/pull/2645)\n* fix: check the cause of the tool error by [@rjolaverria](https://github.com/rjolaverria) in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)\n* Fix uvicorn 0.39+ test timeouts and FastMCPError propagation by [@jlowin](https://github.com/jlowin) in [#2699](https://github.com/PrefectHQ/fastmcp/pull/2699)\n* 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)\n* Fix Proxy provider to return all resource contents by [@jlowin](https://github.com/jlowin) in [#2742](https://github.com/PrefectHQ/fastmcp/pull/2742)\n* 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)\n* Fix rate limit detection during teardown phase by [@jlowin](https://github.com/jlowin) in [#2757](https://github.com/PrefectHQ/fastmcp/pull/2757)\n* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2764](https://github.com/PrefectHQ/fastmcp/pull/2764)\n* Fix `openapi_version` check so 3.1 is included by [@deeleeramone](https://github.com/deeleeramone) in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)\n* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)\n* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2784](https://github.com/PrefectHQ/fastmcp/pull/2784)\n* Fix OAuth token storage TTL calculation by [@jlowin](https://github.com/jlowin) in [#2796](https://github.com/PrefectHQ/fastmcp/pull/2796)\n* Fix client hanging on HTTP 4xx/5xx errors by [@jlowin](https://github.com/jlowin) in [#2803](https://github.com/PrefectHQ/fastmcp/pull/2803)\n* Fix keep_alive passthrough in StdioMCPServer.to_transport() by [@jlowin](https://github.com/jlowin) in [#2791](https://github.com/PrefectHQ/fastmcp/pull/2791)\n* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2808](https://github.com/PrefectHQ/fastmcp/pull/2808)\n* 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)\n* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2844](https://github.com/PrefectHQ/fastmcp/pull/2844)\n* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2849](https://github.com/PrefectHQ/fastmcp/pull/2849)\n* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2875](https://github.com/PrefectHQ/fastmcp/pull/2875)\n* 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)\n* fix: correctly send resource when exchanging code for upstream by [@JonasKs](https://github.com/JonasKs) in [#3013](https://github.com/PrefectHQ/fastmcp/pull/3013)\n* 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)\n* 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)\n* 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)\n* Fix tool_choice reset for structured output sampling by [@strawgate](https://github.com/strawgate) in [#3014](https://github.com/PrefectHQ/fastmcp/pull/3014)\n* fix: Preserve metadata in FastMCPProvider component wrappers by [@NeelayS](https://github.com/NeelayS) in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)\n* 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)\n* Fix --reload port conflict when using explicit port by [@jlowin](https://github.com/jlowin) in [#3070](https://github.com/PrefectHQ/fastmcp/pull/3070)\n* Fix compress_schema to preserve additionalProperties: false by [@jlowin](https://github.com/jlowin) in [#3102](https://github.com/PrefectHQ/fastmcp/pull/3102)\n* Fix CIMD redirect allowlist bypass and cache revalidation by [@jlowin](https://github.com/jlowin) in [#3098](https://github.com/PrefectHQ/fastmcp/pull/3098)\n* Fix session visibility marks leaking across sessions by [@jlowin](https://github.com/jlowin) in [#3132](https://github.com/PrefectHQ/fastmcp/pull/3132)\n* Fix unhandled exceptions in OpenAPI POST tool calls by [@jlowin](https://github.com/jlowin) in [#3133](https://github.com/PrefectHQ/fastmcp/pull/3133)\n* feat: distributed notification queue + BLPOP elicitation for background tasks by [@gfortaine](https://github.com/gfortaine) in [#2906](https://github.com/PrefectHQ/fastmcp/pull/2906)\n* fix: snapshot access token for background tasks by [@gfortaine](https://github.com/gfortaine) in [#3138](https://github.com/PrefectHQ/fastmcp/pull/3138)\n* fix: guard client pagination loops against misbehaving servers by [@jlowin](https://github.com/jlowin) in [#3167](https://github.com/PrefectHQ/fastmcp/pull/3167)\n* Support non-serializable values in Context.set_state by [@jlowin](https://github.com/jlowin) in [#3171](https://github.com/PrefectHQ/fastmcp/pull/3171)\n* Fix stale request context in StatefulProxyClient handlers by [@jlowin](https://github.com/jlowin) in [#3172](https://github.com/PrefectHQ/fastmcp/pull/3172)\n* Drop diskcache dependency (CVE-2025-69872) by [@jlowin](https://github.com/jlowin) in [#3185](https://github.com/PrefectHQ/fastmcp/pull/3185)\n* Fix confused deputy attack via consent binding cookie by [@jlowin](https://github.com/jlowin) in [#3201](https://github.com/PrefectHQ/fastmcp/pull/3201)\n* 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)\n* Cache OBO credentials on AzureProvider for token reuse by [@jlowin](https://github.com/jlowin) in [#3212](https://github.com/PrefectHQ/fastmcp/pull/3212)\n* Fix invalid uv add command in upgrade guide by [@jlowin](https://github.com/jlowin) in [#3217](https://github.com/PrefectHQ/fastmcp/pull/3217)\n* Use standard traceparent/tracestate keys per OTel MCP semconv by [@chrisguidry](https://github.com/chrisguidry) in [#3221](https://github.com/PrefectHQ/fastmcp/pull/3221)\n### Breaking Changes 🛫\n* Add VisibilityFilter for hierarchical enable/disable by [@jlowin](https://github.com/jlowin) in [#2708](https://github.com/PrefectHQ/fastmcp/pull/2708)\n* Remove automatic environment variable loading from auth providers by [@jlowin](https://github.com/jlowin) in [#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)\n* Make pydocket optional and unify DI systems by [@jlowin](https://github.com/jlowin) in [#2835](https://github.com/PrefectHQ/fastmcp/pull/2835)\n* Add session-scoped state persistence by [@jlowin](https://github.com/jlowin) in [#2873](https://github.com/PrefectHQ/fastmcp/pull/2873)\n* 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)\n* Remove deprecated FastMCP() constructor kwargs by [@jlowin](https://github.com/jlowin) in [#3148](https://github.com/PrefectHQ/fastmcp/pull/3148)\n* Move `fastmcp dev` to `fastmcp dev inspector` by [@jlowin](https://github.com/jlowin) in [#3188](https://github.com/PrefectHQ/fastmcp/pull/3188)\n\n## New Contributors\n* [@ivanbelenky](https://github.com/ivanbelenky) made their first contribution in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)\n* [@rjolaverria](https://github.com/rjolaverria) made their first contribution in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)\n* [@mgoldsborough](https://github.com/mgoldsborough) made their first contribution in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)\n* [@Ashif4354](https://github.com/Ashif4354) made their first contribution in [#2707](https://github.com/PrefectHQ/fastmcp/pull/2707)\n* [@majiayu000](https://github.com/majiayu000) made their first contribution in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)\n* [@lgndluke](https://github.com/lgndluke) made their first contribution in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)\n* [@EloiZalczer](https://github.com/EloiZalczer) made their first contribution in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)\n* [@deeleeramone](https://github.com/deeleeramone) made their first contribution in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)\n* [@shea-parkes](https://github.com/shea-parkes) made their first contribution in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)\n* [@bryankthompson](https://github.com/bryankthompson) made their first contribution in [#2777](https://github.com/PrefectHQ/fastmcp/pull/2777)\n* [@bhbs](https://github.com/bhbs) made their first contribution in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)\n* [@shulkx](https://github.com/shulkx) made their first contribution in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)\n* [@abhijeethp](https://github.com/abhijeethp) made their first contribution in [#2967](https://github.com/PrefectHQ/fastmcp/pull/2967)\n* [@aminsamir45](https://github.com/aminsamir45) made their first contribution in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)\n* [@JonasKs](https://github.com/JonasKs) made their first contribution in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)\n* [@NeelayS](https://github.com/NeelayS) made their first contribution in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)\n* [@gfortaine](https://github.com/gfortaine) made their first contribution in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)\n* [@nathanwelsh8](https://github.com/nathanwelsh8) made their first contribution in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)\n* [@dgenio](https://github.com/dgenio) made their first contribution in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)\n* [@martimfasantos](https://github.com/martimfasantos) made their first contribution in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)\n* [@jfBiswajit](https://github.com/jfBiswajit) made their first contribution in [#3193](https://github.com/PrefectHQ/fastmcp/pull/3193)\n\n**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v3.0.0\n\n\n\n\n\n**[v3.0.0rc1: RC-ing is Believing](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0rc1)**\n\nFastMCP 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.\n\n🚨 **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.\n\n🔐 **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:\n\n```python\nfrom fastmcp.server.auth.providers.azure import EntraOBOToken\n\n@mcp.tool()\nasync def get_emails(\n graph_token: str = EntraOBOToken([\"https://graph.microsoft.com/Mail.Read\"]),\n):\n # OBO exchange already happened — just use the token\n ...\n```\n\n⚡ **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`.\n\n📡 **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`.\n\n✅ **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.\n\n## What's Changed\n### Enhancements 🔧\n* generate-cli: auto-generate SKILL.md agent skill by [@jlowin](https://github.com/jlowin) in [#3115](https://github.com/PrefectHQ/fastmcp/pull/3115)\n* Scope Martian triage to bug-labeled issues for jlowin by [@jlowin](https://github.com/jlowin) in [#3124](https://github.com/PrefectHQ/fastmcp/pull/3124)\n* Add Azure OBO dependencies, auth token injection, and documentation by [@jlowin](https://github.com/jlowin) in [#2918](https://github.com/PrefectHQ/fastmcp/pull/2918)\n* feat: add Static Client Registration (#3085) by [@martimfasantos](https://github.com/martimfasantos) in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)\n* Add concurrent tool execution with sequential flag by [@strawgate](https://github.com/strawgate) in [#3022](https://github.com/PrefectHQ/fastmcp/pull/3022)\n* Add validate_output option for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#3134](https://github.com/PrefectHQ/fastmcp/pull/3134)\n* Relay task elicitation through standard MCP protocol by [@chrisguidry](https://github.com/chrisguidry) in [#3136](https://github.com/PrefectHQ/fastmcp/pull/3136)\n* 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)\n* Support async auth checks by [@jlowin](https://github.com/jlowin) in [#3152](https://github.com/PrefectHQ/fastmcp/pull/3152)\n* Make $ref dereferencing optional via FastMCP(dereference_refs=...) by [@jlowin](https://github.com/jlowin) in [#3151](https://github.com/PrefectHQ/fastmcp/pull/3151)\n* Expose local_provider property, deprecate FastMCP.remove_tool() by [@jlowin](https://github.com/jlowin) in [#3155](https://github.com/PrefectHQ/fastmcp/pull/3155)\n* Add helpers for converting FunctionTool and TransformedTool to SamplingTool by [@strawgate](https://github.com/strawgate) in [#3062](https://github.com/PrefectHQ/fastmcp/pull/3062)\n* Updates to github actions / workflows for claude by [@strawgate](https://github.com/strawgate) in [#3157](https://github.com/PrefectHQ/fastmcp/pull/3157)\n### Fixes 🐞\n* Updated deprecation URL for V3 by [@SrzStephen](https://github.com/SrzStephen) in [#3108](https://github.com/PrefectHQ/fastmcp/pull/3108)\n* Fix Windows test timeouts in OAuth proxy provider tests by [@strawgate](https://github.com/strawgate) in [#3123](https://github.com/PrefectHQ/fastmcp/pull/3123)\n* Fix session visibility marks leaking across sessions by [@jlowin](https://github.com/jlowin) in [#3132](https://github.com/PrefectHQ/fastmcp/pull/3132)\n* Fix unhandled exceptions in OpenAPI POST tool calls by [@jlowin](https://github.com/jlowin) in [#3133](https://github.com/PrefectHQ/fastmcp/pull/3133)\n* feat: distributed notification queue + BLPOP elicitation for background tasks by [@gfortaine](https://github.com/gfortaine) in [#2906](https://github.com/PrefectHQ/fastmcp/pull/2906)\n* fix: snapshot access token for background tasks (#3095) by [@gfortaine](https://github.com/gfortaine) in [#3138](https://github.com/PrefectHQ/fastmcp/pull/3138)\n* Stop duplicating path parameter descriptions into tool prose by [@jlowin](https://github.com/jlowin) in [#3149](https://github.com/PrefectHQ/fastmcp/pull/3149)\n* fix: guard client pagination loops against misbehaving servers by [@jlowin](https://github.com/jlowin) in [#3167](https://github.com/PrefectHQ/fastmcp/pull/3167)\n* Fix stale get_* references in docs and examples by [@jlowin](https://github.com/jlowin) in [#3168](https://github.com/PrefectHQ/fastmcp/pull/3168)\n* Support non-serializable values in Context.set_state by [@jlowin](https://github.com/jlowin) in [#3171](https://github.com/PrefectHQ/fastmcp/pull/3171)\n* Fix stale request context in StatefulProxyClient handlers by [@jlowin](https://github.com/jlowin) in [#3172](https://github.com/PrefectHQ/fastmcp/pull/3172)\n### Breaking Changes 🛫\n* 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)\n* Remove deprecated FastMCP() constructor kwargs by [@jlowin](https://github.com/jlowin) in [#3148](https://github.com/PrefectHQ/fastmcp/pull/3148)\n### Docs 📚\n* Update docs to reference beta 2 by [@jlowin](https://github.com/jlowin) in [#3112](https://github.com/PrefectHQ/fastmcp/pull/3112)\n* docs: add pre-registered OAuth clients to v3-features by [@jlowin](https://github.com/jlowin) in [#3129](https://github.com/PrefectHQ/fastmcp/pull/3129)\n### Dependencies 📦\n* 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)\n### Other Changes 🦾\n* 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)\n* docs: remove nonexistent MSALApp from rc1 notes by [@jlowin](https://github.com/jlowin) in [#3146](https://github.com/PrefectHQ/fastmcp/pull/3146)\n\n## New Contributors\n* [@martimfasantos](https://github.com/martimfasantos) made their first contribution in [#3086](https://github.com/PrefectHQ/fastmcp/pull/3086)\n\n**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v3.0.0b2...v3.0.0rc1\n\n\n\n\n\n**[v3.0.0b2: 2 Fast 2 Beta](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b2)**\n\nFastMCP 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.\n\n🖥️ **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.\n\n🔐 **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`.\n\n📱 **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.\n\n⏳ **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.\n\n🛡️ **ResponseLimitingMiddleware** caps tool response sizes with UTF-8-safe truncation for text and schema-aware error handling for structured outputs.\n\n🪿 **Goose Integration** — `fastmcp install goose` generates deeplink URLs for one-command server installation into Goose.\n\n## What's Changed\n### New Features 🎉\n* Add MCP Apps Phase 1 — SDK compatibility (SEP-1865) by [@jlowin](https://github.com/jlowin) in [#3009](https://github.com/PrefectHQ/fastmcp/pull/3009)\n* Add `fastmcp list` and `fastmcp call` CLI commands by [@jlowin](https://github.com/jlowin) in [#3054](https://github.com/PrefectHQ/fastmcp/pull/3054)\n* Add `fastmcp generate-cli` command by [@jlowin](https://github.com/jlowin) in [#3065](https://github.com/PrefectHQ/fastmcp/pull/3065)\n* Add CIMD (Client ID Metadata Document) support for OAuth by [@jlowin](https://github.com/jlowin) in [#2871](https://github.com/PrefectHQ/fastmcp/pull/2871)\n### Enhancements 🔧\n* Make duplicate bot less aggressive by [@jlowin](https://github.com/jlowin) in [#2981](https://github.com/PrefectHQ/fastmcp/pull/2981)\n* Remove uv lockfile monitoring from Dependabot by [@jlowin](https://github.com/jlowin) in [#2986](https://github.com/PrefectHQ/fastmcp/pull/2986)\n* Run static checks with --upgrade, remove lockfile check by [@jlowin](https://github.com/jlowin) in [#2988](https://github.com/PrefectHQ/fastmcp/pull/2988)\n* Adjust workflow triggers for Marvin by [@strawgate](https://github.com/strawgate) in [#3010](https://github.com/PrefectHQ/fastmcp/pull/3010)\n* 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)\n* 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)\n* Fix ty 0.0.14 compatibility and upgrade dependencies by [@jlowin](https://github.com/jlowin) in [#3027](https://github.com/PrefectHQ/fastmcp/pull/3027)\n* 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)\n* feat: expand --reload to watch frontend file types by [@jlowin](https://github.com/jlowin) in [#3028](https://github.com/PrefectHQ/fastmcp/pull/3028)\n* Add `fastmcp install stdio` command by [@jlowin](https://github.com/jlowin) in [#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)\n* Update martian-issue-triage.yml for Workflow editing guidance by [@strawgate](https://github.com/strawgate) in [#3033](https://github.com/PrefectHQ/fastmcp/pull/3033)\n* feat: Goose integration + dedicated install command by [@jlowin](https://github.com/jlowin) in [#3040](https://github.com/PrefectHQ/fastmcp/pull/3040)\n* Fixing spelling issues in multiple files by [@didier-durand](https://github.com/didier-durand) in [#2996](https://github.com/PrefectHQ/fastmcp/pull/2996)\n* Add `fastmcp discover` and name-based server resolution by [@jlowin](https://github.com/jlowin) in [#3055](https://github.com/PrefectHQ/fastmcp/pull/3055)\n* 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)\n* Add server version to banner by [@richardkmichael](https://github.com/richardkmichael) in [#3076](https://github.com/PrefectHQ/fastmcp/pull/3076)\n* Add @handle_tool_errors decorator for standardized error handling by [@dgenio](https://github.com/dgenio) in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)\n* 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)\n* Add ResponseLimitingMiddleware for tool response size control by [@dgenio](https://github.com/dgenio) in [#3072](https://github.com/PrefectHQ/fastmcp/pull/3072)\n* Infer MIME types from OpenAPI response definitions by [@jlowin](https://github.com/jlowin) in [#3101](https://github.com/PrefectHQ/fastmcp/pull/3101)\n* Remove require_auth in favor of scope-based authorization by [@jlowin](https://github.com/jlowin) in [#3103](https://github.com/PrefectHQ/fastmcp/pull/3103)\n### Fixes 🐞\n* Fix FastAPI mounting examples in docs by [@jlowin](https://github.com/jlowin) in [#2962](https://github.com/PrefectHQ/fastmcp/pull/2962)\n* Remove outdated 'FastMCP 3.0 is coming!' CLI banner by [@jlowin](https://github.com/jlowin) in [#2974](https://github.com/PrefectHQ/fastmcp/pull/2974)\n* Pin httpx `< 1.0` and simplify beta install docs by [@jlowin](https://github.com/jlowin) in [#2975](https://github.com/PrefectHQ/fastmcp/pull/2975)\n* Add enabled field to ToolTransformConfig by [@jlowin](https://github.com/jlowin) in [#2991](https://github.com/PrefectHQ/fastmcp/pull/2991)\n* fix phue2 import in smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#2999](https://github.com/PrefectHQ/fastmcp/pull/2999)\n* 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)\n* fix: type narrowing for skills resource contents by [@strawgate](https://github.com/strawgate) in [#3023](https://github.com/PrefectHQ/fastmcp/pull/3023)\n* 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)\n* 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)\n* 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)\n* 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)\n* 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)\n* Fix tool_choice reset for structured output sampling by [@strawgate](https://github.com/strawgate) in [#3014](https://github.com/PrefectHQ/fastmcp/pull/3014)\n* Fix workflow notification URL formatting in upgrade checks by [@strawgate](https://github.com/strawgate) in [#3047](https://github.com/PrefectHQ/fastmcp/pull/3047)\n* Fix Field() handling in prompts by [@strawgate](https://github.com/strawgate) in [#3050](https://github.com/PrefectHQ/fastmcp/pull/3050)\n* 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)\n* fix: Preserve metadata in FastMCPProvider component wrappers by [@NeelayS](https://github.com/NeelayS) in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)\n* 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)\n* 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)\n* 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)\n* Fix --reload port conflict when using explicit port by [@jlowin](https://github.com/jlowin) in [#3070](https://github.com/PrefectHQ/fastmcp/pull/3070)\n* 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)\n* Fix CIMD redirect allowlist bypass and cache revalidation by [@jlowin](https://github.com/jlowin) in [#3098](https://github.com/PrefectHQ/fastmcp/pull/3098)\n* 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)\n### Docs 📚\n* Prepare docs for v3.0 beta release by [@jlowin](https://github.com/jlowin) in [#2954](https://github.com/PrefectHQ/fastmcp/pull/2954)\n* Restructure docs: move transforms to dedicated section by [@jlowin](https://github.com/jlowin) in [#2956](https://github.com/PrefectHQ/fastmcp/pull/2956)\n* Remove unnecessary pip warning by [@jlowin](https://github.com/jlowin) in [#2958](https://github.com/PrefectHQ/fastmcp/pull/2958)\n* Update example MCP version in installation docs by [@jlowin](https://github.com/jlowin) in [#2959](https://github.com/PrefectHQ/fastmcp/pull/2959)\n* Update brand images by [@jlowin](https://github.com/jlowin) in [#2960](https://github.com/PrefectHQ/fastmcp/pull/2960)\n* Restructure README and welcome page with motivated narrative by [@jlowin](https://github.com/jlowin) in [#2963](https://github.com/PrefectHQ/fastmcp/pull/2963)\n* Restructure README and docs with motivated narrative by [@jlowin](https://github.com/jlowin) in [#2964](https://github.com/PrefectHQ/fastmcp/pull/2964)\n* Favicon update and Prefect Horizon docs by [@jlowin](https://github.com/jlowin) in [#2978](https://github.com/PrefectHQ/fastmcp/pull/2978)\n* Add dependency injection documentation and DI-style dependencies by [@jlowin](https://github.com/jlowin) in [#2980](https://github.com/PrefectHQ/fastmcp/pull/2980)\n* docs: document expanded reload behavior and restructure beta sections by [@jlowin](https://github.com/jlowin) in [#3039](https://github.com/PrefectHQ/fastmcp/pull/3039)\n* Add output_schema caveat to response limiting docs by [@jlowin](https://github.com/jlowin) in [#3099](https://github.com/PrefectHQ/fastmcp/pull/3099)\n* Document token passthrough security in OAuth Proxy docs by [@jlowin](https://github.com/jlowin) in [#3100](https://github.com/PrefectHQ/fastmcp/pull/3100)\n### Dependencies 📦\n* Bump ty from 0.0.12 to 0.0.13 by @dependabot in [#2984](https://github.com/PrefectHQ/fastmcp/pull/2984)\n* Bump prek from 0.2.30 to 0.3.0 by @dependabot in [#2982](https://github.com/PrefectHQ/fastmcp/pull/2982)\n### Other Changes 🦾\n* 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)\n* Bump pydocket to 0.17.2 (memory leak fix) by [@chrisguidry](https://github.com/chrisguidry) in [#2998](https://github.com/PrefectHQ/fastmcp/pull/2998)\n* Add AzureJWTVerifier for Managed Identity token verification by [@jlowin](https://github.com/jlowin) in [#3058](https://github.com/PrefectHQ/fastmcp/pull/3058)\n* 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)\n* Add missing beta2 features to v3 release tracking by [@jlowin](https://github.com/jlowin) in [#3105](https://github.com/PrefectHQ/fastmcp/pull/3105)\n\n## New Contributors\n* [@abhijeethp](https://github.com/abhijeethp) made their first contribution in [#2967](https://github.com/PrefectHQ/fastmcp/pull/2967)\n* [@aminsamir45](https://github.com/aminsamir45) made their first contribution in [#3005](https://github.com/PrefectHQ/fastmcp/pull/3005)\n* [@JonasKs](https://github.com/JonasKs) made their first contribution in [#2997](https://github.com/PrefectHQ/fastmcp/pull/2997)\n* [@NeelayS](https://github.com/NeelayS) made their first contribution in [#3057](https://github.com/PrefectHQ/fastmcp/pull/3057)\n* [@gfortaine](https://github.com/gfortaine) made their first contribution in [#2905](https://github.com/PrefectHQ/fastmcp/pull/2905)\n* [@nathanwelsh8](https://github.com/nathanwelsh8) made their first contribution in [#3066](https://github.com/PrefectHQ/fastmcp/pull/3066)\n* [@dgenio](https://github.com/dgenio) made their first contribution in [#2885](https://github.com/PrefectHQ/fastmcp/pull/2885)\n\n**Full Changelog**: https://github.com/PrefectHQ/fastmcp/compare/v3.0.0b1...v3.0.0b2\n\n\n\n\n\n**[v3.0.0b1: This Beta Work](https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0b1)**\n\nFastMCP 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.\n\n🔌 **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.\n\n🔄 **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.\n\n📋 **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.\n\n💾 **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.\n\n⚡ **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.\n\n🔐 **Component Authorization** via `@tool(auth=require_scopes(\"admin\"))` and `AuthMiddleware` for server-wide policies.\n\nBreaking 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.\n\n## What's Changed\n### New Features 🎉\n* Refactor resource behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2611](https://github.com/PrefectHQ/fastmcp/pull/2611)\n* Refactor prompt behavior and add meta support by [@jlowin](https://github.com/jlowin) in [#2610](https://github.com/PrefectHQ/fastmcp/pull/2610)\n* feat: Provider abstraction for dynamic MCP components by [@jlowin](https://github.com/jlowin) in [#2622](https://github.com/PrefectHQ/fastmcp/pull/2622)\n* Unify component storage in LocalProvider by [@jlowin](https://github.com/jlowin) in [#2680](https://github.com/PrefectHQ/fastmcp/pull/2680)\n* Introduce ResourceResult as canonical resource return type by [@jlowin](https://github.com/jlowin) in [#2734](https://github.com/PrefectHQ/fastmcp/pull/2734)\n* Introduce Message and PromptResult as canonical prompt types by [@jlowin](https://github.com/jlowin) in [#2738](https://github.com/PrefectHQ/fastmcp/pull/2738)\n* Add --reload flag for auto-restart on file changes by [@jlowin](https://github.com/jlowin) in [#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)\n* Add FileSystemProvider for filesystem-based component discovery by [@jlowin](https://github.com/jlowin) in [#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)\n* Add standalone decorators and eliminate fastmcp.fs module by [@jlowin](https://github.com/jlowin) in [#2832](https://github.com/PrefectHQ/fastmcp/pull/2832)\n* Add authorization checks to components and servers by [@jlowin](https://github.com/jlowin) in [#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)\n* Decorators return functions instead of component objects by [@jlowin](https://github.com/jlowin) in [#2856](https://github.com/PrefectHQ/fastmcp/pull/2856)\n* Add transform system for modifying components in provider chains by [@jlowin](https://github.com/jlowin) in [#2836](https://github.com/PrefectHQ/fastmcp/pull/2836)\n* Add OpenTelemetry tracing support by [@chrisguidry](https://github.com/chrisguidry) in [#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)\n* Add component versioning and VersionFilter transform by [@jlowin](https://github.com/jlowin) in [#2894](https://github.com/PrefectHQ/fastmcp/pull/2894)\n* 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)\n* Refactor visibility to mark-based enabled system by [@jlowin](https://github.com/jlowin) in [#2912](https://github.com/PrefectHQ/fastmcp/pull/2912)\n* Add session-specific visibility control via Context by [@jlowin](https://github.com/jlowin) in [#2917](https://github.com/PrefectHQ/fastmcp/pull/2917)\n* 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)\n### Enhancements 🔧\n* Convert mounted servers to MountedProvider by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)\n* Simplify .key as computed property by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)\n* Refactor MountedProvider into FastMCPProvider + TransformingProvider by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)\n* Enable background task support for custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2657](https://github.com/PrefectHQ/fastmcp/pull/2657)\n* Use CreateTaskResult for background task creation by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)\n* Refactor provider execution: components own their execution by [@jlowin](https://github.com/jlowin) in [#2663](https://github.com/PrefectHQ/fastmcp/pull/2663)\n* Add supports_tasks() method to replace string mode checks by [@jlowin](https://github.com/jlowin) in [#2664](https://github.com/PrefectHQ/fastmcp/pull/2664)\n* 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)\n* Add poll_interval to TaskConfig by [@jlowin](https://github.com/jlowin) in [#2666](https://github.com/PrefectHQ/fastmcp/pull/2666)\n* 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)\n* Refactor FastMCPProxy into ProxyProvider by [@jlowin](https://github.com/jlowin) in [#2669](https://github.com/PrefectHQ/fastmcp/pull/2669)\n* Move OpenAPI to providers/openapi submodule by [@jlowin](https://github.com/jlowin) in [#2672](https://github.com/PrefectHQ/fastmcp/pull/2672)\n* Use ergonomic provider initialization pattern by [@jlowin](https://github.com/jlowin) in [#2675](https://github.com/PrefectHQ/fastmcp/pull/2675)\n* Fix ty 0.0.5 type errors by [@jlowin](https://github.com/jlowin) in [#2676](https://github.com/PrefectHQ/fastmcp/pull/2676)\n* Remove execution methods from Provider base class by [@jlowin](https://github.com/jlowin) in [#2681](https://github.com/PrefectHQ/fastmcp/pull/2681)\n* Add type-prefixed keys for globally unique component identification by [@jlowin](https://github.com/jlowin) in [#2704](https://github.com/PrefectHQ/fastmcp/pull/2704)\n* Skip parallel MCP config test on Windows by [@jlowin](https://github.com/jlowin) in [#2711](https://github.com/PrefectHQ/fastmcp/pull/2711)\n* Consolidate notification system with unified API by [@jlowin](https://github.com/jlowin) in [#2710](https://github.com/PrefectHQ/fastmcp/pull/2710)\n* Skip test_multi_client on Windows by [@jlowin](https://github.com/jlowin) in [#2714](https://github.com/PrefectHQ/fastmcp/pull/2714)\n* Parallelize provider operations by [@jlowin](https://github.com/jlowin) in [#2716](https://github.com/PrefectHQ/fastmcp/pull/2716)\n* Consolidate get_* and _list_* methods into single API by [@jlowin](https://github.com/jlowin) in [#2719](https://github.com/PrefectHQ/fastmcp/pull/2719)\n* Consolidate execution method chains into single public API by [@jlowin](https://github.com/jlowin) in [#2728](https://github.com/PrefectHQ/fastmcp/pull/2728)\n* Add documentation check to required PR workflow by [@jlowin](https://github.com/jlowin) in [#2730](https://github.com/PrefectHQ/fastmcp/pull/2730)\n* Parallelize list_* calls in Provider.get_tasks() by [@jlowin](https://github.com/jlowin) in [#2731](https://github.com/PrefectHQ/fastmcp/pull/2731)\n* Consistent decorator-based MCP handler registration by [@jlowin](https://github.com/jlowin) in [#2732](https://github.com/PrefectHQ/fastmcp/pull/2732)\n* Make ToolResult a BaseModel for serialization support by [@jlowin](https://github.com/jlowin) in [#2736](https://github.com/PrefectHQ/fastmcp/pull/2736)\n* Align prompt handler with resource pattern by [@jlowin](https://github.com/jlowin) in [#2740](https://github.com/PrefectHQ/fastmcp/pull/2740)\n* Update classes to inherit from FastMCPBaseModel instead of BaseModel by [@jlowin](https://github.com/jlowin) in [#2739](https://github.com/PrefectHQ/fastmcp/pull/2739)\n* Convert provider tests to use direct server calls by [@jlowin](https://github.com/jlowin) in [#2748](https://github.com/PrefectHQ/fastmcp/pull/2748)\n* Add explicit task_meta parameter to FastMCP.call_tool() by [@jlowin](https://github.com/jlowin) in [#2749](https://github.com/PrefectHQ/fastmcp/pull/2749)\n* 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)\n* 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)\n* Remove unused include_tags/exclude_tags settings by [@jlowin](https://github.com/jlowin) in [#2756](https://github.com/PrefectHQ/fastmcp/pull/2756)\n* Parallelize provider access when executing components by [@jlowin](https://github.com/jlowin) in [#2744](https://github.com/PrefectHQ/fastmcp/pull/2744)\n* Add tests for OAuth generator cleanup and use aclosing by [@jlowin](https://github.com/jlowin) in [#2759](https://github.com/PrefectHQ/fastmcp/pull/2759)\n* Deprecate tool_serializer parameter by [@jlowin](https://github.com/jlowin) in [#2753](https://github.com/PrefectHQ/fastmcp/pull/2753)\n* Feature/supabase custom auth route by [@EloiZalczer](https://github.com/EloiZalczer) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)\n* Add regression tests for caching with mounted server prefixes by [@jlowin](https://github.com/jlowin) in [#2762](https://github.com/PrefectHQ/fastmcp/pull/2762)\n* Update CLI banner with FastMCP 3.0 notice by [@jlowin](https://github.com/jlowin) in [#2766](https://github.com/PrefectHQ/fastmcp/pull/2766)\n* 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)\n* 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)\n* 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)\n* Turn off negative CLI flags by default by [@jlowin](https://github.com/jlowin) in [#2801](https://github.com/PrefectHQ/fastmcp/pull/2801)\n* Configure ty to fail on warnings by [@jlowin](https://github.com/jlowin) in [#2804](https://github.com/PrefectHQ/fastmcp/pull/2804)\n* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2814](https://github.com/PrefectHQ/fastmcp/pull/2814)\n* Add v3.0 feature tracking document by [@jlowin](https://github.com/jlowin) in [#2822](https://github.com/PrefectHQ/fastmcp/pull/2822)\n* Remove deprecated WSTransport by [@jlowin](https://github.com/jlowin) in [#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)\n* Add composable lifespans by [@jlowin](https://github.com/jlowin) in [#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)\n* Replace FastMCP.as_proxy() with create_proxy() function by [@jlowin](https://github.com/jlowin) in [#2829](https://github.com/PrefectHQ/fastmcp/pull/2829)\n* 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)\n* Add PingMiddleware for keepalive connections by [@jlowin](https://github.com/jlowin) in [#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)\n* Add CLI update notifications by [@jlowin](https://github.com/jlowin) in [#2840](https://github.com/PrefectHQ/fastmcp/pull/2840)\n* Add agent skills for testing and code review by [@jlowin](https://github.com/jlowin) in [#2846](https://github.com/PrefectHQ/fastmcp/pull/2846)\n* Add loq pre-commit hook for file size enforcement by [@jlowin](https://github.com/jlowin) in [#2847](https://github.com/PrefectHQ/fastmcp/pull/2847)\n* Add transport property to Context by [@jlowin](https://github.com/jlowin) in [#2850](https://github.com/PrefectHQ/fastmcp/pull/2850)\n* 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)\n* Run sync tools/resources/prompts in threadpool automatically by [@jlowin](https://github.com/jlowin) in [#2865](https://github.com/PrefectHQ/fastmcp/pull/2865)\n* Add timeout parameter for tool foreground execution by [@jlowin](https://github.com/jlowin) in [#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)\n* Adopt OpenTelemetry MCP semantic conventions by [@chrisguidry](https://github.com/chrisguidry) in [#2886](https://github.com/PrefectHQ/fastmcp/pull/2886)\n* Add client_secret_post authentication to IntrospectionTokenVerifier by [@shulkx](https://github.com/shulkx) in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)\n* Add enable_rich_logging setting to disable rich formatting by [@strawgate](https://github.com/strawgate) in [#2893](https://github.com/PrefectHQ/fastmcp/pull/2893)\n* 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)\n* Refactor FastMCP to inherit from Provider by [@jlowin](https://github.com/jlowin) in [#2901](https://github.com/PrefectHQ/fastmcp/pull/2901)\n* Swap public/private method naming in Provider by [@jlowin](https://github.com/jlowin) in [#2902](https://github.com/PrefectHQ/fastmcp/pull/2902)\n* Add MCP-compliant pagination support by [@jlowin](https://github.com/jlowin) in [#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)\n* Support VersionSpec in enable/disable for range-based filtering by [@jlowin](https://github.com/jlowin) in [#2914](https://github.com/PrefectHQ/fastmcp/pull/2914)\n* Remove sync notification infrastructure by [@jlowin](https://github.com/jlowin) in [#2915](https://github.com/PrefectHQ/fastmcp/pull/2915)\n* Immutable transform wrapping for providers by [@jlowin](https://github.com/jlowin) in [#2913](https://github.com/PrefectHQ/fastmcp/pull/2913)\n* Unify discovery API: deduplicate at protocol layer only by [@jlowin](https://github.com/jlowin) in [#2919](https://github.com/PrefectHQ/fastmcp/pull/2919)\n* Split transports.py into modular structure by [@jlowin](https://github.com/jlowin) in [#2921](https://github.com/PrefectHQ/fastmcp/pull/2921)\n* Move session visibility logic to enabled.py by [@jlowin](https://github.com/jlowin) in [#2924](https://github.com/PrefectHQ/fastmcp/pull/2924)\n* Refactor Client class into mixins and add timeout utilities by [@jlowin](https://github.com/jlowin) in [#2933](https://github.com/PrefectHQ/fastmcp/pull/2933)\n* Refactor OAuthProxy into focused modules by [@jlowin](https://github.com/jlowin) in [#2935](https://github.com/PrefectHQ/fastmcp/pull/2935)\n* Refactor LocalProvider into mixin modules by [@jlowin](https://github.com/jlowin) in [#2936](https://github.com/PrefectHQ/fastmcp/pull/2936)\n* Refactor server.py into mixins by [@jlowin](https://github.com/jlowin) in [#2939](https://github.com/PrefectHQ/fastmcp/pull/2939)\n* Consolidate test fixtures and refactor large test files by [@jlowin](https://github.com/jlowin) in [#2941](https://github.com/PrefectHQ/fastmcp/pull/2941)\n* Refactor transform list methods to pure function pattern by [@jlowin](https://github.com/jlowin) in [#2942](https://github.com/PrefectHQ/fastmcp/pull/2942)\n* Add ResourcesAsTools transform by [@jlowin](https://github.com/jlowin) in [#2943](https://github.com/PrefectHQ/fastmcp/pull/2943)\n* Add PromptsAsTools transform by [@jlowin](https://github.com/jlowin) in [#2946](https://github.com/PrefectHQ/fastmcp/pull/2946)\n* Add client utilities for downloading skills by [@jlowin](https://github.com/jlowin) in [#2948](https://github.com/PrefectHQ/fastmcp/pull/2948)\n* Rename Enabled transform to Visibility by [@jlowin](https://github.com/jlowin) in [#2950](https://github.com/PrefectHQ/fastmcp/pull/2950)\n### Fixes 🐞\n* Let FastMCPError propagate from dependencies by [@chrisguidry](https://github.com/chrisguidry) in [#2646](https://github.com/PrefectHQ/fastmcp/pull/2646)\n* Fix task execution for tools with custom names by [@chrisguidry](https://github.com/chrisguidry) in [#2645](https://github.com/PrefectHQ/fastmcp/pull/2645)\n* fix: check the cause of the tool error by [@rjolaverria](https://github.com/rjolaverria) in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)\n* 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)\n* Fix uvicorn 0.39+ test timeouts and FastMCPError propagation by [@jlowin](https://github.com/jlowin) in [#2699](https://github.com/PrefectHQ/fastmcp/pull/2699)\n* Fix Prefect website URL in docs footer by [@mgoldsborough](https://github.com/mgoldsborough) in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)\n* 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)\n* Fix Provider.get_tasks() to include custom component subclasses by [@jlowin](https://github.com/jlowin) in [#2729](https://github.com/PrefectHQ/fastmcp/pull/2729)\n* Fix Proxy provider to return all resource contents by [@jlowin](https://github.com/jlowin) in [#2742](https://github.com/PrefectHQ/fastmcp/pull/2742)\n* Fix prompt return type documentation by [@jlowin](https://github.com/jlowin) in [#2741](https://github.com/PrefectHQ/fastmcp/pull/2741)\n* 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)\n* Fix rate limit detection during teardown phase by [@jlowin](https://github.com/jlowin) in [#2757](https://github.com/PrefectHQ/fastmcp/pull/2757)\n* 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)\n* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2764](https://github.com/PrefectHQ/fastmcp/pull/2764)\n* [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)\n* 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)\n* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)\n* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2784](https://github.com/PrefectHQ/fastmcp/pull/2784)\n* Fix OAuth token storage TTL calculation by [@jlowin](https://github.com/jlowin) in [#2796](https://github.com/PrefectHQ/fastmcp/pull/2796)\n* Use consistent refresh_ttl for JTI mapping store by [@jlowin](https://github.com/jlowin) in [#2799](https://github.com/PrefectHQ/fastmcp/pull/2799)\n* 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)\n* Fix client hanging on HTTP 4xx/5xx errors by [@jlowin](https://github.com/jlowin) in [#2803](https://github.com/PrefectHQ/fastmcp/pull/2803)\n* Fix unawaited coroutine warning and treat as test error by [@jlowin](https://github.com/jlowin) in [#2806](https://github.com/PrefectHQ/fastmcp/pull/2806)\n* Fix keep_alive passthrough in StdioMCPServer.to_transport() by [@jlowin](https://github.com/jlowin) in [#2791](https://github.com/PrefectHQ/fastmcp/pull/2791)\n* Dereference $ref in tool schemas for MCP client compatibility by [@jlowin](https://github.com/jlowin) in [#2808](https://github.com/PrefectHQ/fastmcp/pull/2808)\n* Prefix Redis keys with docket name for ACL isolation by [@chrisguidry](https://github.com/chrisguidry) in [#2811](https://github.com/PrefectHQ/fastmcp/pull/2811)\n* fix smart_home example: HueAttributes schema and deprecated prefix by [@zzstoatzz](https://github.com/zzstoatzz) in [#2818](https://github.com/PrefectHQ/fastmcp/pull/2818)\n* Fix redirect URI validation docs to match implementation by [@jlowin](https://github.com/jlowin) in [#2824](https://github.com/PrefectHQ/fastmcp/pull/2824)\n* 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)\n* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2844](https://github.com/PrefectHQ/fastmcp/pull/2844)\n* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2849](https://github.com/PrefectHQ/fastmcp/pull/2849)\n* 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)\n* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2875](https://github.com/PrefectHQ/fastmcp/pull/2875)\n* 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)\n### Breaking Changes 🛫\n* Add VisibilityFilter for hierarchical enable/disable by [@jlowin](https://github.com/jlowin) in [#2708](https://github.com/PrefectHQ/fastmcp/pull/2708)\n* Remove automatic environment variable loading from auth providers by [@jlowin](https://github.com/jlowin) in [#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)\n* Make pydocket optional and unify DI systems by [@jlowin](https://github.com/jlowin) in [#2835](https://github.com/PrefectHQ/fastmcp/pull/2835)\n* Add session-scoped state persistence by [@jlowin](https://github.com/jlowin) in [#2873](https://github.com/PrefectHQ/fastmcp/pull/2873)\n### Docs 📚\n* Undocumented `McpError` exceptions by [@ivanbelenky](https://github.com/ivanbelenky) in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)\n* 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)\n* Add v3 breaking changes notice to README by [@jlowin](https://github.com/jlowin) in [#2712](https://github.com/PrefectHQ/fastmcp/pull/2712)\n* 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)\n* Reorganize docs around provider architecture by [@jlowin](https://github.com/jlowin) in [#2723](https://github.com/PrefectHQ/fastmcp/pull/2723)\n* 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)\n* Enhance documentation on tool transformation by [@shea-parkes](https://github.com/shea-parkes) in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)\n* Add FastMCP 4.0 preview to documentation by [@jlowin](https://github.com/jlowin) in [#2831](https://github.com/PrefectHQ/fastmcp/pull/2831)\n* 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)\n* 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)\n* Fix custom provider docs to show correct interface by [@jlowin](https://github.com/jlowin) in [#2920](https://github.com/PrefectHQ/fastmcp/pull/2920)\n* Update v3 features that were missed in PRs by [@jlowin](https://github.com/jlowin) in [#2947](https://github.com/PrefectHQ/fastmcp/pull/2947)\n* Restructure documentation for FastMCP 3.0 by [@jlowin](https://github.com/jlowin) in [#2951](https://github.com/PrefectHQ/fastmcp/pull/2951)\n* Fix broken documentation links by [@jlowin](https://github.com/jlowin) in [#2952](https://github.com/PrefectHQ/fastmcp/pull/2952)\n* Clarify installation for FastMCP 3.0 beta by [@jlowin](https://github.com/jlowin) in [#2953](https://github.com/PrefectHQ/fastmcp/pull/2953)\n### Dependencies 📦\n* 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)\n* Bump ty to 0.0.7+ by [@jlowin](https://github.com/jlowin) in [#2737](https://github.com/PrefectHQ/fastmcp/pull/2737)\n* 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)\n\n## New Contributors\n* [@ivanbelenky](https://github.com/ivanbelenky) made their first contribution in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)\n* [@rjolaverria](https://github.com/rjolaverria) made their first contribution in [#2674](https://github.com/PrefectHQ/fastmcp/pull/2674)\n* [@mgoldsborough](https://github.com/mgoldsborough) made their first contribution in [#2701](https://github.com/PrefectHQ/fastmcp/pull/2701)\n* [@Ashif4354](https://github.com/Ashif4354) made their first contribution in [#2707](https://github.com/PrefectHQ/fastmcp/pull/2707)\n* [@majiayu000](https://github.com/majiayu000) made their first contribution in [#2720](https://github.com/PrefectHQ/fastmcp/pull/2720)\n* [@lgndluke](https://github.com/lgndluke) made their first contribution in [#2644](https://github.com/PrefectHQ/fastmcp/pull/2644)\n* [@EloiZalczer](https://github.com/EloiZalczer) made their first contribution in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)\n* [@deeleeramone](https://github.com/deeleeramone) made their first contribution in [#2768](https://github.com/PrefectHQ/fastmcp/pull/2768)\n* [@shea-parkes](https://github.com/shea-parkes) made their first contribution in [#2781](https://github.com/PrefectHQ/fastmcp/pull/2781)\n* [@triepod-ai](https://github.com/triepod-ai) made their first contribution in [#2777](https://github.com/PrefectHQ/fastmcp/pull/2777)\n* [@bhbs](https://github.com/bhbs) made their first contribution in [#2776](https://github.com/PrefectHQ/fastmcp/pull/2776)\n* [@shulkx](https://github.com/shulkx) made their first contribution in [#2884](https://github.com/PrefectHQ/fastmcp/pull/2884)\n\n**Full Changelog**: [v2.14.1...v3.0.0b1](https://github.com/PrefectHQ/fastmcp/compare/v2.14.1...v3.0.0b1)\n\n\n\n\n\n**[v2.14.5: Sealed Docket](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.5)**\n\nFixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.\n\n## What's Changed\n### Enhancements 🔧\n* Bump pydocket to 0.17.2 (memory leak fix) by [@chrisguidry](https://github.com/chrisguidry) in [#2992](https://github.com/PrefectHQ/fastmcp/pull/2992)\n\n**Full Changelog**: [v2.14.4...v2.14.5](https://github.com/PrefectHQ/fastmcp/compare/v2.14.4...v2.14.5)\n\n\n\n\n\n**[v2.14.4: Package Deal](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.4)**\n\nFixes 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.\n\n## What's Changed\n### Enhancements 🔧\n* 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)\n### Fixes 🐞\n* 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)\n* Fix task capabilities location (issue #2870) by [@jlowin](https://github.com/jlowin) in [#2874](https://github.com/PrefectHQ/fastmcp/pull/2874)\n* Add missing packaging dependency by [@jlowin](https://github.com/jlowin) in [#2989](https://github.com/PrefectHQ/fastmcp/pull/2989)\n\n**Full Changelog**: [v2.14.3...v2.14.4](https://github.com/PrefectHQ/fastmcp/compare/v2.14.3...v2.14.4)\n\n\n\n\n\n**[v2.14.3: Time After Timeout](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.3)**\n\nSometimes 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.\n\n## What's Changed\n### Enhancements 🔧\n* Add debug logging for OAuth token expiry diagnostics by [@jlowin](https://github.com/jlowin) in [#2789](https://github.com/PrefectHQ/fastmcp/pull/2789)\n* Add CLI update notifications by [@jlowin](https://github.com/jlowin) in [#2839](https://github.com/PrefectHQ/fastmcp/pull/2839)\n* Use pip instead of uv pip in upgrade instructions by [@jlowin](https://github.com/jlowin) in [#2841](https://github.com/PrefectHQ/fastmcp/pull/2841)\n### Fixes 🐞\n* 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)\n* 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)\n* Fix ContextVar propagation for ASGI-mounted servers with tasks by [@chrisguidry](https://github.com/chrisguidry) in [#2843](https://github.com/PrefectHQ/fastmcp/pull/2843)\n* Fix HTTP transport timeout defaulting to 5 seconds by [@jlowin](https://github.com/jlowin) in [#2848](https://github.com/PrefectHQ/fastmcp/pull/2848)\n\n**Full Changelog**: [v2.14.2...v2.14.3](https://github.com/PrefectHQ/fastmcp/compare/v2.14.2...v2.14.3)\n\n\n\n\n\n**[v2.14.2: Port Authority](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.2)**\n\nFastMCP 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.\n\n## What's Changed\n### Enhancements 🔧\n* Pin MCP under 2.x by [@jlowin](https://github.com/jlowin) in [#2709](https://github.com/PrefectHQ/fastmcp/pull/2709)\n* Add auth_route parameter to SupabaseProvider by [@EloiZalczer](https://github.com/EloiZalczer) in [#2760](https://github.com/PrefectHQ/fastmcp/pull/2760)\n* Update CLI banner with FastMCP 3.0 notice by [@jlowin](https://github.com/jlowin) in [#2765](https://github.com/PrefectHQ/fastmcp/pull/2765)\n### Fixes 🐞\n* Let FastMCPError propagate unchanged from managers by [@jlowin](https://github.com/jlowin) in [#2697](https://github.com/PrefectHQ/fastmcp/pull/2697)\n* Fix test cleanup for uvicorn 0.39+ context isolation by [@jlowin](https://github.com/jlowin) in [#2696](https://github.com/PrefectHQ/fastmcp/pull/2696)\n* 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)\n* Fix Prefect website URL in docs footer by [@mgoldsborough](https://github.com/mgoldsborough) in [#2705](https://github.com/PrefectHQ/fastmcp/pull/2705)\n* 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)\n* Fix OAuth Proxy resource parameter validation by [@jlowin](https://github.com/jlowin) in [#2763](https://github.com/PrefectHQ/fastmcp/pull/2763)\n* Fix openapi_version check to include 3.1 by [@deeleeramone](https://github.com/deeleeramone) in [#2769](https://github.com/PrefectHQ/fastmcp/pull/2769)\n* 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)\n* Fix base_url fallback when url is not set by [@bhbs](https://github.com/bhbs) in [#2782](https://github.com/PrefectHQ/fastmcp/pull/2782)\n* Lazy import DiskStore to avoid sqlite3 dependency on import by [@jlowin](https://github.com/jlowin) in [#2785](https://github.com/PrefectHQ/fastmcp/pull/2785)\n### Docs 📚\n* Add v3 breaking changes notice to README and docs by [@jlowin](https://github.com/jlowin) in [#2713](https://github.com/PrefectHQ/fastmcp/pull/2713)\n* 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)\n* conference to 2.x branch by [@aaazzam](https://github.com/aaazzam) in [#2787](https://github.com/PrefectHQ/fastmcp/pull/2787)\n\n**Full Changelog**: [v2.14.1...v2.14.2](https://github.com/PrefectHQ/fastmcp/compare/v2.14.1...v2.14.2)\n\n\n\n\n\n**[v2.14.1: 'Tis a Gift to Be Sample](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.1)**\n\nFastMCP 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.\n\n🤖 **AnthropicSamplingHandler** joins the existing OpenAI handler, providing multi-provider sampling support out of the box.\n\n⚡ **OpenAISamplingHandler promoted** from experimental status—sampling handlers are now production-ready with a unified API.\n\n## What's Changed\n### New Features 🎉\n* Sampling with tools by [@jlowin](https://github.com/jlowin) in [#2538](https://github.com/PrefectHQ/fastmcp/pull/2538)\n* Add AnthropicSamplingHandler by [@jlowin](https://github.com/jlowin) in [#2677](https://github.com/PrefectHQ/fastmcp/pull/2677)\n### Enhancements 🔧\n* Add Python 3.13 to ubuntu CI by [@jlowin](https://github.com/jlowin) in [#2648](https://github.com/PrefectHQ/fastmcp/pull/2648)\n* Remove legacy task initialization workaround by [@jlowin](https://github.com/jlowin) in [#2649](https://github.com/PrefectHQ/fastmcp/pull/2649)\n* Consolidate session state reset logic by [@jlowin](https://github.com/jlowin) in [#2651](https://github.com/PrefectHQ/fastmcp/pull/2651)\n* Unify SamplingHandler; promote OpenAI from experimental by [@jlowin](https://github.com/jlowin) in [#2656](https://github.com/PrefectHQ/fastmcp/pull/2656)\n* Add `tool_names` parameter to mount() for name customization by [@jlowin](https://github.com/jlowin) in [#2660](https://github.com/PrefectHQ/fastmcp/pull/2660)\n* Use streamable HTTP client API from MCP SDK by [@jlowin](https://github.com/jlowin) in [#2678](https://github.com/PrefectHQ/fastmcp/pull/2678)\n* Deprecate `exclude_args` in favor of Depends() by [@jlowin](https://github.com/jlowin) in [#2693](https://github.com/PrefectHQ/fastmcp/pull/2693)\n### Fixes 🐞\n* Fix prompt tasks to return mcp.types.PromptMessage by [@jlowin](https://github.com/jlowin) in [#2650](https://github.com/PrefectHQ/fastmcp/pull/2650)\n* Fix Windows test warnings by [@jlowin](https://github.com/jlowin) in [#2653](https://github.com/PrefectHQ/fastmcp/pull/2653)\n* Cleanup cancelled connection startup by [@jlowin](https://github.com/jlowin) in [#2679](https://github.com/PrefectHQ/fastmcp/pull/2679)\n* Fix tool choice bug in sampling examples by [@shawnthapa](https://github.com/shawnthapa) in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)\n### Docs 📚\n* Simplify Docket tip wording by [@chrisguidry](https://github.com/chrisguidry) in [#2662](https://github.com/PrefectHQ/fastmcp/pull/2662)\n### Other Changes 🦾\n* Bump pydocket to ≥0.15.5 by [@jlowin](https://github.com/jlowin) in [#2694](https://github.com/PrefectHQ/fastmcp/pull/2694)\n\n## New Contributors\n* [@shawnthapa](https://github.com/shawnthapa) made their first contribution in [#2686](https://github.com/PrefectHQ/fastmcp/pull/2686)\n\n**Full Changelog**: [v2.14.0...v2.14.1](https://github.com/PrefectHQ/fastmcp/compare/v2.14.0...v2.14.1)\n\n\n\n\n\n**[v2.14.0: Task and You Shall Receive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.14.0)**\n\nFastMCP 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.\n\n⏳ **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.\n\n🔧 **OpenAPI Parser Promoted** from experimental to standard with improved performance through single-pass schema processing and cleaner abstractions.\n\n📋 **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).\n\n## Breaking Changes\n- Docket is always enabled; task execution is forbidden through proxies\n- Task protocol enabled by default\n- Removed deprecated settings, imports, and methods accumulated across 2.x series\n\n## What's Changed\n### New Features 🎉\n* OpenAPI parser is now the default by [@jlowin](https://github.com/jlowin) in [#2583](https://github.com/PrefectHQ/fastmcp/pull/2583)\n* Implement SEP-1686: Background Tasks by [@jlowin](https://github.com/jlowin) in [#2550](https://github.com/PrefectHQ/fastmcp/pull/2550)\n### Enhancements 🔧\n* Expose InitializeResult in middleware by [@jlowin](https://github.com/jlowin) in [#2562](https://github.com/PrefectHQ/fastmcp/pull/2562)\n* Update MCP SDK auth compatibility by [@jlowin](https://github.com/jlowin) in [#2574](https://github.com/PrefectHQ/fastmcp/pull/2574)\n* Validate tool names at registration (SEP-986) by [@jlowin](https://github.com/jlowin) in [#2588](https://github.com/PrefectHQ/fastmcp/pull/2588)\n* Support SEP-1034 and SEP-1330 for elicitation by [@jlowin](https://github.com/jlowin) in [#2595](https://github.com/PrefectHQ/fastmcp/pull/2595)\n* Implement SSE polling (SEP-1699) by [@jlowin](https://github.com/jlowin) in [#2612](https://github.com/PrefectHQ/fastmcp/pull/2612)\n* Expose session ID callback by [@jlowin](https://github.com/jlowin) in [#2628](https://github.com/PrefectHQ/fastmcp/pull/2628)\n### Fixes 🐞\n* Fix OAuth metadata discovery by [@jlowin](https://github.com/jlowin) in [#2565](https://github.com/PrefectHQ/fastmcp/pull/2565)\n* Fix fastapi.cli package structure by [@jlowin](https://github.com/jlowin) in [#2570](https://github.com/PrefectHQ/fastmcp/pull/2570)\n* Correct OAuth error codes by [@jlowin](https://github.com/jlowin) in [#2578](https://github.com/PrefectHQ/fastmcp/pull/2578)\n* Prevent function signature modification by [@jlowin](https://github.com/jlowin) in [#2590](https://github.com/PrefectHQ/fastmcp/pull/2590)\n* Fix proxy client kwargs by [@jlowin](https://github.com/jlowin) in [#2605](https://github.com/PrefectHQ/fastmcp/pull/2605)\n* Fix nested server routing by [@jlowin](https://github.com/jlowin) in [#2618](https://github.com/PrefectHQ/fastmcp/pull/2618)\n* Use access token expiry fallback by [@jlowin](https://github.com/jlowin) in [#2635](https://github.com/PrefectHQ/fastmcp/pull/2635)\n* Handle transport cleanup exceptions by [@jlowin](https://github.com/jlowin) in [#2642](https://github.com/PrefectHQ/fastmcp/pull/2642)\n### Docs 📚\n* Add OCI and Supabase integration docs by [@jlowin](https://github.com/jlowin) in [#2580](https://github.com/PrefectHQ/fastmcp/pull/2580)\n* Add v2.14.0 upgrade guide by [@jlowin](https://github.com/jlowin) in [#2598](https://github.com/PrefectHQ/fastmcp/pull/2598)\n* Rewrite background tasks documentation by [@jlowin](https://github.com/jlowin) in [#2620](https://github.com/PrefectHQ/fastmcp/pull/2620)\n* Document read-only tool patterns by [@jlowin](https://github.com/jlowin) in [#2632](https://github.com/PrefectHQ/fastmcp/pull/2632)\n\n## New Contributors\n11 total contributors including 7 first-time participants.\n\n**Full Changelog**: [v2.13.3...v2.14.0](https://github.com/PrefectHQ/fastmcp/compare/v2.13.3...v2.14.0)\n\n\n\n\n\n**[v2.13.3: Pin-ish Line](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.3)**\n\nFastMCP 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`.\n\n## What's Changed\n### Fixes 🐞\n* Pin MCP SDK below 1.23 by [@jlowin](https://github.com/jlowin) in [#2545](https://github.com/PrefectHQ/fastmcp/pull/2545)\n\n**Full Changelog**: [v2.13.2...v2.13.3](https://github.com/PrefectHQ/fastmcp/compare/v2.13.2...v2.13.3)\n\n\n\n\n\n**[v2.13.2: Refreshing Changes](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.2)**\n\nFastMCP 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.\n\n## What's Changed\n### New Features 🎉\n* Add Discord OAuth provider by [@jlowin](https://github.com/jlowin) in [#2480](https://github.com/PrefectHQ/fastmcp/pull/2480)\n### Enhancements 🔧\n* Descope Provider updates for new well-known URLs by [@anvibanga](https://github.com/anvibanga) in [#2465](https://github.com/PrefectHQ/fastmcp/pull/2465)\n* Scalekit provider improvements by [@jlowin](https://github.com/jlowin) in [#2472](https://github.com/PrefectHQ/fastmcp/pull/2472)\n* Add CSP customization for consent screens by [@jlowin](https://github.com/jlowin) in [#2488](https://github.com/PrefectHQ/fastmcp/pull/2488)\n* Add icon support to proxy classes by [@jlowin](https://github.com/jlowin) in [#2495](https://github.com/PrefectHQ/fastmcp/pull/2495)\n### Fixes 🐞\n* Google Provider now defaults to refresh token support by [@jlowin](https://github.com/jlowin) in [#2468](https://github.com/PrefectHQ/fastmcp/pull/2468)\n* Fix Azure OAuth token refresh with unprefixed scopes by [@jlowin](https://github.com/jlowin) in [#2475](https://github.com/PrefectHQ/fastmcp/pull/2475)\n* Prevent `$defs` mutation during tool transforms by [@jlowin](https://github.com/jlowin) in [#2482](https://github.com/PrefectHQ/fastmcp/pull/2482)\n* 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)\n* Fix stale token issue after OAuth refresh by [@jlowin](https://github.com/jlowin) in [#2498](https://github.com/PrefectHQ/fastmcp/pull/2498)\n* Fix Azure provider OIDC scope handling by [@jlowin](https://github.com/jlowin) in [#2505](https://github.com/PrefectHQ/fastmcp/pull/2505)\n\n## New Contributors\n7 new contributors made their first FastMCP contributions in this release.\n\n**Full Changelog**: [v2.13.1...v2.13.2](https://github.com/PrefectHQ/fastmcp/compare/v2.13.1...v2.13.2)\n\n\n\n\n\n**[v2.13.1: Heavy Meta](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.1)**\n\nFastMCP 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.\n\n🏷️ **Meta parameters for ToolResult** enable tools to return supplementary metadata alongside results, supporting patterns like OpenAI's Apps SDK integration.\n\n🔐 **Custom token verifiers** with DebugTokenVerifier for development, plus Azure Government support through a `base_authority` parameter and Supabase authentication algorithm configuration.\n\n🔒 **Security fixes** address CVE-2025-61920 through authlib updates and validate Cursor deeplink URLs using safer Windows APIs.\n\n## What's Changed\n### New Features 🎉\n* Add meta parameter support for ToolResult by [@jlowin](https://github.com/jlowin) in [#2350](https://github.com/PrefectHQ/fastmcp/pull/2350)\n* Add OCI authentication provider by [@jlowin](https://github.com/jlowin) in [#2365](https://github.com/PrefectHQ/fastmcp/pull/2365)\n* Add Supabase authentication provider by [@jlowin](https://github.com/jlowin) in [#2378](https://github.com/PrefectHQ/fastmcp/pull/2378)\n### Enhancements 🔧\n* Add custom token verifier support to OIDCProxy by [@jlowin](https://github.com/jlowin) in [#2355](https://github.com/PrefectHQ/fastmcp/pull/2355)\n* Add DebugTokenVerifier for development by [@jlowin](https://github.com/jlowin) in [#2362](https://github.com/PrefectHQ/fastmcp/pull/2362)\n* Add Azure Government support via base_authority parameter by [@jlowin](https://github.com/jlowin) in [#2385](https://github.com/PrefectHQ/fastmcp/pull/2385)\n* Add Supabase authentication algorithm configuration by [@jlowin](https://github.com/jlowin) in [#2392](https://github.com/PrefectHQ/fastmcp/pull/2392)\n### Fixes 🐞\n* Security: Update authlib for CVE-2025-61920 by [@jlowin](https://github.com/jlowin) in [#2398](https://github.com/PrefectHQ/fastmcp/pull/2398)\n* Validate Cursor deeplink URLs using safer Windows APIs by [@jlowin](https://github.com/jlowin) in [#2405](https://github.com/PrefectHQ/fastmcp/pull/2405)\n* 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)\n\n## New Contributors\n18 new contributors joined in this release across 70+ pull requests.\n\n**Full Changelog**: [v2.13.0...v2.13.1](https://github.com/PrefectHQ/fastmcp/compare/v2.13.0...v2.13.1)\n\n\n\n\n\n**[v2.13.0: Cache Me If You Can](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.13.0)**\n\nFastMCP 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.\n\n💾 **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.\n\n🔐 **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.\n\nFastMCP now supports out-of-the-box authentication with:\n- **[WorkOS](https://gofastmcp.com/integrations/workos)** and **[AuthKit](https://gofastmcp.com/integrations/authkit)**\n- **[GitHub](https://gofastmcp.com/integrations/github)**\n- **[Google](https://gofastmcp.com/integrations/google)**\n- **[Azure](https://gofastmcp.com/integrations/azure)** (Entra ID)\n- **[AWS Cognito](https://gofastmcp.com/integrations/aws-cognito)**\n- **[Auth0](https://gofastmcp.com/integrations/auth0)**\n- **[Descope](https://gofastmcp.com/integrations/descope)**\n- **[Scalekit](https://gofastmcp.com/integrations/scalekit)**\n- **[JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification)**\n- **[RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol)**\n\n⚡ **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.\n\n🔄 **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.\n\n✨ **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.\n\nThis 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!\n\n**Full Changelog**: [v2.12.5...v2.13.0](https://github.com/PrefectHQ/fastmcp/compare/v2.12.5...v2.13.0)\n\n\n\n\n\n**[v2.12.5: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.5)**\n\nFastMCP 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.\n\n## What's Changed\n\n### Fixes 🐞\n* Pin MCP SDK version below 1.17 by [@jlowin](https://github.com/jlowin) in [a1b2c3d](https://github.com/PrefectHQ/fastmcp/commit/dab2b316ddc3883b7896a86da21cacb68da01e5c)\n\n**Full Changelog**: [v2.12.4...v2.12.5](https://github.com/PrefectHQ/fastmcp/compare/v2.12.4...v2.12.5)\n\n\n\n\n\n**[v2.12.4: OIDC What You Did There](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.4)**\n\nFastMCP 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.\n\n## What's Changed\n### New Features 🎉\n* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)\n### Enhancements 🔧\n* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)\n* Refactor Logging and Structured Logging Middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)\n* Update pull_request_template.md by [@jlowin](https://github.com/jlowin) in [#1824](https://github.com/PrefectHQ/fastmcp/pull/1824)\n* chore: Set redirect_path default in function by [@ruhulio](https://github.com/ruhulio) in [#1833](https://github.com/PrefectHQ/fastmcp/pull/1833)\n* feat: Set instructions in code by [@attiks](https://github.com/attiks) in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)\n* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)\n* chore: Cleanup Auth0 redirect_path initialization by [@ruhulio](https://github.com/ruhulio) in [#1842](https://github.com/PrefectHQ/fastmcp/pull/1842)\n* feat: Add support for Descope Authentication by [@anvibanga](https://github.com/anvibanga) in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)\n* Update descope version badges by [@jlowin](https://github.com/jlowin) in [#1870](https://github.com/PrefectHQ/fastmcp/pull/1870)\n* Update welcome images by [@jlowin](https://github.com/jlowin) in [#1884](https://github.com/PrefectHQ/fastmcp/pull/1884)\n* Fix rounded edges of image by [@jlowin](https://github.com/jlowin) in [#1886](https://github.com/PrefectHQ/fastmcp/pull/1886)\n* optimize test suite by [@zzstoatzz](https://github.com/zzstoatzz) in [#1893](https://github.com/PrefectHQ/fastmcp/pull/1893)\n* Enhancement: client completions support context_arguments by [@isijoe](https://github.com/isijoe) in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)\n* Update Descope icon by [@anvibanga](https://github.com/anvibanga) in [#1912](https://github.com/PrefectHQ/fastmcp/pull/1912)\n* Add AWS Cognito OAuth Provider for Enterprise Authentication by [@stephaneberle9](https://github.com/stephaneberle9) in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)\n* Fix typos discovered by codespell by [@cclauss](https://github.com/cclauss) in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)\n* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)\n### Fixes 🐞\n* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)\n* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)\n* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)\n* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)\n* fix: Increase default 3s timeout on Pytest by [@dacamposol](https://github.com/dacamposol) in [#1866](https://github.com/PrefectHQ/fastmcp/pull/1866)\n* fix: Improve URL handling in OIDCConfiguration by [@ruhulio](https://github.com/ruhulio) in [#1850](https://github.com/PrefectHQ/fastmcp/pull/1850)\n* fix: correct typing for on_read_resource middleware method by [@strawgate](https://github.com/strawgate) in [#1858](https://github.com/PrefectHQ/fastmcp/pull/1858)\n* feat(experimental/openapi): replace $ref in additionalProperties; add tests by [@jlowin](https://github.com/jlowin) in [#1735](https://github.com/PrefectHQ/fastmcp/pull/1735)\n* Honor client supplied scopes during registration by [@dmikusa](https://github.com/dmikusa) in [#1860](https://github.com/PrefectHQ/fastmcp/pull/1860)\n* Fix: FastAPI list parameter parsing in experimental OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#1834](https://github.com/PrefectHQ/fastmcp/pull/1834)\n* Add log level support for stdio and HTTP transports by [@jlowin](https://github.com/jlowin) in [#1840](https://github.com/PrefectHQ/fastmcp/pull/1840)\n* 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)\n* Fix: Preserve OpenAPI parameter descriptions in experimental parser by [@shlomo666](https://github.com/shlomo666) in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)\n* Add persistent storage for OAuth client registrations by [@jlowin](https://github.com/jlowin) in [#1879](https://github.com/PrefectHQ/fastmcp/pull/1879)\n* docs: update release dates based on github releases by [@lodu](https://github.com/lodu) in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)\n* Small updates to Sampling types by [@strawgate](https://github.com/strawgate) in [#1882](https://github.com/PrefectHQ/fastmcp/pull/1882)\n* remove lockfile smart_home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#1892](https://github.com/PrefectHQ/fastmcp/pull/1892)\n* 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)\n* Fix: get_resource_url nested URL handling by [@raphael-linx](https://github.com/raphael-linx) in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)\n* Clean up code for creating the resource url by [@jlowin](https://github.com/jlowin) in [#1916](https://github.com/PrefectHQ/fastmcp/pull/1916)\n* Fix route count logging in OpenAPI server by [@zzstoatzz](https://github.com/zzstoatzz) in [#1928](https://github.com/PrefectHQ/fastmcp/pull/1928)\n### Docs 📚\n* docs: make Gemini CLI integration discoverable by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1827](https://github.com/PrefectHQ/fastmcp/pull/1827)\n* docs: update NEW tags for AI assistant integrations by [@jackwotherspoon](https://github.com/jackwotherspoon) in [#1829](https://github.com/PrefectHQ/fastmcp/pull/1829)\n* Update wordmark by [@jlowin](https://github.com/jlowin) in [#1832](https://github.com/PrefectHQ/fastmcp/pull/1832)\n* docs: improve OAuth and OIDC Proxy documentation by [@jlowin](https://github.com/jlowin) in [#1880](https://github.com/PrefectHQ/fastmcp/pull/1880)\n* Update readme + welcome docs by [@jlowin](https://github.com/jlowin) in [#1883](https://github.com/PrefectHQ/fastmcp/pull/1883)\n* Update dark mode image in README by [@jlowin](https://github.com/jlowin) in [#1885](https://github.com/PrefectHQ/fastmcp/pull/1885)\n\n## New Contributors\n* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)\n* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)\n* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)\n* [@attiks](https://github.com/attiks) made their first contribution in [#1838](https://github.com/PrefectHQ/fastmcp/pull/1838)\n* [@anvibanga](https://github.com/anvibanga) made their first contribution in [#1853](https://github.com/PrefectHQ/fastmcp/pull/1853)\n* [@shlomo666](https://github.com/shlomo666) made their first contribution in [#1877](https://github.com/PrefectHQ/fastmcp/pull/1877)\n* [@lodu](https://github.com/lodu) made their first contribution in [#1890](https://github.com/PrefectHQ/fastmcp/pull/1890)\n* [@isijoe](https://github.com/isijoe) made their first contribution in [#1906](https://github.com/PrefectHQ/fastmcp/pull/1906)\n* [@raphael-linx](https://github.com/raphael-linx) made their first contribution in [#1914](https://github.com/PrefectHQ/fastmcp/pull/1914)\n* [@stephaneberle9](https://github.com/stephaneberle9) made their first contribution in [#1873](https://github.com/PrefectHQ/fastmcp/pull/1873)\n* [@cclauss](https://github.com/cclauss) made their first contribution in [#1922](https://github.com/PrefectHQ/fastmcp/pull/1922)\n\n**Full Changelog**: [v2.12.3...v2.12.4](https://github.com/PrefectHQ/fastmcp/compare/v2.12.3...v2.12.4)\n\n\n\n\n\n**[v2.12.3: Double Time](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.3)**\n\nFastMCP 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.\n\n## What's Changed\n### New Features 🎉\n* feat: Support setting MCP log level via transport configuration by [@jlowin](https://github.com/jlowin) in [#1756](https://github.com/PrefectHQ/fastmcp/pull/1756)\n### Enhancements 🔧\n* 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)\n* Automatically Create inline Snapshots by [@strawgate](https://github.com/strawgate) in [#1779](https://github.com/PrefectHQ/fastmcp/pull/1779)\n* Use lowercase namespace for fastmcp logger by [@jlowin](https://github.com/jlowin) in [#1791](https://github.com/PrefectHQ/fastmcp/pull/1791)\n### Fixes 🐞\n* fix: correct merge mistake during auth0 refactor by [@strawgate](https://github.com/strawgate) in [#1742](https://github.com/PrefectHQ/fastmcp/pull/1742)\n* Remove extraneous union import by [@jlowin](https://github.com/jlowin) in [#1823](https://github.com/PrefectHQ/fastmcp/pull/1823)\n* Delay import of Provider classes until FastMCP Server Creation by [@strawgate](https://github.com/strawgate) in [#1820](https://github.com/PrefectHQ/fastmcp/pull/1820)\n* fix: refactor OIDC configuration provider for proper token management by [@strawgate](https://github.com/strawgate) in [#1751](https://github.com/PrefectHQ/fastmcp/pull/1751)\n* Fix smart_home example imports by [@strawgate](https://github.com/strawgate) in [#1753](https://github.com/PrefectHQ/fastmcp/pull/1753)\n* fix: correct oauth proxy initialization of client by [@strawgate](https://github.com/strawgate) in [#1759](https://github.com/PrefectHQ/fastmcp/pull/1759)\n* Fix: return empty string when prompts have no arguments by [@jlowin](https://github.com/jlowin) in [#1766](https://github.com/PrefectHQ/fastmcp/pull/1766)\n* Fix async server callbacks by [@strawgate](https://github.com/strawgate) in [#1774](https://github.com/PrefectHQ/fastmcp/pull/1774)\n* Fix error when retrieving Completion API errors by [@strawgate](https://github.com/strawgate) in [#1785](https://github.com/PrefectHQ/fastmcp/pull/1785)\n* fix: correct documentation link in deprecation warning by [@strawgate](https://github.com/strawgate) in [#1828](https://github.com/PrefectHQ/fastmcp/pull/1828)\n### Docs 📚\n* Add migration docs for 2.12 by [@jlowin](https://github.com/jlowin) in [#1745](https://github.com/PrefectHQ/fastmcp/pull/1745)\n* 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)\n* 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)\n* Update quickstart.mdx by [@radi-dev](https://github.com/radi-dev) in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)\n### Other Changes 🦾\n* Replace Marvin with Claude Code in CI by [@jlowin](https://github.com/jlowin) in [#1800](https://github.com/PrefectHQ/fastmcp/pull/1800)\n* Refactor logging and structured logging middleware by [@strawgate](https://github.com/strawgate) in [#1805](https://github.com/PrefectHQ/fastmcp/pull/1805)\n* feat: Move the Starlette context middleware to the front by [@akkuman](https://github.com/akkuman) in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)\n* feat: Add support for OIDC configuration by [@ruhulio](https://github.com/ruhulio) in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)\n\n## New Contributors\n* [@radi-dev](https://github.com/radi-dev) made their first contribution in [#1821](https://github.com/PrefectHQ/fastmcp/pull/1821)\n* [@akkuman](https://github.com/akkuman) made their first contribution in [#1812](https://github.com/PrefectHQ/fastmcp/pull/1812)\n* [@ruhulio](https://github.com/ruhulio) made their first contribution in [#1817](https://github.com/PrefectHQ/fastmcp/pull/1817)\n\n**Full Changelog**: [v2.12.2...v2.12.3](https://github.com/PrefectHQ/fastmcp/compare/v2.12.2...v2.12.3)\n\n\n\n\n\n**[v2.12.2: Perchance to Stream](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.2)**\n\nThis 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. \n\n## What's Changed\n### Fixes 🐞\n* Fix streamable-http transport validation in fastmcp.json config by [@jlowin](https://github.com/jlowin) in [#1739](https://github.com/PrefectHQ/fastmcp/pull/1739)\n\n**Full Changelog**: [v2.12.1...v2.12.2](https://github.com/PrefectHQ/fastmcp/compare/v2.12.1...v2.12.2)\n\n\n\n\n\n**[v2.12.1: OAuth to Joy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.1)**\n\nFastMCP 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.\n\n## Breaking Changes\n- **OAuth Proxy**: Users of built-in IDP integrations should note that `resource_server_url` has been renamed to `base_url` for clarity and consistency\n\n## What's Changed\n### Enhancements 🔧\n* Make openai dependency optional by [@jlowin](https://github.com/jlowin) in [#1701](https://github.com/PrefectHQ/fastmcp/pull/1701)\n* Remove orphaned OAuth proxy code by [@jlowin](https://github.com/jlowin) in [#1722](https://github.com/PrefectHQ/fastmcp/pull/1722)\n* Expose valid scopes from OAuthProxy metadata by [@dmikusa](https://github.com/dmikusa) in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)\n* OAuth proxy PKCE forwarding by [@jlowin](https://github.com/jlowin) in [#1733](https://github.com/PrefectHQ/fastmcp/pull/1733)\n* Add token_endpoint_auth_method parameter to OAuthProxy by [@jlowin](https://github.com/jlowin) in [#1736](https://github.com/PrefectHQ/fastmcp/pull/1736)\n* 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)\n### Fixes 🐞\n* refactor: replace auth provider registry with ImportString by [@jlowin](https://github.com/jlowin) in [#1710](https://github.com/PrefectHQ/fastmcp/pull/1710)\n* Fix OAuth resource URL handling and WWW-Authenticate header by [@jlowin](https://github.com/jlowin) in [#1706](https://github.com/PrefectHQ/fastmcp/pull/1706)\n* Fix OAuth proxy client storage and add retry logic by [@jlowin](https://github.com/jlowin) in [#1732](https://github.com/PrefectHQ/fastmcp/pull/1732)\n### Docs 📚\n* Fix documentation: use StreamableHttpTransport for headers in testing by [@jlowin](https://github.com/jlowin) in [#1702](https://github.com/PrefectHQ/fastmcp/pull/1702)\n* docs: add performance warnings for mounted servers and proxies by [@strawgate](https://github.com/strawgate) in [#1669](https://github.com/PrefectHQ/fastmcp/pull/1669)\n* Update documentation around scopes for google by [@jlowin](https://github.com/jlowin) in [#1703](https://github.com/PrefectHQ/fastmcp/pull/1703)\n* Add deployment information to quickstart by [@seanpwlms](https://github.com/seanpwlms) in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)\n* Update quickstart by [@jlowin](https://github.com/jlowin) in [#1728](https://github.com/PrefectHQ/fastmcp/pull/1728)\n* Add development docs for FastMCP by [@jlowin](https://github.com/jlowin) in [#1719](https://github.com/PrefectHQ/fastmcp/pull/1719)\n### Other Changes 🦾\n* Set generics without bounds to default=Any by [@strawgate](https://github.com/strawgate) in [#1648](https://github.com/PrefectHQ/fastmcp/pull/1648)\n\n## New Contributors\n* [@dmikusa](https://github.com/dmikusa) made their first contribution in [#1717](https://github.com/PrefectHQ/fastmcp/pull/1717)\n* [@seanpwlms](https://github.com/seanpwlms) made their first contribution in [#1433](https://github.com/PrefectHQ/fastmcp/pull/1433)\n\n**Full Changelog**: [v2.12.0...v2.12.1](https://github.com/PrefectHQ/fastmcp/compare/v2.12.0...v2.12.1)\n\n\n\n\n\n**[v2.12.0: Auth to the Races](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.12.0)**\n\nFastMCP 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.\n\n🔐 **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.\n\n📋 **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.\n\n🧠 **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.\n\nThis 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.\n\nThank you to our new contributors and everyone who tested preview builds. Your feedback directly shaped these features.\n\n## What's Changed\n### New Features 🎉\n* 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)\n* feat: introduce declarative JSON configuration system by [@jlowin](https://github.com/jlowin) in [#1517](https://github.com/PrefectHQ/fastmcp/pull/1517)\n* ✨ 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)\n* Implement typed source system for FastMCP declarative configuration by [@jlowin](https://github.com/jlowin) in [#1607](https://github.com/PrefectHQ/fastmcp/pull/1607)\n### Enhancements 🔧\n* Support importing custom_route endpoints when mounting servers by [@jlowin](https://github.com/jlowin) in [#1470](https://github.com/PrefectHQ/fastmcp/pull/1470)\n* Remove unnecessary asserts by [@jlowin](https://github.com/jlowin) in [#1484](https://github.com/PrefectHQ/fastmcp/pull/1484)\n* Add Claude issue triage by [@jlowin](https://github.com/jlowin) in [#1510](https://github.com/PrefectHQ/fastmcp/pull/1510)\n* Inline dedupe prompt by [@jlowin](https://github.com/jlowin) in [#1512](https://github.com/PrefectHQ/fastmcp/pull/1512)\n* Improve stdio and mcp_config clean-up by [@strawgate](https://github.com/strawgate) in [#1444](https://github.com/PrefectHQ/fastmcp/pull/1444)\n* 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)\n* Move SDK docs generation to post-merge workflow by [@jlowin](https://github.com/jlowin) in [#1513](https://github.com/PrefectHQ/fastmcp/pull/1513)\n* Improve label triage guidance by [@jlowin](https://github.com/jlowin) in [#1516](https://github.com/PrefectHQ/fastmcp/pull/1516)\n* Add code review guidelines for agents by [@jlowin](https://github.com/jlowin) in [#1520](https://github.com/PrefectHQ/fastmcp/pull/1520)\n* Remove trailing slash in unit tests by [@jlowin](https://github.com/jlowin) in [#1535](https://github.com/PrefectHQ/fastmcp/pull/1535)\n* Update OAuth callback UI branding by [@jlowin](https://github.com/jlowin) in [#1536](https://github.com/PrefectHQ/fastmcp/pull/1536)\n* Fix Marvin workflow to support development tools by [@jlowin](https://github.com/jlowin) in [#1537](https://github.com/PrefectHQ/fastmcp/pull/1537)\n* 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)\n* feat: Add --workspace flag to fastmcp install cursor by [@jlowin](https://github.com/jlowin) in [#1522](https://github.com/PrefectHQ/fastmcp/pull/1522)\n* switch from `pyright` to `ty` by [@zzstoatzz](https://github.com/zzstoatzz) in [#1545](https://github.com/PrefectHQ/fastmcp/pull/1545)\n* feat: trigger Marvin workflow on PR body content by [@jlowin](https://github.com/jlowin) in [#1549](https://github.com/PrefectHQ/fastmcp/pull/1549)\n* Add WorkOS and Azure OAuth providers by [@jlowin](https://github.com/jlowin) in [#1550](https://github.com/PrefectHQ/fastmcp/pull/1550)\n* Adjust timeout for slow MCP Server shutdown test by [@strawgate](https://github.com/strawgate) in [#1561](https://github.com/PrefectHQ/fastmcp/pull/1561)\n* Update banner by [@jlowin](https://github.com/jlowin) in [#1567](https://github.com/PrefectHQ/fastmcp/pull/1567)\n* Added import of AuthProxy to auth __init__ by [@KaliszS](https://github.com/KaliszS) in [#1568](https://github.com/PrefectHQ/fastmcp/pull/1568)\n* Add configurable redirect URI validation for OAuth providers by [@jlowin](https://github.com/jlowin) in [#1582](https://github.com/PrefectHQ/fastmcp/pull/1582)\n* Remove invalid-argument-type ignore and fix type errors by [@jlowin](https://github.com/jlowin) in [#1588](https://github.com/PrefectHQ/fastmcp/pull/1588)\n* Remove generate-schema from public CLI by [@jlowin](https://github.com/jlowin) in [#1591](https://github.com/PrefectHQ/fastmcp/pull/1591)\n* Skip flaky windows test / mulit-client garbage collection by [@jlowin](https://github.com/jlowin) in [#1592](https://github.com/PrefectHQ/fastmcp/pull/1592)\n* Add setting to disable logging configuration by [@isra17](https://github.com/isra17) in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)\n* Improve debug logging for nested Servers / Clients by [@strawgate](https://github.com/strawgate) in [#1604](https://github.com/PrefectHQ/fastmcp/pull/1604)\n* Add GitHub pull request template by [@strawgate](https://github.com/strawgate) in [#1581](https://github.com/PrefectHQ/fastmcp/pull/1581)\n* chore: Automate docs and schema updates via PRs by [@jlowin](https://github.com/jlowin) in [#1611](https://github.com/PrefectHQ/fastmcp/pull/1611)\n* Experiment with haiku for limited workflows by [@jlowin](https://github.com/jlowin) in [#1613](https://github.com/PrefectHQ/fastmcp/pull/1613)\n* 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)\n* Consolidate server loading logic into FileSystemSource by [@jlowin](https://github.com/jlowin) in [#1614](https://github.com/PrefectHQ/fastmcp/pull/1614)\n* 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)\n* chore: Add clarifying note to automated PR bodies by [@jlowin](https://github.com/jlowin) in [#1623](https://github.com/PrefectHQ/fastmcp/pull/1623)\n* feat: introduce inline snapshots by [@strawgate](https://github.com/strawgate) in [#1605](https://github.com/PrefectHQ/fastmcp/pull/1605)\n* Improve fastmcp.json environment configuration and project-based deployments by [@jlowin](https://github.com/jlowin) in [#1631](https://github.com/PrefectHQ/fastmcp/pull/1631)\n* 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)\n* Support multiple --with-editable flags in CLI commands by [@jlowin](https://github.com/jlowin) in [#1634](https://github.com/PrefectHQ/fastmcp/pull/1634)\n* feat: support comma separated oauth scopes by [@jlowin](https://github.com/jlowin) in [#1642](https://github.com/PrefectHQ/fastmcp/pull/1642)\n* Add allowed_client_redirect_uris to OAuth provider subclasses by [@jlowin](https://github.com/jlowin) in [#1662](https://github.com/PrefectHQ/fastmcp/pull/1662)\n* Consolidate CLI config parsing and prevent infinite loops by [@jlowin](https://github.com/jlowin) in [#1660](https://github.com/PrefectHQ/fastmcp/pull/1660)\n* Internal refactor: mcp server config by [@jlowin](https://github.com/jlowin) in [#1672](https://github.com/PrefectHQ/fastmcp/pull/1672)\n* Refactor Environment to support multiple runtime types by [@jlowin](https://github.com/jlowin) in [#1673](https://github.com/PrefectHQ/fastmcp/pull/1673)\n* Add type field to Environment base class by [@jlowin](https://github.com/jlowin) in [#1676](https://github.com/PrefectHQ/fastmcp/pull/1676)\n### Fixes 🐞\n* Fix breaking change: restore output_schema=False compatibility by [@jlowin](https://github.com/jlowin) in [#1482](https://github.com/PrefectHQ/fastmcp/pull/1482)\n* 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)\n* Fix pytest warnings by [@jlowin](https://github.com/jlowin) in [#1559](https://github.com/PrefectHQ/fastmcp/pull/1559)\n* nest schemas under assets by [@jlowin](https://github.com/jlowin) in [#1593](https://github.com/PrefectHQ/fastmcp/pull/1593)\n* Skip flaky windows test by [@jlowin](https://github.com/jlowin) in [#1596](https://github.com/PrefectHQ/fastmcp/pull/1596)\n* ACTUALLY move schemas to fastmcp.json by [@jlowin](https://github.com/jlowin) in [#1597](https://github.com/PrefectHQ/fastmcp/pull/1597)\n* Fix and centralize CLI path resolution by [@jlowin](https://github.com/jlowin) in [#1590](https://github.com/PrefectHQ/fastmcp/pull/1590)\n* Remove client info modifications by [@jlowin](https://github.com/jlowin) in [#1620](https://github.com/PrefectHQ/fastmcp/pull/1620)\n* 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)\n* 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)\n* Reuse session for `StdioTransport` in `Client.new` by [@strawgate](https://github.com/strawgate) in [#1635](https://github.com/PrefectHQ/fastmcp/pull/1635)\n* Feat: Configurable LoggingMiddleware payload serialization by [@vl-kp](https://github.com/vl-kp) in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)\n* Fix OAuth redirect URI validation for DCR compatibility by [@jlowin](https://github.com/jlowin) in [#1661](https://github.com/PrefectHQ/fastmcp/pull/1661)\n* Add default scope handling in OAuth proxy by [@romanusyk](https://github.com/romanusyk) in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)\n* Fix OAuth token expiry handling by [@jlowin](https://github.com/jlowin) in [#1671](https://github.com/PrefectHQ/fastmcp/pull/1671)\n* Add resource_server_url parameter to OAuth proxy providers by [@jlowin](https://github.com/jlowin) in [#1682](https://github.com/PrefectHQ/fastmcp/pull/1682)\n### Breaking Changes 🛫\n* Enhance inspect command with structured output and format options by [@jlowin](https://github.com/jlowin) in [#1481](https://github.com/PrefectHQ/fastmcp/pull/1481)\n### Docs 📚\n* Update changelog by [@jlowin](https://github.com/jlowin) in [#1453](https://github.com/PrefectHQ/fastmcp/pull/1453)\n* Update banner by [@jlowin](https://github.com/jlowin) in [#1472](https://github.com/PrefectHQ/fastmcp/pull/1472)\n* Update logo files by [@jlowin](https://github.com/jlowin) in [#1473](https://github.com/PrefectHQ/fastmcp/pull/1473)\n* Update deployment docs by [@jlowin](https://github.com/jlowin) in [#1486](https://github.com/PrefectHQ/fastmcp/pull/1486)\n* Update FastMCP Cloud screenshot by [@jlowin](https://github.com/jlowin) in [#1487](https://github.com/PrefectHQ/fastmcp/pull/1487)\n* Update authentication note in docs by [@jlowin](https://github.com/jlowin) in [#1488](https://github.com/PrefectHQ/fastmcp/pull/1488)\n* chore: Update installation.mdx version snippet by [@thomas-te](https://github.com/thomas-te) in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)\n* Update fastmcp cloud server requirements by [@jlowin](https://github.com/jlowin) in [#1497](https://github.com/PrefectHQ/fastmcp/pull/1497)\n* Fix oauth pyright type checking by [@strawgate](https://github.com/strawgate) in [#1498](https://github.com/PrefectHQ/fastmcp/pull/1498)\n* docs: Fix type annotation in return value documentation by [@MaikelVeen](https://github.com/MaikelVeen) in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)\n* Fix PromptMessage usage in docs example by [@jlowin](https://github.com/jlowin) in [#1515](https://github.com/PrefectHQ/fastmcp/pull/1515)\n* Create CODE_OF_CONDUCT.md by [@jlowin](https://github.com/jlowin) in [#1523](https://github.com/PrefectHQ/fastmcp/pull/1523)\n* Fixed wrong import path in new docs page by [@KaliszS](https://github.com/KaliszS) in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)\n* Document symmetric key JWT verification support by [@jlowin](https://github.com/jlowin) in [#1586](https://github.com/PrefectHQ/fastmcp/pull/1586)\n* Update fastmcp.json schema path by [@jlowin](https://github.com/jlowin) in [#1595](https://github.com/PrefectHQ/fastmcp/pull/1595)\n### Dependencies 📦\n* 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)\n* 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)\n* Bump actions/checkout from 4 to 5 by [@dependabot](https://github.com/dependabot)[bot] in [#1533](https://github.com/PrefectHQ/fastmcp/pull/1533)\n### Other Changes 🦾\n* Add dedupe workflow by [@jlowin](https://github.com/jlowin) in [#1454](https://github.com/PrefectHQ/fastmcp/pull/1454)\n* Update AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1471](https://github.com/PrefectHQ/fastmcp/pull/1471)\n* Give Marvin the power of the Internet by [@strawgate](https://github.com/strawgate) in [#1475](https://github.com/PrefectHQ/fastmcp/pull/1475)\n* Update `just` error message for static checks by [@jlowin](https://github.com/jlowin) in [#1483](https://github.com/PrefectHQ/fastmcp/pull/1483)\n* Remove labeler by [@jlowin](https://github.com/jlowin) in [#1509](https://github.com/PrefectHQ/fastmcp/pull/1509)\n* update aproto server to handle rich links by [@zzstoatzz](https://github.com/zzstoatzz) in [#1556](https://github.com/PrefectHQ/fastmcp/pull/1556)\n* 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)\n\n## New Contributors\n* [@thomas-te](https://github.com/thomas-te) made their first contribution in [#1496](https://github.com/PrefectHQ/fastmcp/pull/1496)\n* [@maybenotconnor](https://github.com/maybenotconnor) made their first contribution in [#1511](https://github.com/PrefectHQ/fastmcp/pull/1511)\n* [@MaikelVeen](https://github.com/MaikelVeen) made their first contribution in [#1499](https://github.com/PrefectHQ/fastmcp/pull/1499)\n* [@KaliszS](https://github.com/KaliszS) made their first contribution in [#1538](https://github.com/PrefectHQ/fastmcp/pull/1538)\n* [@isra17](https://github.com/isra17) made their first contribution in [#1575](https://github.com/PrefectHQ/fastmcp/pull/1575)\n* [@marvin-context-protocol](https://github.com/marvin-context-protocol)[bot] made their first contribution in [#1616](https://github.com/PrefectHQ/fastmcp/pull/1616)\n* [@pldesch-chift](https://github.com/pldesch-chift) made their first contribution in [#1578](https://github.com/PrefectHQ/fastmcp/pull/1578)\n* [@vl-kp](https://github.com/vl-kp) made their first contribution in [#1636](https://github.com/PrefectHQ/fastmcp/pull/1636)\n* [@romanusyk](https://github.com/romanusyk) made their first contribution in [#1667](https://github.com/PrefectHQ/fastmcp/pull/1667)\n\n**Full Changelog**: [v2.11.3...v2.12.0](https://github.com/PrefectHQ/fastmcp/compare/v2.11.3...v2.12.0)\n\n\n\n\n\n**[v2.11.3: API-tite for Change](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.3)**\n\nThis 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.\n\n## What's Changed\n### Enhancements 🔧\n* Improve redirect handling to address 307's by [@jlowin](https://github.com/jlowin) in [#1387](https://github.com/PrefectHQ/fastmcp/pull/1387)\n* 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)\n* fixes #1398: Add JWT claims to AccessToken by [@panargirakis](https://github.com/panargirakis) in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)\n* 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)\n* 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)\n* Clean up complexity from PR #1426 by [@jlowin](https://github.com/jlowin) in [#1435](https://github.com/PrefectHQ/fastmcp/pull/1435)\n* Optimize OpenAPI payload size by 46% by [@jlowin](https://github.com/jlowin) in [#1452](https://github.com/PrefectHQ/fastmcp/pull/1452)\n* Update static checks by [@jlowin](https://github.com/jlowin) in [#1448](https://github.com/PrefectHQ/fastmcp/pull/1448)\n### Fixes 🐞\n* Fix client-side logging bug #1394 by [@chi2liu](https://github.com/chi2liu) in [#1397](https://github.com/PrefectHQ/fastmcp/pull/1397)\n* 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)\n* Fix OpenAPI allOf handling at requestBody top level (#1378) by [@chi2liu](https://github.com/chi2liu) in [#1425](https://github.com/PrefectHQ/fastmcp/pull/1425)\n* Fix OpenAPI transitive references and performance (#1372) by [@jlowin](https://github.com/jlowin) in [#1426](https://github.com/PrefectHQ/fastmcp/pull/1426)\n* fix(type): lifespan is partially unknown by [@ykun9](https://github.com/ykun9) in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)\n* Ensure transformed tools generate structured content by [@jlowin](https://github.com/jlowin) in [#1443](https://github.com/PrefectHQ/fastmcp/pull/1443)\n### Docs 📚\n* docs(client/logging): reflect corrected default log level mapping by [@jlowin](https://github.com/jlowin) in [#1403](https://github.com/PrefectHQ/fastmcp/pull/1403)\n* Add documentation for get_access_token() dependency function by [@jlowin](https://github.com/jlowin) in [#1446](https://github.com/PrefectHQ/fastmcp/pull/1446)\n### Other Changes 🦾\n* Add comprehensive tests for utilities.components module by [@chi2liu](https://github.com/chi2liu) in [#1395](https://github.com/PrefectHQ/fastmcp/pull/1395)\n* Consolidate agent instructions into AGENTS.md by [@jlowin](https://github.com/jlowin) in [#1404](https://github.com/PrefectHQ/fastmcp/pull/1404)\n* Fix performance test threshold to prevent flaky failures by [@jlowin](https://github.com/jlowin) in [#1406](https://github.com/PrefectHQ/fastmcp/pull/1406)\n* Update agents.md; add github instructions by [@jlowin](https://github.com/jlowin) in [#1410](https://github.com/PrefectHQ/fastmcp/pull/1410)\n* Add Marvin assistant by [@jlowin](https://github.com/jlowin) in [#1412](https://github.com/PrefectHQ/fastmcp/pull/1412)\n* Marvin: fix deprecated variable names by [@jlowin](https://github.com/jlowin) in [#1417](https://github.com/PrefectHQ/fastmcp/pull/1417)\n* Simplify action setup and add github tools for Marvin by [@jlowin](https://github.com/jlowin) in [#1419](https://github.com/PrefectHQ/fastmcp/pull/1419)\n* Update marvin workflow name by [@jlowin](https://github.com/jlowin) in [#1421](https://github.com/PrefectHQ/fastmcp/pull/1421)\n* Improve GitHub templates by [@jlowin](https://github.com/jlowin) in [#1422](https://github.com/PrefectHQ/fastmcp/pull/1422)\n\n## New Contributors\n* [@panargirakis](https://github.com/panargirakis) made their first contribution in [#1399](https://github.com/PrefectHQ/fastmcp/pull/1399)\n* [@ykun9](https://github.com/ykun9) made their first contribution in [#1389](https://github.com/PrefectHQ/fastmcp/pull/1389)\n* [@yannj-fr](https://github.com/yannj-fr) made their first contribution in [#1371](https://github.com/PrefectHQ/fastmcp/pull/1371)\n\n**Full Changelog**: [v2.11.2...v2.11.3](https://github.com/PrefectHQ/fastmcp/compare/v2.11.2...v2.11.3)\n\n\n\n\n\n## [v2.11.2: Satis-factory](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.2)\n\n## What's Changed\n### Enhancements 🔧\n* Support factory functions in fastmcp run by [@jlowin](https://github.com/jlowin) in [#1384](https://github.com/PrefectHQ/fastmcp/pull/1384)\n* Add async support to client_factory in FastMCPProxy (#1286) by [@bianning](https://github.com/bianning) in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)\n### Fixes 🐞\n* Fix server_version field in inspect manifest by [@jlowin](https://github.com/jlowin) in [#1383](https://github.com/PrefectHQ/fastmcp/pull/1383)\n* Fix Settings field with both default and default_factory by [@jlowin](https://github.com/jlowin) in [#1380](https://github.com/PrefectHQ/fastmcp/pull/1380)\n### Other Changes 🦾\n* Remove unused arg by [@jlowin](https://github.com/jlowin) in [#1382](https://github.com/PrefectHQ/fastmcp/pull/1382)\n* Add remote auth provider tests by [@jlowin](https://github.com/jlowin) in [#1351](https://github.com/PrefectHQ/fastmcp/pull/1351)\n\n## New Contributors\n* [@bianning](https://github.com/bianning) made their first contribution in [#1375](https://github.com/PrefectHQ/fastmcp/pull/1375)\n\n**Full Changelog**: [v2.11.1...v2.11.2](https://github.com/PrefectHQ/fastmcp/compare/v2.11.1...v2.11.2)\n\n\n\n\n\n## [v2.11.1: You're Better Auth Now](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.1)\n\n## What's Changed\n### New Features 🎉\n* 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)\n### Enhancements 🔧\n* perf: optimize string operations in OpenAPI parameter processing by [@chi2liu](https://github.com/chi2liu) in [#1342](https://github.com/PrefectHQ/fastmcp/pull/1342)\n### Fixes 🐞\n* Fix method-bound FunctionTool schemas by [@strawgate](https://github.com/strawgate) in [#1360](https://github.com/PrefectHQ/fastmcp/pull/1360)\n* 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)\n### Docs 📚\n* Docs updates by [@jlowin](https://github.com/jlowin) in [#1336](https://github.com/PrefectHQ/fastmcp/pull/1336)\n* Add 2.11 to changelog by [@jlowin](https://github.com/jlowin) in [#1337](https://github.com/PrefectHQ/fastmcp/pull/1337)\n* Update AuthKit vocab by [@jlowin](https://github.com/jlowin) in [#1338](https://github.com/PrefectHQ/fastmcp/pull/1338)\n* Fix typo in decorating-methods.mdx by [@Ozzuke](https://github.com/Ozzuke) in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)\n\n## New Contributors\n* [@Ozzuke](https://github.com/Ozzuke) made their first contribution in [#1344](https://github.com/PrefectHQ/fastmcp/pull/1344)\n\n**Full Changelog**: [v2.11.0...v2.11.1](https://github.com/PrefectHQ/fastmcp/compare/v2.11.0...v2.11.1)\n\n\n\n\n\n## [v2.11.0: Auth to a Good Start](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.11.0)\n\nFastMCP 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.\n\n🔐 **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.\n\n⚡ 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.)_\n\n🧠 **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.\n\nThis release represents a TON of community contributions and sets the foundation for even more ambitious features ahead.\n\n## What's Changed\n### New Features 🎉\n* Introduce experimental OpenAPI parser with improved performance and maintainability by [@jlowin](https://github.com/jlowin) in [#1209](https://github.com/PrefectHQ/fastmcp/pull/1209)\n* Add state dict to Context (#1118) by [@mukulmurthy](https://github.com/mukulmurthy) in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)\n* Expose FastMCP tags to clients via component `meta` dict by [@jlowin](https://github.com/jlowin) in [#1281](https://github.com/PrefectHQ/fastmcp/pull/1281)\n* Add _fastmcp meta namespace by [@jlowin](https://github.com/jlowin) in [#1290](https://github.com/PrefectHQ/fastmcp/pull/1290)\n* Add TokenVerifier protocol support alongside existing OAuthProvider authentication by [@jlowin](https://github.com/jlowin) in [#1297](https://github.com/PrefectHQ/fastmcp/pull/1297)\n* 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)\n### Enhancements 🔧\n* [🐶] Transform MCP Server Tools by [@strawgate](https://github.com/strawgate) in [#1132](https://github.com/PrefectHQ/fastmcp/pull/1132)\n* 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)\n* Support `fastmcp run mcp.json` by [@strawgate](https://github.com/strawgate) in [#1138](https://github.com/PrefectHQ/fastmcp/pull/1138)\n* Support from __future__ import annotations by [@jlowin](https://github.com/jlowin) in [#1199](https://github.com/PrefectHQ/fastmcp/pull/1199)\n* Optimize OpenAPI parser performance with single-pass schema processing by [@jlowin](https://github.com/jlowin) in [#1214](https://github.com/PrefectHQ/fastmcp/pull/1214)\n* Log tool name on transform validation error by [@strawgate](https://github.com/strawgate) in [#1238](https://github.com/PrefectHQ/fastmcp/pull/1238)\n* Refactor `get_http_request` and `context.session_id` by [@hopeful0](https://github.com/hopeful0) in [#1242](https://github.com/PrefectHQ/fastmcp/pull/1242)\n* Support creating tool argument descriptions from string annotations by [@jlowin](https://github.com/jlowin) in [#1255](https://github.com/PrefectHQ/fastmcp/pull/1255)\n* feat: Add Annotations support for resources and resource templates by [@chughtapan](https://github.com/chughtapan) in [#1260](https://github.com/PrefectHQ/fastmcp/pull/1260)\n* Add UV Transport by [@strawgate](https://github.com/strawgate) in [#1270](https://github.com/PrefectHQ/fastmcp/pull/1270)\n* Improve OpenAPI-to-JSONSchema conversion utilities by [@jlowin](https://github.com/jlowin) in [#1283](https://github.com/PrefectHQ/fastmcp/pull/1283)\n* Ensure proxy components forward meta dicts by [@jlowin](https://github.com/jlowin) in [#1282](https://github.com/PrefectHQ/fastmcp/pull/1282)\n* fix: server argument passing in CLI run command by [@chughtapan](https://github.com/chughtapan) in [#1293](https://github.com/PrefectHQ/fastmcp/pull/1293)\n* Add meta support to tool transformation utilities by [@jlowin](https://github.com/jlowin) in [#1295](https://github.com/PrefectHQ/fastmcp/pull/1295)\n* feat: Allow Resource Metadata URL as field in OAuthProvider by [@dacamposol](https://github.com/dacamposol) in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)\n* 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)\n* Remove unused TimedCache by [@strawgate](https://github.com/strawgate) in [#1303](https://github.com/PrefectHQ/fastmcp/pull/1303)\n* refactor: standardize logging usage across OpenAPI utilities by [@chi2liu](https://github.com/chi2liu) in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)\n* perf: optimize OpenAPI parsing by reducing dict copy operations by [@chi2liu](https://github.com/chi2liu) in [#1321](https://github.com/PrefectHQ/fastmcp/pull/1321)\n* Structured client-side logging by [@cjermain](https://github.com/cjermain) in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)\n### Fixes 🐞\n* 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)\n* fix: add type hint to custom_route decorator by [@zzstoatzz](https://github.com/zzstoatzz) in [#1210](https://github.com/PrefectHQ/fastmcp/pull/1210)\n* chore: typo by [@richardkmichael](https://github.com/richardkmichael) in [#1216](https://github.com/PrefectHQ/fastmcp/pull/1216)\n* 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)\n* 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)\n* Ensure default fields are not marked nullable by [@jlowin](https://github.com/jlowin) in [#1224](https://github.com/PrefectHQ/fastmcp/pull/1224)\n* Fix stateful proxy client mixing in multi-proxies sessions by [@hopeful0](https://github.com/hopeful0) in [#1245](https://github.com/PrefectHQ/fastmcp/pull/1245)\n* Fix invalid async context manager usage in proxy documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#1246](https://github.com/PrefectHQ/fastmcp/pull/1246)\n* 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)\n* Fix typing, add tests for tool call middleware by [@jlowin](https://github.com/jlowin) in [#1269](https://github.com/PrefectHQ/fastmcp/pull/1269)\n* Fix: prune hidden parameter defs by [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)\n* 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)\n* Ensure fastmcp run supports v1 servers by [@jlowin](https://github.com/jlowin) in [#1332](https://github.com/PrefectHQ/fastmcp/pull/1332)\n### Breaking Changes 🛫\n* Change server flag to --name by [@jlowin](https://github.com/jlowin) in [#1248](https://github.com/PrefectHQ/fastmcp/pull/1248)\n### Docs 📚\n* Remove unused import from FastAPI integration documentation by [@mariotaddeucci](https://github.com/mariotaddeucci) in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)\n* Update fastapi docs by [@jlowin](https://github.com/jlowin) in [#1198](https://github.com/PrefectHQ/fastmcp/pull/1198)\n* Add docs for context state management by [@jlowin](https://github.com/jlowin) in [#1227](https://github.com/PrefectHQ/fastmcp/pull/1227)\n* Permit.io integration docs by [@orweis](https://github.com/orweis) in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)\n* Update docs to reflect sync tools by [@jlowin](https://github.com/jlowin) in [#1234](https://github.com/PrefectHQ/fastmcp/pull/1234)\n* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1235](https://github.com/PrefectHQ/fastmcp/pull/1235)\n* Update SDK docs by [@jlowin](https://github.com/jlowin) in [#1236](https://github.com/PrefectHQ/fastmcp/pull/1236)\n* Update --name flag documentation for Cursor/Claude by [@adam-conway](https://github.com/adam-conway) in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)\n* Add annotations docs by [@jlowin](https://github.com/jlowin) in [#1268](https://github.com/PrefectHQ/fastmcp/pull/1268)\n* Update openapi/fastapi URLs README.md by [@jbn](https://github.com/jbn) in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)\n* Add 2.11 version badge for state management by [@jlowin](https://github.com/jlowin) in [#1289](https://github.com/PrefectHQ/fastmcp/pull/1289)\n* 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)\n* docs: update get_state and set_state references by [@Maxi91f](https://github.com/Maxi91f) in [#1306](https://github.com/PrefectHQ/fastmcp/pull/1306)\n* 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)\n* Remove reference to stacked decorators by [@jlowin](https://github.com/jlowin) in [#1334](https://github.com/PrefectHQ/fastmcp/pull/1334)\n* 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)\n### Other Changes 🦾\n* Update README.md by [@jlowin](https://github.com/jlowin) in [#1230](https://github.com/PrefectHQ/fastmcp/pull/1230)\n* Logcapture addition to test_server file by [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)\n* 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)\n* Small clean-up from MCP Tool Transform PR by [@strawgate](https://github.com/strawgate) in [#1267](https://github.com/PrefectHQ/fastmcp/pull/1267)\n* Add test for proxy tags visibility by [@jlowin](https://github.com/jlowin) in [#1302](https://github.com/PrefectHQ/fastmcp/pull/1302)\n* Add unit test for sampling with image messages by [@jlowin](https://github.com/jlowin) in [#1329](https://github.com/PrefectHQ/fastmcp/pull/1329)\n* Remove redundant resource_metadata_url assignment by [@jlowin](https://github.com/jlowin) in [#1328](https://github.com/PrefectHQ/fastmcp/pull/1328)\n* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#1331](https://github.com/PrefectHQ/fastmcp/pull/1331)\n* Ensure validation errors are raised when masked by [@jlowin](https://github.com/jlowin) in [#1330](https://github.com/PrefectHQ/fastmcp/pull/1330)\n\n## New Contributors\n* [@mariotaddeucci](https://github.com/mariotaddeucci) made their first contribution in [#1194](https://github.com/PrefectHQ/fastmcp/pull/1194)\n* [@algirdasci](https://github.com/algirdasci) made their first contribution in [#1208](https://github.com/PrefectHQ/fastmcp/pull/1208)\n* [@chughtapan](https://github.com/chughtapan) made their first contribution in [#1222](https://github.com/PrefectHQ/fastmcp/pull/1222)\n* [@mukulmurthy](https://github.com/mukulmurthy) made their first contribution in [#1160](https://github.com/PrefectHQ/fastmcp/pull/1160)\n* [@orweis](https://github.com/orweis) made their first contribution in [#1226](https://github.com/PrefectHQ/fastmcp/pull/1226)\n* [@Sourav-Tripathy](https://github.com/Sourav-Tripathy) made their first contribution in [#1229](https://github.com/PrefectHQ/fastmcp/pull/1229)\n* [@adam-conway](https://github.com/adam-conway) made their first contribution in [#1239](https://github.com/PrefectHQ/fastmcp/pull/1239)\n* [@muhammadkhalid-03](https://github.com/muhammadkhalid-03) made their first contribution in [#1257](https://github.com/PrefectHQ/fastmcp/pull/1257)\n* [@jbn](https://github.com/jbn) made their first contribution in [#1278](https://github.com/PrefectHQ/fastmcp/pull/1278)\n* [@dacamposol](https://github.com/dacamposol) made their first contribution in [#1287](https://github.com/PrefectHQ/fastmcp/pull/1287)\n* [@chi2liu](https://github.com/chi2liu) made their first contribution in [#1322](https://github.com/PrefectHQ/fastmcp/pull/1322)\n* [@cjermain](https://github.com/cjermain) made their first contribution in [#1326](https://github.com/PrefectHQ/fastmcp/pull/1326)\n\n**Full Changelog**: [v2.10.6...v2.11.0](https://github.com/PrefectHQ/fastmcp/compare/v2.10.6...v2.11.0)\n\n\n\n\n\n## [v2.10.6: Hymn for the Weekend](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.6)\n\nA special Saturday release with many fixes.\n\n## What's Changed\n### Enhancements 🔧\n* Resolve #1139 -- Implement include_context argument in Context.sample by [@codingjoe](https://github.com/codingjoe) in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)\n* feat(settings): add log level normalization by [@ka2048](https://github.com/ka2048) in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)\n* add server name to mounted server warnings by [@artificial-aidan](https://github.com/artificial-aidan) in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)\n* Add StatefulProxyClient by [@hopeful0](https://github.com/hopeful0) in [#1109](https://github.com/PrefectHQ/fastmcp/pull/1109)\n### Fixes 🐞\n* Fix OpenAPI empty parameters by [@FabrizioSandri](https://github.com/FabrizioSandri) in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)\n* Fix title field preservation in tool transformations by [@jlowin](https://github.com/jlowin) in [#1131](https://github.com/PrefectHQ/fastmcp/pull/1131)\n* Fix optional parameter validation in OpenAPI integration by [@jlowin](https://github.com/jlowin) in [#1135](https://github.com/PrefectHQ/fastmcp/pull/1135)\n* 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)\n* 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)\n* 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)\n* Fix nesting when making OpenAPI arrays and objects optional by [@melkamar](https://github.com/melkamar) in [#1178](https://github.com/PrefectHQ/fastmcp/pull/1178)\n* Fix `mcp-json` output format to include server name by [@jlowin](https://github.com/jlowin) in [#1185](https://github.com/PrefectHQ/fastmcp/pull/1185)\n* Only configure logging one time by [@jlowin](https://github.com/jlowin) in [#1187](https://github.com/PrefectHQ/fastmcp/pull/1187)\n### Docs 📚\n* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1127](https://github.com/PrefectHQ/fastmcp/pull/1127)\n* Eunomia Authorization with native FastMCP's Middleware by [@tommitt](https://github.com/tommitt) in [#1144](https://github.com/PrefectHQ/fastmcp/pull/1144)\n* update api ref for new `mdxify` version by [@zzstoatzz](https://github.com/zzstoatzz) in [#1182](https://github.com/PrefectHQ/fastmcp/pull/1182)\n### Other Changes 🦾\n* Expand empty parameter filtering and add comprehensive tests by [@jlowin](https://github.com/jlowin) in [#1129](https://github.com/PrefectHQ/fastmcp/pull/1129)\n* Add no-commit-to-branch hook by [@zzstoatzz](https://github.com/zzstoatzz) in [#1149](https://github.com/PrefectHQ/fastmcp/pull/1149)\n* Update README.md by [@jlowin](https://github.com/jlowin) in [#1165](https://github.com/PrefectHQ/fastmcp/pull/1165)\n* skip on rate limit by [@zzstoatzz](https://github.com/zzstoatzz) in [#1183](https://github.com/PrefectHQ/fastmcp/pull/1183)\n* Remove deprecated proxy creation by [@jlowin](https://github.com/jlowin) in [#1186](https://github.com/PrefectHQ/fastmcp/pull/1186)\n* Separate integration tests from unit tests in CI by [@jlowin](https://github.com/jlowin) in [#1188](https://github.com/PrefectHQ/fastmcp/pull/1188)\n\n## New Contributors\n* [@FabrizioSandri](https://github.com/FabrizioSandri) made their first contribution in [#1128](https://github.com/PrefectHQ/fastmcp/pull/1128)\n* [@melkamar](https://github.com/melkamar) made their first contribution in [#1153](https://github.com/PrefectHQ/fastmcp/pull/1153)\n* [@codingjoe](https://github.com/codingjoe) made their first contribution in [#1141](https://github.com/PrefectHQ/fastmcp/pull/1141)\n* [@itaru2622](https://github.com/itaru2622) made their first contribution in [#1164](https://github.com/PrefectHQ/fastmcp/pull/1164)\n* [@ka2048](https://github.com/ka2048) made their first contribution in [#1171](https://github.com/PrefectHQ/fastmcp/pull/1171)\n* [@artificial-aidan](https://github.com/artificial-aidan) made their first contribution in [#1147](https://github.com/PrefectHQ/fastmcp/pull/1147)\n\n**Full Changelog**: [v2.10.5...v2.10.6](https://github.com/PrefectHQ/fastmcp/compare/v2.10.5...v2.10.6)\n\n\n\n\n\n## [v2.10.5: Middle Management](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.5)\n\nA maintenance release focused on OpenAPI refinements and middleware fixes, plus console improvements.\n\n## What's Changed\n### Enhancements 🔧\n* Fix Claude Code CLI detection for npm global installations by [@jlowin](https://github.com/jlowin) in [#1106](https://github.com/PrefectHQ/fastmcp/pull/1106)\n* Fix OpenAPI parameter name collisions with location suffixing by [@jlowin](https://github.com/jlowin) in [#1107](https://github.com/PrefectHQ/fastmcp/pull/1107)\n* Add mirrored component support for proxy servers by [@jlowin](https://github.com/jlowin) in [#1105](https://github.com/PrefectHQ/fastmcp/pull/1105)\n### Fixes 🐞\n* Fix OpenAPI deepObject style parameter encoding by [@jlowin](https://github.com/jlowin) in [#1122](https://github.com/PrefectHQ/fastmcp/pull/1122)\n* xfail when github token is not set ('' or None) by [@jlowin](https://github.com/jlowin) in [#1123](https://github.com/PrefectHQ/fastmcp/pull/1123)\n* fix: replace oneOf with anyOf in OpenAPI output schemas by [@MagnusS0](https://github.com/MagnusS0) in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)\n* Fix middleware list result types by [@jlowin](https://github.com/jlowin) in [#1125](https://github.com/PrefectHQ/fastmcp/pull/1125)\n* Improve console width for logo by [@jlowin](https://github.com/jlowin) in [#1126](https://github.com/PrefectHQ/fastmcp/pull/1126)\n### Docs 📚\n* Improve transport + integration docs by [@jlowin](https://github.com/jlowin) in [#1103](https://github.com/PrefectHQ/fastmcp/pull/1103)\n* Update proxy.mdx by [@coldfire-x](https://github.com/coldfire-x) in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)\n### Other Changes 🦾\n* Update github remote server tests with secret by [@jlowin](https://github.com/jlowin) in [#1112](https://github.com/PrefectHQ/fastmcp/pull/1112)\n\n## New Contributors\n* [@coldfire-x](https://github.com/coldfire-x) made their first contribution in [#1108](https://github.com/PrefectHQ/fastmcp/pull/1108)\n* [@MagnusS0](https://github.com/MagnusS0) made their first contribution in [#1119](https://github.com/PrefectHQ/fastmcp/pull/1119)\n\n**Full Changelog**: [v2.10.4...v2.10.5](https://github.com/PrefectHQ/fastmcp/compare/v2.10.4...v2.10.5)\n\n\n\n\n\n## [v2.10.4: Transport-ation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.4)\n\nA quick fix to ensure the CLI accepts \"streamable-http\" as a valid transport option.\n\n## What's Changed\n### Fixes 🐞\n* 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)\n\n**Full Changelog**: [v2.10.3...v2.10.4](https://github.com/PrefectHQ/fastmcp/compare/v2.10.3...v2.10.4)\n\n\n\n\n\n## [v2.10.3: CLI Me a River](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.3)\n\nA major CLI overhaul featuring a complete refactor from typer to cyclopts, new IDE integrations, and comprehensive OpenAPI improvements.\n\n## What's Changed\n### New Features 🎉\n* 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)\n* Add output schema support for OpenAPI tools by [@jlowin](https://github.com/jlowin) in [#1073](https://github.com/PrefectHQ/fastmcp/pull/1073)\n### Enhancements 🔧\n* Add Cursor support via CLI integration by [@jlowin](https://github.com/jlowin) in [#1052](https://github.com/PrefectHQ/fastmcp/pull/1052)\n* Add Claude Code install integration by [@jlowin](https://github.com/jlowin) in [#1053](https://github.com/PrefectHQ/fastmcp/pull/1053)\n* 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)\n* Use isawaitable instead of iscoroutine by [@jlowin](https://github.com/jlowin) in [#1059](https://github.com/PrefectHQ/fastmcp/pull/1059)\n* 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)\n* Fix concurrent proxy client operations with session isolation by [@jlowin](https://github.com/jlowin) in [#1083](https://github.com/PrefectHQ/fastmcp/pull/1083)\n### Fixes 🐞\n* Refactor Client context management to avoid concurrency issue by [@hopeful0](https://github.com/hopeful0) in [#1054](https://github.com/PrefectHQ/fastmcp/pull/1054)\n* Keep json schema $defs on transform by [@strawgate](https://github.com/strawgate) in [#1066](https://github.com/PrefectHQ/fastmcp/pull/1066)\n* Ensure fastmcp version copy is plaintext by [@jlowin](https://github.com/jlowin) in [#1071](https://github.com/PrefectHQ/fastmcp/pull/1071)\n* Fix single-element list unwrapping in tool content by [@jlowin](https://github.com/jlowin) in [#1074](https://github.com/PrefectHQ/fastmcp/pull/1074)\n* Fix max recursion error when pruning OpenAPI definitions by [@dimitribarbot](https://github.com/dimitribarbot) in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)\n* 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)\n### Docs 📚\n* 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)\n* Update favicon by [@jlowin](https://github.com/jlowin) in [#1058](https://github.com/PrefectHQ/fastmcp/pull/1058)\n* Update environment note by [@jlowin](https://github.com/jlowin) in [#1075](https://github.com/PrefectHQ/fastmcp/pull/1075)\n* Add fastmcp version --copy documentation by [@jlowin](https://github.com/jlowin) in [#1076](https://github.com/PrefectHQ/fastmcp/pull/1076)\n### Other Changes 🦾\n* Remove asserts and add documentation following #1054 by [@jlowin](https://github.com/jlowin) in [#1057](https://github.com/PrefectHQ/fastmcp/pull/1057)\n* Add --copy flag for fastmcp version by [@jlowin](https://github.com/jlowin) in [#1063](https://github.com/PrefectHQ/fastmcp/pull/1063)\n* Fix docstring format for fastmcp.client.Client by [@neilconway](https://github.com/neilconway) in [#1094](https://github.com/PrefectHQ/fastmcp/pull/1094)\n\n## New Contributors\n* [@neilconway](https://github.com/neilconway) made their first contribution in [#1055](https://github.com/PrefectHQ/fastmcp/pull/1055)\n* [@davidbk-legit](https://github.com/davidbk-legit) made their first contribution in [#1087](https://github.com/PrefectHQ/fastmcp/pull/1087)\n* [@dimitribarbot](https://github.com/dimitribarbot) made their first contribution in [#1092](https://github.com/PrefectHQ/fastmcp/pull/1092)\n\n**Full Changelog**: [v2.10.2...v2.10.3](https://github.com/PrefectHQ/fastmcp/compare/v2.10.2...v2.10.3)\n\n\n\n\n\n## [v2.10.2: Forward March](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.2)\n\nThe 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.\n\n## What's Changed\n### New Features 🎉\n* Proxy support advanced MCP features by [@hopeful0](https://github.com/hopeful0) in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)\n### Enhancements 🔧\n* Re-add splash screen by [@jlowin](https://github.com/jlowin) in [#1027](https://github.com/PrefectHQ/fastmcp/pull/1027)\n* Reduce banner padding by [@jlowin](https://github.com/jlowin) in [#1030](https://github.com/PrefectHQ/fastmcp/pull/1030)\n* Allow per-server timeouts in MCPConfig by [@cegersdoerfer](https://github.com/cegersdoerfer) in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)\n* Support 'scp' claim for OAuth scopes in BearerAuthProvider by [@jlowin](https://github.com/jlowin) in [#1033](https://github.com/PrefectHQ/fastmcp/pull/1033)\n* Add path expansion to image/audio/file by [@jlowin](https://github.com/jlowin) in [#1038](https://github.com/PrefectHQ/fastmcp/pull/1038)\n* Ensure multi-client configurations use new ProxyClient by [@jlowin](https://github.com/jlowin) in [#1045](https://github.com/PrefectHQ/fastmcp/pull/1045)\n### Fixes 🐞\n* Expose stateless_http kwarg for mcp.run() by [@jlowin](https://github.com/jlowin) in [#1018](https://github.com/PrefectHQ/fastmcp/pull/1018)\n* Avoid propagating logs by [@jlowin](https://github.com/jlowin) in [#1042](https://github.com/PrefectHQ/fastmcp/pull/1042)\n### Docs 📚\n* Clean up docs by [@jlowin](https://github.com/jlowin) in [#1028](https://github.com/PrefectHQ/fastmcp/pull/1028)\n* Docs: clarify server URL paths for ChatGPT integration by [@thap2331](https://github.com/thap2331) in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)\n### Other Changes 🦾\n* Split giant openapi test file into smaller files by [@jlowin](https://github.com/jlowin) in [#1034](https://github.com/PrefectHQ/fastmcp/pull/1034)\n* 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)\n* Update banner and use console.log by [@jlowin](https://github.com/jlowin) in [#1041](https://github.com/PrefectHQ/fastmcp/pull/1041)\n\n## New Contributors\n* [@cegersdoerfer](https://github.com/cegersdoerfer) made their first contribution in [#1031](https://github.com/PrefectHQ/fastmcp/pull/1031)\n* [@hopeful0](https://github.com/hopeful0) made their first contribution in [#1022](https://github.com/PrefectHQ/fastmcp/pull/1022)\n* [@thap2331](https://github.com/thap2331) made their first contribution in [#1017](https://github.com/PrefectHQ/fastmcp/pull/1017)\n\n**Full Changelog**: [v2.10.1...v2.10.2](https://github.com/PrefectHQ/fastmcp/compare/v2.10.1...v2.10.2)\n\n\n\n\n\n## [v2.10.1: Revert to Sender](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.1)\n\nA quick patch to revert the CLI banner that was added in v2.10.0.\n\n## What's Changed\n### Docs 📚\n* Update changelog.mdx by [@jlowin](https://github.com/jlowin) in [#1009](https://github.com/PrefectHQ/fastmcp/pull/1009)\n* Revert \"Add CLI banner\" by [@jlowin](https://github.com/jlowin) in [#1011](https://github.com/PrefectHQ/fastmcp/pull/1011)\n\n**Full Changelog**: [v2.10.0...v2.10.1](https://github.com/PrefectHQ/fastmcp/compare/v2.10.0...v2.10.1)\n\n\n\n\n\n## [v2.10.0: Great Spec-tations](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.10.0)\n\nFastMCP 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()`.\n\n### Elicitation Support\nElicitation 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.\n\n### Output Schemas\nTools can now define structured output schemas, ensuring that responses conform to expected formats and making tool integration more predictable and type-safe.\n\n## What's Changed\n### New Features 🎉\n* MCP 6/18/25: Add output schema to tools by [@jlowin](https://github.com/jlowin) in [#901](https://github.com/PrefectHQ/fastmcp/pull/901)\n* MCP 6/18/25: Elicitation support by [@jlowin](https://github.com/jlowin) in [#889](https://github.com/PrefectHQ/fastmcp/pull/889)\n### Enhancements 🔧\n* Update types + tests for SDK changes by [@jlowin](https://github.com/jlowin) in [#888](https://github.com/PrefectHQ/fastmcp/pull/888)\n* MCP 6/18/25: Update auth primitives by [@jlowin](https://github.com/jlowin) in [#966](https://github.com/PrefectHQ/fastmcp/pull/966)\n* Add OpenAPI extensions support to HTTPRoute by [@maddymanu](https://github.com/maddymanu) in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)\n* Add title field support to FastMCP components by [@jlowin](https://github.com/jlowin) in [#982](https://github.com/PrefectHQ/fastmcp/pull/982)\n* Support implicit Elicitation acceptance by [@jlowin](https://github.com/jlowin) in [#983](https://github.com/PrefectHQ/fastmcp/pull/983)\n* Support 'no response' elicitation requests by [@jlowin](https://github.com/jlowin) in [#992](https://github.com/PrefectHQ/fastmcp/pull/992)\n* Add Support for Configurable Algorithms by [@sstene1](https://github.com/sstene1) in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)\n### Fixes 🐞\n* Improve stdio error handling to raise connection failures immediately by [@jlowin](https://github.com/jlowin) in [#984](https://github.com/PrefectHQ/fastmcp/pull/984)\n* Fix type hints for FunctionResource:fn by [@CfirTsabari](https://github.com/CfirTsabari) in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)\n* Update link to OpenAI MCP example by [@mossbanay](https://github.com/mossbanay) in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)\n* Fix output schema generation edge case by [@jlowin](https://github.com/jlowin) in [#995](https://github.com/PrefectHQ/fastmcp/pull/995)\n* Refactor array parameter formatting to reduce code duplication by [@jlowin](https://github.com/jlowin) in [#1007](https://github.com/PrefectHQ/fastmcp/pull/1007)\n* Fix OpenAPI array parameter explode handling by [@jlowin](https://github.com/jlowin) in [#1008](https://github.com/PrefectHQ/fastmcp/pull/1008)\n### Breaking Changes 🛫\n* MCP 6/18/25: Upgrade to mcp 1.10 by [@jlowin](https://github.com/jlowin) in [#887](https://github.com/PrefectHQ/fastmcp/pull/887)\n### Docs 📚\n* Update middleware imports and documentation by [@jlowin](https://github.com/jlowin) in [#999](https://github.com/PrefectHQ/fastmcp/pull/999)\n* Update OpenAI docs by [@jlowin](https://github.com/jlowin) in [#1001](https://github.com/PrefectHQ/fastmcp/pull/1001)\n* Add CLI banner by [@jlowin](https://github.com/jlowin) in [#1005](https://github.com/PrefectHQ/fastmcp/pull/1005)\n### Examples & Contrib 💡\n* Component Manager by [@gorocode](https://github.com/gorocode) in [#976](https://github.com/PrefectHQ/fastmcp/pull/976)\n### Other Changes 🦾\n* Minor auth improvements by [@jlowin](https://github.com/jlowin) in [#967](https://github.com/PrefectHQ/fastmcp/pull/967)\n* Add .ccignore for copychat by [@jlowin](https://github.com/jlowin) in [#1000](https://github.com/PrefectHQ/fastmcp/pull/1000)\n\n## New Contributors\n* [@maddymanu](https://github.com/maddymanu) made their first contribution in [#977](https://github.com/PrefectHQ/fastmcp/pull/977)\n* [@github0hello](https://github.com/github0hello) made their first contribution in [#979](https://github.com/PrefectHQ/fastmcp/pull/979)\n* [@tommitt](https://github.com/tommitt) made their first contribution in [#975](https://github.com/PrefectHQ/fastmcp/pull/975)\n* [@CfirTsabari](https://github.com/CfirTsabari) made their first contribution in [#986](https://github.com/PrefectHQ/fastmcp/pull/986)\n* [@mossbanay](https://github.com/mossbanay) made their first contribution in [#985](https://github.com/PrefectHQ/fastmcp/pull/985)\n* [@sstene1](https://github.com/sstene1) made their first contribution in [#997](https://github.com/PrefectHQ/fastmcp/pull/997)\n\n**Full Changelog**: [v2.9.2...v2.10.0](https://github.com/PrefectHQ/fastmcp/compare/v2.9.2...v2.10.0)\n\n\n\n\n\n## [v2.9.2: Safety Pin](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.2)\n\nThis 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.\n\n## What's Changed\n### Docs 📚\n* Fix version badge for messages by [@jlowin](https://github.com/jlowin) in [#960](https://github.com/PrefectHQ/fastmcp/pull/960)\n### Dependencies 📦\n* Pin mcp dependency by [@jlowin](https://github.com/jlowin) in [#962](https://github.com/PrefectHQ/fastmcp/pull/962)\n\n**Full Changelog**: [v2.9.1...v2.9.2](https://github.com/PrefectHQ/fastmcp/compare/v2.9.1...v2.9.2)\n\n\n\n\n\n## [v2.9.1: Call Me Maybe](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.1)\n\nFastMCP 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.\n\n## What's Changed\n### New Features 🎉\n* 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)\n### Enhancements 🔧\n* Add debug logging to bearer token authentication by [@jlowin](https://github.com/jlowin) in [#952](https://github.com/PrefectHQ/fastmcp/pull/952)\n### Fixes 🐞\n* Fix duplicate error logging in exception handlers by [@jlowin](https://github.com/jlowin) in [#938](https://github.com/PrefectHQ/fastmcp/pull/938)\n* Fix parameter location enum handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#953](https://github.com/PrefectHQ/fastmcp/pull/953)\n* Fix external schema reference handling in OpenAPI parser by [@jlowin](https://github.com/jlowin) in [#954](https://github.com/PrefectHQ/fastmcp/pull/954)\n### Docs 📚\n* Update changelog for 2.9 release by [@jlowin](https://github.com/jlowin) in [#929](https://github.com/PrefectHQ/fastmcp/pull/929)\n* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#935](https://github.com/PrefectHQ/fastmcp/pull/935)\n* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#947](https://github.com/PrefectHQ/fastmcp/pull/947)\n* Regenerate API references by [@zzstoatzz](https://github.com/zzstoatzz) in [#949](https://github.com/PrefectHQ/fastmcp/pull/949)\n### Examples & Contrib 💡\n* Add `create_thread` tool to bsky MCP server by [@zzstoatzz](https://github.com/zzstoatzz) in [#927](https://github.com/PrefectHQ/fastmcp/pull/927)\n* 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)\n\n## New Contributors\n* [@rajephon](https://github.com/rajephon) made their first contribution in [#957](https://github.com/PrefectHQ/fastmcp/pull/957)\n\n**Full Changelog**: [v2.9.0...v2.9.1](https://github.com/PrefectHQ/fastmcp/compare/v2.9.0...v2.9.1)\n\n\n\n\n\n## [v2.9.0: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.9.0)\n\nFastMCP 2.9 introduces two important features that push beyond the basic MCP protocol: MCP Middleware and server-side type conversion.\n\n### MCP Middleware\nMCP 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.\n\n### Server-side Type Conversion\nThis 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.\n\n## What's Changed\n### New Features 🎉\n* Add File utility for binary data by [@gorocode](https://github.com/gorocode) in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)\n* Consolidate prefix logic into FastMCP methods by [@jlowin](https://github.com/jlowin) in [#861](https://github.com/PrefectHQ/fastmcp/pull/861)\n* Add MCP Middleware by [@jlowin](https://github.com/jlowin) in [#870](https://github.com/PrefectHQ/fastmcp/pull/870)\n* Implement server-side type conversion for prompt arguments by [@jlowin](https://github.com/jlowin) in [#908](https://github.com/PrefectHQ/fastmcp/pull/908)\n### Enhancements 🔧\n* Fix tool description indentation issue by [@zfflxx](https://github.com/zfflxx) in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)\n* Add version parameter to FastMCP constructor by [@mkyutani](https://github.com/mkyutani) in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)\n* Update version to not be positional by [@jlowin](https://github.com/jlowin) in [#848](https://github.com/PrefectHQ/fastmcp/pull/848)\n* Add key to component by [@jlowin](https://github.com/jlowin) in [#869](https://github.com/PrefectHQ/fastmcp/pull/869)\n* Add session_id property to Context for data sharing by [@jlowin](https://github.com/jlowin) in [#881](https://github.com/PrefectHQ/fastmcp/pull/881)\n* Fix CORS documentation example by [@jlowin](https://github.com/jlowin) in [#895](https://github.com/PrefectHQ/fastmcp/pull/895)\n### Fixes 🐞\n* \"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)\n* 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)\n* Fix BearerAuthProvider audience type annotations by [@jlowin](https://github.com/jlowin) in [#894](https://github.com/PrefectHQ/fastmcp/pull/894)\n### Docs 📚\n* Add CLAUDE.md development guidelines by [@jlowin](https://github.com/jlowin) in [#880](https://github.com/PrefectHQ/fastmcp/pull/880)\n* Update context docs for session_id property by [@jlowin](https://github.com/jlowin) in [#882](https://github.com/PrefectHQ/fastmcp/pull/882)\n* Add API reference by [@zzstoatzz](https://github.com/zzstoatzz) in [#893](https://github.com/PrefectHQ/fastmcp/pull/893)\n* Fix API ref rendering by [@zzstoatzz](https://github.com/zzstoatzz) in [#900](https://github.com/PrefectHQ/fastmcp/pull/900)\n* Simplify docs nav by [@jlowin](https://github.com/jlowin) in [#902](https://github.com/PrefectHQ/fastmcp/pull/902)\n* Add fastmcp inspect command by [@jlowin](https://github.com/jlowin) in [#904](https://github.com/PrefectHQ/fastmcp/pull/904)\n* Update client docs by [@jlowin](https://github.com/jlowin) in [#912](https://github.com/PrefectHQ/fastmcp/pull/912)\n* Update docs nav by [@jlowin](https://github.com/jlowin) in [#913](https://github.com/PrefectHQ/fastmcp/pull/913)\n* 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)\n* Add http as an alias for streamable http by [@jlowin](https://github.com/jlowin) in [#917](https://github.com/PrefectHQ/fastmcp/pull/917)\n* Clean up parameter documentation by [@jlowin](https://github.com/jlowin) in [#918](https://github.com/PrefectHQ/fastmcp/pull/918)\n* 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)\n* ControlFlow → FastMCP rename by [@jlowin](https://github.com/jlowin) in [#922](https://github.com/PrefectHQ/fastmcp/pull/922)\n### Examples & Contrib 💡\n* Add contrib.mcp_mixin support for annotations by [@rsp2k](https://github.com/rsp2k) in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)\n* Add ATProto (Bluesky) MCP Server Example by [@zzstoatzz](https://github.com/zzstoatzz) in [#916](https://github.com/PrefectHQ/fastmcp/pull/916)\n* Fix path in atproto example pyproject by [@zzstoatzz](https://github.com/zzstoatzz) in [#920](https://github.com/PrefectHQ/fastmcp/pull/920)\n* Remove uv source in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#921](https://github.com/PrefectHQ/fastmcp/pull/921)\n\n## New Contributors\n* [@alexsee](https://github.com/alexsee) made their first contribution in [#838](https://github.com/PrefectHQ/fastmcp/pull/838)\n* [@zfflxx](https://github.com/zfflxx) made their first contribution in [#845](https://github.com/PrefectHQ/fastmcp/pull/845)\n* [@mkyutani](https://github.com/mkyutani) made their first contribution in [#842](https://github.com/PrefectHQ/fastmcp/pull/842)\n* [@gorocode](https://github.com/gorocode) made their first contribution in [#843](https://github.com/PrefectHQ/fastmcp/pull/843)\n* [@rsp2k](https://github.com/rsp2k) made their first contribution in [#860](https://github.com/PrefectHQ/fastmcp/pull/860)\n* [@owtaylor](https://github.com/owtaylor) made their first contribution in [#897](https://github.com/PrefectHQ/fastmcp/pull/897)\n* [@Jason-CKY](https://github.com/Jason-CKY) made their first contribution in [#906](https://github.com/PrefectHQ/fastmcp/pull/906)\n\n**Full Changelog**: [v2.8.1...v2.9.0](https://github.com/PrefectHQ/fastmcp/compare/v2.8.1...v2.9.0)\n\n\n\n\n\n## [v2.8.1: Sound Judgement](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.1)\n\n2.8.1 introduces audio support, as well as minor fixes and updates for deprecated features.\n\n### Audio Support\nThis release adds support for audio content in MCP tools and resources, expanding FastMCP's multimedia capabilities beyond text and images.\n\n## What's Changed\n### New Features 🎉\n* Add audio support by [@jlowin](https://github.com/jlowin) in [#833](https://github.com/PrefectHQ/fastmcp/pull/833)\n### Enhancements 🔧\n* Add flag for disabling deprecation warnings by [@jlowin](https://github.com/jlowin) in [#802](https://github.com/PrefectHQ/fastmcp/pull/802)\n* Add examples to Tool Arg Param transformation by [@strawgate](https://github.com/strawgate) in [#806](https://github.com/PrefectHQ/fastmcp/pull/806)\n### Fixes 🐞\n* Restore .settings access as deprecated by [@jlowin](https://github.com/jlowin) in [#800](https://github.com/PrefectHQ/fastmcp/pull/800)\n* 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)\n* Bump mcp 1.9.4 by [@jlowin](https://github.com/jlowin) in [#835](https://github.com/PrefectHQ/fastmcp/pull/835)\n### Docs 📚\n* Update changelog for 2.8.0 by [@jlowin](https://github.com/jlowin) in [#794](https://github.com/PrefectHQ/fastmcp/pull/794)\n* Update welcome docs by [@jlowin](https://github.com/jlowin) in [#808](https://github.com/PrefectHQ/fastmcp/pull/808)\n* Update headers in docs by [@jlowin](https://github.com/jlowin) in [#809](https://github.com/PrefectHQ/fastmcp/pull/809)\n* Add MCP group to tutorials by [@jlowin](https://github.com/jlowin) in [#810](https://github.com/PrefectHQ/fastmcp/pull/810)\n* Add Community section to documentation by [@zzstoatzz](https://github.com/zzstoatzz) in [#819](https://github.com/PrefectHQ/fastmcp/pull/819)\n* Add 2.8 update by [@jlowin](https://github.com/jlowin) in [#821](https://github.com/PrefectHQ/fastmcp/pull/821)\n* Embed YouTube videos in community showcase by [@zzstoatzz](https://github.com/zzstoatzz) in [#820](https://github.com/PrefectHQ/fastmcp/pull/820)\n### Other Changes 🦾\n* Ensure http args are passed through by [@jlowin](https://github.com/jlowin) in [#803](https://github.com/PrefectHQ/fastmcp/pull/803)\n* Fix install link in readme by [@jlowin](https://github.com/jlowin) in [#836](https://github.com/PrefectHQ/fastmcp/pull/836)\n\n**Full Changelog**: [v2.8.0...v2.8.1](https://github.com/PrefectHQ/fastmcp/compare/v2.8.0...v2.8.1)\n\n\n\n\n\n## [v2.8.0: Transform and Roll Out](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.8.0)\n\nFastMCP 2.8.0 introduces powerful new ways to customize and control your MCP servers! \n\n### Tool Transformation\n\nThe 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.\n\n### Component Control\nThis 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.\n\n### Tools-by-Default\nFinally, 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.\n\n## What's Changed\n### New Features 🎉\n* First-class tool transformation by [@jlowin](https://github.com/jlowin) in [#745](https://github.com/PrefectHQ/fastmcp/pull/745)\n* 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)\n* Add support for tag-based component filtering by [@jlowin](https://github.com/jlowin) in [#748](https://github.com/PrefectHQ/fastmcp/pull/748)\n* Allow tag assignments for OpenAPI by [@jlowin](https://github.com/jlowin) in [#791](https://github.com/PrefectHQ/fastmcp/pull/791)\n### Enhancements 🔧\n* Create common base class for components by [@jlowin](https://github.com/jlowin) in [#776](https://github.com/PrefectHQ/fastmcp/pull/776)\n* Move components to own file; add resource by [@jlowin](https://github.com/jlowin) in [#777](https://github.com/PrefectHQ/fastmcp/pull/777)\n* Update FastMCP component with __eq__ and __repr__ by [@jlowin](https://github.com/jlowin) in [#779](https://github.com/PrefectHQ/fastmcp/pull/779)\n* Remove open-ended and server-specific settings by [@jlowin](https://github.com/jlowin) in [#750](https://github.com/PrefectHQ/fastmcp/pull/750)\n### Fixes 🐞\n* Ensure client is only initialized once by [@jlowin](https://github.com/jlowin) in [#758](https://github.com/PrefectHQ/fastmcp/pull/758)\n* Fix field validator for resource by [@jlowin](https://github.com/jlowin) in [#778](https://github.com/PrefectHQ/fastmcp/pull/778)\n* 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)\n### Breaking Changes 🛫\n* Treat all openapi routes as tools by [@jlowin](https://github.com/jlowin) in [#788](https://github.com/PrefectHQ/fastmcp/pull/788)\n* Fix issue with global OpenAPI tags by [@jlowin](https://github.com/jlowin) in [#792](https://github.com/PrefectHQ/fastmcp/pull/792)\n### Docs 📚\n* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#755](https://github.com/PrefectHQ/fastmcp/pull/755)\n* Add 2.7 update by [@jlowin](https://github.com/jlowin) in [#756](https://github.com/PrefectHQ/fastmcp/pull/756)\n* Reduce 2.7 image size by [@jlowin](https://github.com/jlowin) in [#757](https://github.com/PrefectHQ/fastmcp/pull/757)\n* Update updates.mdx by [@jlowin](https://github.com/jlowin) in [#765](https://github.com/PrefectHQ/fastmcp/pull/765)\n* Hide docs sidebar scrollbar by default by [@jlowin](https://github.com/jlowin) in [#766](https://github.com/PrefectHQ/fastmcp/pull/766)\n* Add \"stop vibe testing\" to tutorials by [@jlowin](https://github.com/jlowin) in [#767](https://github.com/PrefectHQ/fastmcp/pull/767)\n* Add docs links by [@jlowin](https://github.com/jlowin) in [#768](https://github.com/PrefectHQ/fastmcp/pull/768)\n* Fix: updated variable name under Gemini remote client by [@yrangana](https://github.com/yrangana) in [#769](https://github.com/PrefectHQ/fastmcp/pull/769)\n* Revert \"Hide docs sidebar scrollbar by default\" by [@jlowin](https://github.com/jlowin) in [#770](https://github.com/PrefectHQ/fastmcp/pull/770)\n* Add updates by [@jlowin](https://github.com/jlowin) in [#773](https://github.com/PrefectHQ/fastmcp/pull/773)\n* Add tutorials by [@jlowin](https://github.com/jlowin) in [#783](https://github.com/PrefectHQ/fastmcp/pull/783)\n* Update LLM-friendly docs by [@jlowin](https://github.com/jlowin) in [#784](https://github.com/PrefectHQ/fastmcp/pull/784)\n* Update oauth.mdx by [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)\n* Add changelog by [@jlowin](https://github.com/jlowin) in [#789](https://github.com/PrefectHQ/fastmcp/pull/789)\n* Add tutorials by [@jlowin](https://github.com/jlowin) in [#790](https://github.com/PrefectHQ/fastmcp/pull/790)\n* Add docs for tag-based filtering by [@jlowin](https://github.com/jlowin) in [#793](https://github.com/PrefectHQ/fastmcp/pull/793)\n### Other Changes 🦾\n* Create dependabot.yml by [@jlowin](https://github.com/jlowin) in [#759](https://github.com/PrefectHQ/fastmcp/pull/759)\n* Bump astral-sh/setup-uv from 3 to 6 by [@dependabot](https://github.com/dependabot) in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)\n* Add dependencies section to release by [@jlowin](https://github.com/jlowin) in [#761](https://github.com/PrefectHQ/fastmcp/pull/761)\n* Remove extra imports for MCPConfig by [@Maanas-Verma](https://github.com/Maanas-Verma) in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)\n* Split out enhancements in release notes by [@jlowin](https://github.com/jlowin) in [#764](https://github.com/PrefectHQ/fastmcp/pull/764)\n\n## New Contributors\n* [@dependabot](https://github.com/dependabot) made their first contribution in [#760](https://github.com/PrefectHQ/fastmcp/pull/760)\n* [@Maanas-Verma](https://github.com/Maanas-Verma) made their first contribution in [#763](https://github.com/PrefectHQ/fastmcp/pull/763)\n* [@JeremyCraigMartinez](https://github.com/JeremyCraigMartinez) made their first contribution in [#787](https://github.com/PrefectHQ/fastmcp/pull/787)\n\n**Full Changelog**: [v2.7.1...v2.8.0](https://github.com/PrefectHQ/fastmcp/compare/v2.7.1...v2.8.0)\n\n\n\n\n\n## [v2.7.1: The Bearer Necessities](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.1)\n\nThis release primarily contains a fix for parsing string tokens that are provided to FastMCP clients.\n\n### New Features 🎉\n\n* Respect cache setting, set default to 1 second by [@jlowin](https://github.com/jlowin) in [#747](https://github.com/PrefectHQ/fastmcp/pull/747)\n\n### Fixes 🐞\n\n* Ensure event store is properly typed by [@jlowin](https://github.com/jlowin) in [#753](https://github.com/PrefectHQ/fastmcp/pull/753)\n* 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)\n\n### Docs 📚\n\n* Docs : fix client to mcp\\_client in Gemini example by [@yrangana](https://github.com/yrangana) in [#734](https://github.com/PrefectHQ/fastmcp/pull/734)\n* update add tool docstring by [@strawgate](https://github.com/strawgate) in [#739](https://github.com/PrefectHQ/fastmcp/pull/739)\n* Fix contrib link by [@richardkmichael](https://github.com/richardkmichael) in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)\n\n### Other Changes 🦾\n\n* Switch Pydantic defaults to kwargs by [@strawgate](https://github.com/strawgate) in [#731](https://github.com/PrefectHQ/fastmcp/pull/731)\n* Fix Typo in CLI module by [@wfclark5](https://github.com/wfclark5) in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)\n* chore: fix prompt docstring by [@danb27](https://github.com/danb27) in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)\n* Add accept to excluded headers by [@jlowin](https://github.com/jlowin) in [#751](https://github.com/PrefectHQ/fastmcp/pull/751)\n\n### New Contributors\n\n* [@wfclark5](https://github.com/wfclark5) made their first contribution in [#737](https://github.com/PrefectHQ/fastmcp/pull/737)\n* [@richardkmichael](https://github.com/richardkmichael) made their first contribution in [#749](https://github.com/PrefectHQ/fastmcp/pull/749)\n* [@danb27](https://github.com/danb27) made their first contribution in [#752](https://github.com/PrefectHQ/fastmcp/pull/752)\n\n**Full Changelog**: [v2.7.0...v2.7.1](https://github.com/PrefectHQ/fastmcp/compare/v2.7.0...v2.7.1)\n\n\n\n\n## [v2.7.0: Pare Programming](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.7.0)\n\nThis 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.\n\n### Breaking Changes 🛫\n\n* decorators return the objects they create, not the decorated function\n* websockets is an optional dependency\n* methods on the server for automatically converting functions into tools/resources/prompts have been deprecated in favor of using the decorators directly\n\n### New Features 🎉\n\n* allow passing flags to servers by [@zzstoatzz](https://github.com/zzstoatzz) in [#690](https://github.com/PrefectHQ/fastmcp/pull/690)\n* replace $ref pointing to `#/components/schemas/` with `#/$defs/` by [@phateffect](https://github.com/phateffect) in [#697](https://github.com/PrefectHQ/fastmcp/pull/697)\n* Split Tool into Tool and FunctionTool by [@jlowin](https://github.com/jlowin) in [#700](https://github.com/PrefectHQ/fastmcp/pull/700)\n* Use strict basemodel for Prompt; relax from\\_function deprecation by [@jlowin](https://github.com/jlowin) in [#701](https://github.com/PrefectHQ/fastmcp/pull/701)\n* Formalize resource/functionresource replationship by [@jlowin](https://github.com/jlowin) in [#702](https://github.com/PrefectHQ/fastmcp/pull/702)\n* Formalize template/functiontemplate split by [@jlowin](https://github.com/jlowin) in [#703](https://github.com/PrefectHQ/fastmcp/pull/703)\n* Support flexible @tool decorator call patterns by [@jlowin](https://github.com/jlowin) in [#706](https://github.com/PrefectHQ/fastmcp/pull/706)\n* Ensure deprecation warnings have stacklevel=2 by [@jlowin](https://github.com/jlowin) in [#710](https://github.com/PrefectHQ/fastmcp/pull/710)\n* Allow naked prompt decorator by [@jlowin](https://github.com/jlowin) in [#711](https://github.com/PrefectHQ/fastmcp/pull/711)\n\n### Fixes 🐞\n\n* Updates / Fixes for Tool Content Conversion by [@strawgate](https://github.com/strawgate) in [#642](https://github.com/PrefectHQ/fastmcp/pull/642)\n* Fix pr labeler permissions by [@jlowin](https://github.com/jlowin) in [#708](https://github.com/PrefectHQ/fastmcp/pull/708)\n* remove -n auto by [@jlowin](https://github.com/jlowin) in [#709](https://github.com/PrefectHQ/fastmcp/pull/709)\n* Fix links in README.md by [@alainivars](https://github.com/alainivars) in [#723](https://github.com/PrefectHQ/fastmcp/pull/723)\n\nHappily, this release DOES permit the use of \"naked\" decorators to align with Pythonic practice:\n\n```python\n@mcp.tool\ndef my_tool():\n ...\n```\n\n**Full Changelog**: [v2.6.2...v2.7.0](https://github.com/PrefectHQ/fastmcp/compare/v2.6.2...v2.7.0)\n\n\n\n\n## [v2.6.1: Blast Auth (second ignition)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.1)\n\nThis is a patch release to restore py.typed in #686.\n\n### Docs 📚\n\n* Update readme by [@jlowin](https://github.com/jlowin) in [#679](https://github.com/PrefectHQ/fastmcp/pull/679)\n* Add gemini tutorial by [@jlowin](https://github.com/jlowin) in [#680](https://github.com/PrefectHQ/fastmcp/pull/680)\n* Fix : fix path error to CLI Documentation by [@yrangana](https://github.com/yrangana) in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)\n* Update auth docs by [@jlowin](https://github.com/jlowin) in [#687](https://github.com/PrefectHQ/fastmcp/pull/687)\n\n### Other Changes 🦾\n\n* Remove deprecation notice by [@jlowin](https://github.com/jlowin) in [#677](https://github.com/PrefectHQ/fastmcp/pull/677)\n* Delete server.py by [@jlowin](https://github.com/jlowin) in [#681](https://github.com/PrefectHQ/fastmcp/pull/681)\n* Restore py.typed by [@jlowin](https://github.com/jlowin) in [#686](https://github.com/PrefectHQ/fastmcp/pull/686)\n\n### New Contributors\n\n* [@yrangana](https://github.com/yrangana) made their first contribution in [#684](https://github.com/PrefectHQ/fastmcp/pull/684)\n\n**Full Changelog**: [v2.6.0...v2.6.1](https://github.com/PrefectHQ/fastmcp/compare/v2.6.0...v2.6.1)\n\n\n\n\n## [v2.6.0: Blast Auth](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.6.0)\n\n### New Features 🎉\n\n* Introduce MCP client oauth flow by [@jlowin](https://github.com/jlowin) in [#478](https://github.com/PrefectHQ/fastmcp/pull/478)\n* Support providing tools at init by [@jlowin](https://github.com/jlowin) in [#647](https://github.com/PrefectHQ/fastmcp/pull/647)\n* Simplify code for running servers in processes during tests by [@jlowin](https://github.com/jlowin) in [#649](https://github.com/PrefectHQ/fastmcp/pull/649)\n* Add basic bearer auth for server and client by [@jlowin](https://github.com/jlowin) in [#650](https://github.com/PrefectHQ/fastmcp/pull/650)\n* Support configuring bearer auth from env vars by [@jlowin](https://github.com/jlowin) in [#652](https://github.com/PrefectHQ/fastmcp/pull/652)\n* 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)\n* Add docs for server + client auth by [@jlowin](https://github.com/jlowin) in [#655](https://github.com/PrefectHQ/fastmcp/pull/655)\n\n### Fixes 🐞\n\n* fix: Support concurrency in FastMcpProxy (and Client) by [@Sillocan](https://github.com/Sillocan) in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)\n* Ensure Client.close() cleans up client context appropriately by [@jlowin](https://github.com/jlowin) in [#643](https://github.com/PrefectHQ/fastmcp/pull/643)\n* Update client.mdx: ClientError namespace by [@mjkaye](https://github.com/mjkaye) in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)\n\n### Docs 📚\n\n* 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)\n* Document exclude\\_args by [@jlowin](https://github.com/jlowin) in [#653](https://github.com/PrefectHQ/fastmcp/pull/653)\n* Update welcome by [@jlowin](https://github.com/jlowin) in [#673](https://github.com/PrefectHQ/fastmcp/pull/673)\n* Add Anthropic + Claude desktop integration guides by [@jlowin](https://github.com/jlowin) in [#674](https://github.com/PrefectHQ/fastmcp/pull/674)\n* Minor docs design updates by [@jlowin](https://github.com/jlowin) in [#676](https://github.com/PrefectHQ/fastmcp/pull/676)\n\n### Other Changes 🦾\n\n* Update test typing by [@jlowin](https://github.com/jlowin) in [#646](https://github.com/PrefectHQ/fastmcp/pull/646)\n* Add OpenAI integration docs by [@jlowin](https://github.com/jlowin) in [#660](https://github.com/PrefectHQ/fastmcp/pull/660)\n\n### New Contributors\n\n* [@Sillocan](https://github.com/Sillocan) made their first contribution in [#635](https://github.com/PrefectHQ/fastmcp/pull/635)\n* [@deepak-stratforge](https://github.com/deepak-stratforge) made their first contribution in [#626](https://github.com/PrefectHQ/fastmcp/pull/626)\n* [@mjkaye](https://github.com/mjkaye) made their first contribution in [#657](https://github.com/PrefectHQ/fastmcp/pull/657)\n\n**Full Changelog**: [v2.5.2...v2.6.0](https://github.com/PrefectHQ/fastmcp/compare/v2.5.2...v2.6.0)\n\n\n\n\n## [v2.5.2: Stayin' Alive](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.2)\n\n### New Features 🎉\n\n* Add graceful error handling for unreachable mounted servers by [@davenpi](https://github.com/davenpi) in [#605](https://github.com/PrefectHQ/fastmcp/pull/605)\n* Improve type inference from client transport by [@jlowin](https://github.com/jlowin) in [#623](https://github.com/PrefectHQ/fastmcp/pull/623)\n* Add keep\\_alive param to reuse subprocess by [@jlowin](https://github.com/jlowin) in [#624](https://github.com/PrefectHQ/fastmcp/pull/624)\n\n### Fixes 🐞\n\n* Fix handling tools without descriptions by [@jlowin](https://github.com/jlowin) in [#610](https://github.com/PrefectHQ/fastmcp/pull/610)\n* 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)\n* 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)\n\n### Docs 📚\n\n* Add notes about uv and claude desktop by [@jlowin](https://github.com/jlowin) in [#597](https://github.com/PrefectHQ/fastmcp/pull/597)\n\n### Other Changes 🦾\n\n* add init\\_timeout for mcp client by [@jfouret](https://github.com/jfouret) in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)\n* Add init\\_timeout for mcp client (incl settings) by [@jlowin](https://github.com/jlowin) in [#609](https://github.com/PrefectHQ/fastmcp/pull/609)\n* Support for uppercase letters at the log level by [@ksawaray](https://github.com/ksawaray) in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)\n\n### New Contributors\n\n* [@jfouret](https://github.com/jfouret) made their first contribution in [#607](https://github.com/PrefectHQ/fastmcp/pull/607)\n* [@ksawaray](https://github.com/ksawaray) made their first contribution in [#625](https://github.com/PrefectHQ/fastmcp/pull/625)\n\n**Full Changelog**: [v2.5.1...v2.5.2](https://github.com/PrefectHQ/fastmcp/compare/v2.5.1...v2.5.2)\n\n\n\n\n## [v2.5.1: Route Awakening (Part 2)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.1)\n\n### Fixes 🐞\n\n* Ensure content-length is always stripped from client headers by [@jlowin](https://github.com/jlowin) in [#589](https://github.com/PrefectHQ/fastmcp/pull/589)\n\n### Docs 📚\n\n* Fix redundant section of docs by [@jlowin](https://github.com/jlowin) in [#583](https://github.com/PrefectHQ/fastmcp/pull/583)\n\n**Full Changelog**: [v2.5.0...v2.5.1](https://github.com/PrefectHQ/fastmcp/compare/v2.5.0...v2.5.1)\n\n\n\n\n## [v2.5.0: Route Awakening](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.5.0)\n\nThis 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.\n\n### New Features 🎉\n\n* 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)\n* 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)\n* 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)\n* 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)\n* Ensure custom routes are respected by [@jlowin](https://github.com/jlowin) in [#558](https://github.com/PrefectHQ/fastmcp/pull/558)\n* Add client method to send cancellation notifications by [@davenpi](https://github.com/davenpi) in [#563](https://github.com/PrefectHQ/fastmcp/pull/563)\n* Enhance route map logic for include/exclude OpenAPI routes by [@jlowin](https://github.com/jlowin) in [#564](https://github.com/PrefectHQ/fastmcp/pull/564)\n* Add tag-based route maps by [@jlowin](https://github.com/jlowin) in [#565](https://github.com/PrefectHQ/fastmcp/pull/565)\n* Add advanced control of openAPI route creation by [@jlowin](https://github.com/jlowin) in [#566](https://github.com/PrefectHQ/fastmcp/pull/566)\n* Make error masking configurable by [@jlowin](https://github.com/jlowin) in [#550](https://github.com/PrefectHQ/fastmcp/pull/550)\n* Ensure client headers are passed through to remote servers by [@jlowin](https://github.com/jlowin) in [#575](https://github.com/PrefectHQ/fastmcp/pull/575)\n* Use lowercase name for headers when comparing by [@jlowin](https://github.com/jlowin) in [#576](https://github.com/PrefectHQ/fastmcp/pull/576)\n* Permit more flexible name generation for OpenAPI servers by [@jlowin](https://github.com/jlowin) in [#578](https://github.com/PrefectHQ/fastmcp/pull/578)\n* 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)\n\n### Docs 📚\n\n* Add version badge for prefix formats by [@jlowin](https://github.com/jlowin) in [#537](https://github.com/PrefectHQ/fastmcp/pull/537)\n* Add versioning note to docs by [@jlowin](https://github.com/jlowin) in [#551](https://github.com/PrefectHQ/fastmcp/pull/551)\n* Bump 2.3.6 references to 2.4.0 by [@jlowin](https://github.com/jlowin) in [#567](https://github.com/PrefectHQ/fastmcp/pull/567)\n\n**Full Changelog**: [v2.4.0...v2.5.0](https://github.com/PrefectHQ/fastmcp/compare/v2.4.0...v2.5.0)\n\n\n\n\n## [v2.4.0: Config and Conquer](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.4.0)\n\n**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.\n\n### New Features 🎉\n\n* Allow \\* Methods and all routes as tools shortcuts by [@jlowin](https://github.com/jlowin) in [#520](https://github.com/PrefectHQ/fastmcp/pull/520)\n* Improved support for config dicts by [@jlowin](https://github.com/jlowin) in [#522](https://github.com/PrefectHQ/fastmcp/pull/522)\n* 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)\n* Make resource prefix format configurable by [@jlowin](https://github.com/jlowin) in [#534](https://github.com/PrefectHQ/fastmcp/pull/534)\n\n### Fixes 🐞\n\n* Avoid hanging on initializing server session by [@jlowin](https://github.com/jlowin) in [#523](https://github.com/PrefectHQ/fastmcp/pull/523)\n\n### Breaking Changes 🛫\n\n* Remove customizable separators; improve resource separator by [@jlowin](https://github.com/jlowin) in [#526](https://github.com/PrefectHQ/fastmcp/pull/526)\n\n### Docs 📚\n\n* Improve client documentation by [@jlowin](https://github.com/jlowin) in [#517](https://github.com/PrefectHQ/fastmcp/pull/517)\n\n### Other Changes 🦾\n\n* Ensure openapi path params are handled properly by [@jlowin](https://github.com/jlowin) in [#519](https://github.com/PrefectHQ/fastmcp/pull/519)\n* better error when missing lifespan by [@zzstoatzz](https://github.com/zzstoatzz) in [#521](https://github.com/PrefectHQ/fastmcp/pull/521)\n\n**Full Changelog**: [v2.3.5...v2.4.0](https://github.com/PrefectHQ/fastmcp/compare/v2.3.5...v2.4.0)\n\n\n\n\n## [v2.3.5: Making Progress](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.5)\n\n### New Features 🎉\n\n* support messages in progress notifications by [@rickygenhealth](https://github.com/rickygenhealth) in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)\n* feat: Add middleware option in server.run by [@Maxi91f](https://github.com/Maxi91f) in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)\n* Add lifespan property to app by [@jlowin](https://github.com/jlowin) in [#483](https://github.com/PrefectHQ/fastmcp/pull/483)\n* Update `fastmcp run` to work with remote servers by [@jlowin](https://github.com/jlowin) in [#491](https://github.com/PrefectHQ/fastmcp/pull/491)\n* Add FastMCP.as\\_proxy() by [@jlowin](https://github.com/jlowin) in [#490](https://github.com/PrefectHQ/fastmcp/pull/490)\n* Infer sse transport from urls containing /sse by [@jlowin](https://github.com/jlowin) in [#512](https://github.com/PrefectHQ/fastmcp/pull/512)\n* Add progress handler to client by [@jlowin](https://github.com/jlowin) in [#513](https://github.com/PrefectHQ/fastmcp/pull/513)\n* Store the initialize result on the client by [@jlowin](https://github.com/jlowin) in [#509](https://github.com/PrefectHQ/fastmcp/pull/509)\n\n### Fixes 🐞\n\n* Remove patch and use upstream SSEServerTransport by [@jlowin](https://github.com/jlowin) in [#425](https://github.com/PrefectHQ/fastmcp/pull/425)\n\n### Docs 📚\n\n* Update transport docs by [@jlowin](https://github.com/jlowin) in [#458](https://github.com/PrefectHQ/fastmcp/pull/458)\n* update proxy docs + example by [@zzstoatzz](https://github.com/zzstoatzz) in [#460](https://github.com/PrefectHQ/fastmcp/pull/460)\n* doc(asgi): Change custom route example to PlainTextResponse by [@mcw0933](https://github.com/mcw0933) in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)\n* Store FastMCP instance on app.state.fastmcp\\_server by [@jlowin](https://github.com/jlowin) in [#489](https://github.com/PrefectHQ/fastmcp/pull/489)\n* Improve AGENTS.md overview by [@jlowin](https://github.com/jlowin) in [#492](https://github.com/PrefectHQ/fastmcp/pull/492)\n* Update release numbers for anticipated version by [@jlowin](https://github.com/jlowin) in [#516](https://github.com/PrefectHQ/fastmcp/pull/516)\n\n### Other Changes 🦾\n\n* run tests on all PRs by [@jlowin](https://github.com/jlowin) in [#468](https://github.com/PrefectHQ/fastmcp/pull/468)\n* add null check by [@zzstoatzz](https://github.com/zzstoatzz) in [#473](https://github.com/PrefectHQ/fastmcp/pull/473)\n* strict typing for `server.py` by [@zzstoatzz](https://github.com/zzstoatzz) in [#476](https://github.com/PrefectHQ/fastmcp/pull/476)\n* Doc(quickstart): Fix import statements by [@mai-nakagawa](https://github.com/mai-nakagawa) in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)\n* Add labeler by [@jlowin](https://github.com/jlowin) in [#484](https://github.com/PrefectHQ/fastmcp/pull/484)\n* Fix flaky timeout test by increasing timeout (#474) by [@davenpi](https://github.com/davenpi) in [#486](https://github.com/PrefectHQ/fastmcp/pull/486)\n* Skipping `test_permission_error` if runner is root. by [@ZiadAmerr](https://github.com/ZiadAmerr) in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)\n* allow passing full uvicorn config by [@zzstoatzz](https://github.com/zzstoatzz) in [#504](https://github.com/PrefectHQ/fastmcp/pull/504)\n* Skip timeout tests on windows by [@jlowin](https://github.com/jlowin) in [#514](https://github.com/PrefectHQ/fastmcp/pull/514)\n\n### New Contributors\n\n* [@rickygenhealth](https://github.com/rickygenhealth) made their first contribution in [#471](https://github.com/PrefectHQ/fastmcp/pull/471)\n* [@Maxi91f](https://github.com/Maxi91f) made their first contribution in [#475](https://github.com/PrefectHQ/fastmcp/pull/475)\n* [@mcw0933](https://github.com/mcw0933) made their first contribution in [#477](https://github.com/PrefectHQ/fastmcp/pull/477)\n* [@mai-nakagawa](https://github.com/mai-nakagawa) made their first contribution in [#479](https://github.com/PrefectHQ/fastmcp/pull/479)\n* [@ZiadAmerr](https://github.com/ZiadAmerr) made their first contribution in [#502](https://github.com/PrefectHQ/fastmcp/pull/502)\n\n**Full Changelog**: [v2.3.4...v2.3.5](https://github.com/PrefectHQ/fastmcp/compare/v2.3.4...v2.3.5)\n\n\n\n\n## [v2.3.4: Error Today, Gone Tomorrow](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.4)\n\n### New Features 🎉\n\n* logging stack trace for easier debugging by [@jbkoh](https://github.com/jbkoh) in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)\n* add missing StreamableHttpTransport in client exports by [@yihuang](https://github.com/yihuang) in [#408](https://github.com/PrefectHQ/fastmcp/pull/408)\n* Improve error handling for tools and resources by [@jlowin](https://github.com/jlowin) in [#434](https://github.com/PrefectHQ/fastmcp/pull/434)\n* feat: add support for removing tools from server by [@davenpi](https://github.com/davenpi) in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)\n* Prune titles from JSONSchemas by [@jlowin](https://github.com/jlowin) in [#449](https://github.com/PrefectHQ/fastmcp/pull/449)\n* Declare toolsChanged capability for stdio server. by [@davenpi](https://github.com/davenpi) in [#450](https://github.com/PrefectHQ/fastmcp/pull/450)\n* Improve handling of exceptiongroups when raised in clients by [@jlowin](https://github.com/jlowin) in [#452](https://github.com/PrefectHQ/fastmcp/pull/452)\n* Add timeout support to client by [@jlowin](https://github.com/jlowin) in [#455](https://github.com/PrefectHQ/fastmcp/pull/455)\n\n### Fixes 🐞\n\n* 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)\n* Add reprs for OpenAPI objects by [@jlowin](https://github.com/jlowin) in [#447](https://github.com/PrefectHQ/fastmcp/pull/447)\n* Ensure openapi defs for structured objects are loaded properly by [@jlowin](https://github.com/jlowin) in [#448](https://github.com/PrefectHQ/fastmcp/pull/448)\n* Ensure tests run against correct python version by [@jlowin](https://github.com/jlowin) in [#454](https://github.com/PrefectHQ/fastmcp/pull/454)\n* 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)\n\n### Docs 📚\n\n* Add documentation for tool removal by [@jlowin](https://github.com/jlowin) in [#440](https://github.com/PrefectHQ/fastmcp/pull/440)\n\n### Other Changes 🦾\n\n* Deprecate passing settings to the FastMCP instance by [@jlowin](https://github.com/jlowin) in [#424](https://github.com/PrefectHQ/fastmcp/pull/424)\n* Add path prefix to test by [@jlowin](https://github.com/jlowin) in [#432](https://github.com/PrefectHQ/fastmcp/pull/432)\n\n### New Contributors\n\n* [@jbkoh](https://github.com/jbkoh) made their first contribution in [#413](https://github.com/PrefectHQ/fastmcp/pull/413)\n* [@davenpi](https://github.com/davenpi) made their first contribution in [#437](https://github.com/PrefectHQ/fastmcp/pull/437)\n\n**Full Changelog**: [v2.3.3...v2.3.4](https://github.com/PrefectHQ/fastmcp/compare/v2.3.3...v2.3.4)\n\n\n\n\n## [v2.3.3: SSE you later](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.3)\n\nThis is a hotfix for a bug introduced in 2.3.2 that broke SSE servers\n\n### Fixes 🐞\n\n* 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)\n\n### Docs 📚\n\n* Update composition docs by [@jlowin](https://github.com/jlowin) in [#403](https://github.com/PrefectHQ/fastmcp/pull/403)\n\n### Other Changes 🦾\n\n* Add test for no prefix when importing by [@jlowin](https://github.com/jlowin) in [#404](https://github.com/PrefectHQ/fastmcp/pull/404)\n\n**Full Changelog**: [v2.3.2...v2.3.3](https://github.com/PrefectHQ/fastmcp/compare/v2.3.2...v2.3.3)\n\n\n\n\n## [v2.3.2: Stuck in the Middleware With You](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.2)\n\n### New Features 🎉\n\n* Allow users to pass middleware to starlette app constructors by [@jlowin](https://github.com/jlowin) in [#398](https://github.com/PrefectHQ/fastmcp/pull/398)\n* Deprecate transport-specific methods on FastMCP server by [@jlowin](https://github.com/jlowin) in [#401](https://github.com/PrefectHQ/fastmcp/pull/401)\n\n### Docs 📚\n\n* Update CLI docs by [@jlowin](https://github.com/jlowin) in [#402](https://github.com/PrefectHQ/fastmcp/pull/402)\n\n### Other Changes 🦾\n\n* Adding 23 tests for CLI by [@didier-durand](https://github.com/didier-durand) in [#394](https://github.com/PrefectHQ/fastmcp/pull/394)\n\n**Full Changelog**: [v2.3.1...v2.3.2](https://github.com/PrefectHQ/fastmcp/compare/v2.3.1...v2.3.2)\n\n\n\n\n## [v2.3.1: For Good-nests Sake](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.1)\n\nThis release primarily patches a long-standing bug with nested ASGI SSE servers.\n\n### Fixes 🐞\n\n* 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)\n* 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)\n\n### Docs 📚\n\n* Update transport docs by [@jlowin](https://github.com/jlowin) in [#377](https://github.com/PrefectHQ/fastmcp/pull/377)\n* Add llms.txt to docs by [@jlowin](https://github.com/jlowin) in [#384](https://github.com/PrefectHQ/fastmcp/pull/384)\n* Fixing various text typos by [@didier-durand](https://github.com/didier-durand) in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)\n\n### Other Changes 🦾\n\n* Adding a few tests to Image type by [@didier-durand](https://github.com/didier-durand) in [#387](https://github.com/PrefectHQ/fastmcp/pull/387)\n* Adding tests for TimedCache by [@didier-durand](https://github.com/didier-durand) in [#388](https://github.com/PrefectHQ/fastmcp/pull/388)\n\n### New Contributors\n\n* [@didier-durand](https://github.com/didier-durand) made their first contribution in [#385](https://github.com/PrefectHQ/fastmcp/pull/385)\n\n**Full Changelog**: [v2.3.0...v2.3.1](https://github.com/PrefectHQ/fastmcp/compare/v2.3.0...v2.3.1)\n\n\n\n\n## [v2.3.0: Stream Me Up, Scotty](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.3.0)\n\n### New Features 🎉\n\n* Add streaming support for HTTP transport by [@jlowin](https://github.com/jlowin) in [#365](https://github.com/PrefectHQ/fastmcp/pull/365)\n* Support streaming HTTP transport in clients by [@jlowin](https://github.com/jlowin) in [#366](https://github.com/PrefectHQ/fastmcp/pull/366)\n* Add streaming support to CLI by [@jlowin](https://github.com/jlowin) in [#367](https://github.com/PrefectHQ/fastmcp/pull/367)\n\n### Fixes 🐞\n\n* Fix streaming transport initialization by [@jlowin](https://github.com/jlowin) in [#368](https://github.com/PrefectHQ/fastmcp/pull/368)\n\n### Docs 📚\n\n* Update transport documentation for streaming support by [@jlowin](https://github.com/jlowin) in [#369](https://github.com/PrefectHQ/fastmcp/pull/369)\n\n**Full Changelog**: [v2.2.10...v2.3.0](https://github.com/PrefectHQ/fastmcp/compare/v2.2.10...v2.3.0)\n\n\n\n\n## [v2.2.10: That's JSON Bourne](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.10)\n\n### Fixes 🐞\n\n* Disable automatic JSON parsing of tool args by [@jlowin](https://github.com/jlowin) in [#341](https://github.com/PrefectHQ/fastmcp/pull/341)\n* Fix prompt test by [@jlowin](https://github.com/jlowin) in [#342](https://github.com/PrefectHQ/fastmcp/pull/342)\n\n### Other Changes 🦾\n\n* Update docs.json by [@jlowin](https://github.com/jlowin) in [#338](https://github.com/PrefectHQ/fastmcp/pull/338)\n* Add test coverage + tests on 4 examples by [@alainivars](https://github.com/alainivars) in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)\n\n### New Contributors\n\n* [@alainivars](https://github.com/alainivars) made their first contribution in [#306](https://github.com/PrefectHQ/fastmcp/pull/306)\n\n**Full Changelog**: [v2.2.9...v2.2.10](https://github.com/PrefectHQ/fastmcp/compare/v2.2.9...v2.2.10)\n\n\n\n\n## [v2.2.9: Str-ing the Pot (Hotfix)](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.9)\n\nThis release is a hotfix for the issue detailed in #330\n\n### Fixes 🐞\n\n* Prevent invalid resource URIs by [@jlowin](https://github.com/jlowin) in [#336](https://github.com/PrefectHQ/fastmcp/pull/336)\n* Coerce numbers to str by [@jlowin](https://github.com/jlowin) in [#337](https://github.com/PrefectHQ/fastmcp/pull/337)\n\n### Docs 📚\n\n* Add client badge by [@jlowin](https://github.com/jlowin) in [#327](https://github.com/PrefectHQ/fastmcp/pull/327)\n* Update bug.yml by [@jlowin](https://github.com/jlowin) in [#328](https://github.com/PrefectHQ/fastmcp/pull/328)\n\n### Other Changes 🦾\n\n* Update quickstart.mdx example to include import by [@discdiver](https://github.com/discdiver) in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)\n\n### New Contributors\n\n* [@discdiver](https://github.com/discdiver) made their first contribution in [#329](https://github.com/PrefectHQ/fastmcp/pull/329)\n\n**Full Changelog**: [v2.2.8...v2.2.9](https://github.com/PrefectHQ/fastmcp/compare/v2.2.8...v2.2.9)\n\n\n\n\n## [v2.2.8: Parse and Recreation](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.8)\n\n### New Features 🎉\n\n* Replace custom parsing with TypeAdapter by [@jlowin](https://github.com/jlowin) in [#314](https://github.com/PrefectHQ/fastmcp/pull/314)\n* Handle \\*args/\\*\\*kwargs appropriately for various components by [@jlowin](https://github.com/jlowin) in [#317](https://github.com/PrefectHQ/fastmcp/pull/317)\n* 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)\n* Ensure prompts return descriptions by [@jlowin](https://github.com/jlowin) in [#325](https://github.com/PrefectHQ/fastmcp/pull/325)\n\n### Fixes 🐞\n\n* Ensure that tool serialization has a graceful fallback by [@jlowin](https://github.com/jlowin) in [#310](https://github.com/PrefectHQ/fastmcp/pull/310)\n\n### Docs 📚\n\n* Update docs for clarity by [@jlowin](https://github.com/jlowin) in [#312](https://github.com/PrefectHQ/fastmcp/pull/312)\n\n### Other Changes 🦾\n\n* Remove is\\_async attribute by [@jlowin](https://github.com/jlowin) in [#315](https://github.com/PrefectHQ/fastmcp/pull/315)\n* Dry out retrieving context kwarg by [@jlowin](https://github.com/jlowin) in [#316](https://github.com/PrefectHQ/fastmcp/pull/316)\n\n**Full Changelog**: [v2.2.7...v2.2.8](https://github.com/PrefectHQ/fastmcp/compare/v2.2.7...v2.2.8)\n\n\n\n\n## [v2.2.7: You Auth to Know Better](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.7)\n\n### New Features 🎉\n\n* use pydantic\\_core.to\\_json by [@jlowin](https://github.com/jlowin) in [#290](https://github.com/PrefectHQ/fastmcp/pull/290)\n* Ensure openapi descriptions are included in tool details by [@jlowin](https://github.com/jlowin) in [#293](https://github.com/PrefectHQ/fastmcp/pull/293)\n* Bump mcp to 1.7.1 by [@jlowin](https://github.com/jlowin) in [#298](https://github.com/PrefectHQ/fastmcp/pull/298)\n* Add support for tool annotations by [@jlowin](https://github.com/jlowin) in [#299](https://github.com/PrefectHQ/fastmcp/pull/299)\n* Add auth support by [@jlowin](https://github.com/jlowin) in [#300](https://github.com/PrefectHQ/fastmcp/pull/300)\n* Add low-level methods to client by [@jlowin](https://github.com/jlowin) in [#301](https://github.com/PrefectHQ/fastmcp/pull/301)\n* 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)\n* get\\_starlette\\_request → get\\_http\\_request by [@jlowin](https://github.com/jlowin) in [#303](https://github.com/PrefectHQ/fastmcp/pull/303)\n* Support custom Serializer for Tools by [@strawgate](https://github.com/strawgate) in [#308](https://github.com/PrefectHQ/fastmcp/pull/308)\n* Support proxy mount by [@jlowin](https://github.com/jlowin) in [#309](https://github.com/PrefectHQ/fastmcp/pull/309)\n\n### Other Changes 🦾\n\n* Improve context injection type checks by [@jlowin](https://github.com/jlowin) in [#291](https://github.com/PrefectHQ/fastmcp/pull/291)\n* add readme to smarthome example by [@zzstoatzz](https://github.com/zzstoatzz) in [#294](https://github.com/PrefectHQ/fastmcp/pull/294)\n\n**Full Changelog**: [v2.2.6...v2.2.7](https://github.com/PrefectHQ/fastmcp/compare/v2.2.6...v2.2.7)\n\n\n\n\n## [v2.2.6: The REST is History](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.6)\n\n### New Features 🎉\n\n* Added feature : Load MCP server using config by [@sandipan1](https://github.com/sandipan1) in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)\n* small typing fixes by [@zzstoatzz](https://github.com/zzstoatzz) in [#237](https://github.com/PrefectHQ/fastmcp/pull/237)\n* Expose configurable timeout for OpenAPI by [@jlowin](https://github.com/jlowin) in [#279](https://github.com/PrefectHQ/fastmcp/pull/279)\n* Lower websockets pin for compatibility by [@jlowin](https://github.com/jlowin) in [#286](https://github.com/PrefectHQ/fastmcp/pull/286)\n* Improve OpenAPI param handling by [@jlowin](https://github.com/jlowin) in [#287](https://github.com/PrefectHQ/fastmcp/pull/287)\n\n### Fixes 🐞\n\n* Ensure openapi tool responses are properly converted by [@jlowin](https://github.com/jlowin) in [#283](https://github.com/PrefectHQ/fastmcp/pull/283)\n* Fix OpenAPI examples by [@jlowin](https://github.com/jlowin) in [#285](https://github.com/PrefectHQ/fastmcp/pull/285)\n* 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)\n\n### Other Changes 🦾\n\n* add testing doc by [@jlowin](https://github.com/jlowin) in [#264](https://github.com/PrefectHQ/fastmcp/pull/264)\n* #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)\n\n### New Contributors\n\n* [@sandipan1](https://github.com/sandipan1) made their first contribution in [#260](https://github.com/PrefectHQ/fastmcp/pull/260)\n* [@jeger-at](https://github.com/jeger-at) made their first contribution in [#278](https://github.com/PrefectHQ/fastmcp/pull/278)\n\n**Full Changelog**: [v2.2.5...v2.2.6](https://github.com/PrefectHQ/fastmcp/compare/v2.2.5...v2.2.6)\n\n\n\n\n## [v2.2.5: Context Switching](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.5)\n\n### New Features 🎉\n\n* Add tests for tool return types; improve serialization behavior by [@jlowin](https://github.com/jlowin) in [#262](https://github.com/PrefectHQ/fastmcp/pull/262)\n* 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)\n\n### Docs 📚\n\n* Update wildcards to 2.2.4 by [@jlowin](https://github.com/jlowin) in [#257](https://github.com/PrefectHQ/fastmcp/pull/257)\n* Update note in templates docs by [@jlowin](https://github.com/jlowin) in [#258](https://github.com/PrefectHQ/fastmcp/pull/258)\n* Significant documentation and test expansion for tool input types by [@jlowin](https://github.com/jlowin) in [#261](https://github.com/PrefectHQ/fastmcp/pull/261)\n\n**Full Changelog**: [v2.2.4...v2.2.5](https://github.com/PrefectHQ/fastmcp/compare/v2.2.4...v2.2.5)\n\n\n\n\n## [v2.2.4: The Wild Side, Actually](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.4)\n\nThe wildcard URI templates exposed in v2.2.3 were blocked by a server-level check which is removed in this release.\n\n### New Features 🎉\n\n* 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)\n\n### Fixes 🐞\n\n* fix: unintended type convert by [@cutekibry](https://github.com/cutekibry) in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)\n* Ensure openapi resources return valid responses by [@jlowin](https://github.com/jlowin) in [#254](https://github.com/PrefectHQ/fastmcp/pull/254)\n* Ensure servers expose template wildcards by [@jlowin](https://github.com/jlowin) in [#256](https://github.com/PrefectHQ/fastmcp/pull/256)\n\n### Docs 📚\n\n* Update README.md Grammar error by [@TechWithTy](https://github.com/TechWithTy) in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)\n\n### Other Changes 🦾\n\n* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#255](https://github.com/PrefectHQ/fastmcp/pull/255)\n\n### New Contributors\n\n* [@TechWithTy](https://github.com/TechWithTy) made their first contribution in [#249](https://github.com/PrefectHQ/fastmcp/pull/249)\n* [@cutekibry](https://github.com/cutekibry) made their first contribution in [#252](https://github.com/PrefectHQ/fastmcp/pull/252)\n\n**Full Changelog**: [v2.2.3...v2.2.4](https://github.com/PrefectHQ/fastmcp/compare/v2.2.3...v2.2.4)\n\n\n\n\n## [v2.2.3: The Wild Side](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.3)\n\n### New Features 🎉\n\n* Add wildcard params for resource templates by [@jlowin](https://github.com/jlowin) in [#246](https://github.com/PrefectHQ/fastmcp/pull/246)\n\n### Docs 📚\n\n* Indicate that Image class is for returns by [@jlowin](https://github.com/jlowin) in [#242](https://github.com/PrefectHQ/fastmcp/pull/242)\n* Update mermaid diagram by [@jlowin](https://github.com/jlowin) in [#243](https://github.com/PrefectHQ/fastmcp/pull/243)\n\n### Other Changes 🦾\n\n* update version badges by [@jlowin](https://github.com/jlowin) in [#248](https://github.com/PrefectHQ/fastmcp/pull/248)\n\n**Full Changelog**: [v2.2.2...v2.2.3](https://github.com/PrefectHQ/fastmcp/compare/v2.2.2...v2.2.3)\n\n\n\n\n## [v2.2.2: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.2)\n\n### New Features 🎉\n\n* Add prompt support by [@jlowin](https://github.com/jlowin) in [#235](https://github.com/PrefectHQ/fastmcp/pull/235)\n\n### Fixes 🐞\n\n* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#238](https://github.com/PrefectHQ/fastmcp/pull/238)\n\n### Docs 📚\n\n* Update docs for prompts by [@jlowin](https://github.com/jlowin) in [#236](https://github.com/PrefectHQ/fastmcp/pull/236)\n\n### Other Changes 🦾\n\n* Add prompt tests by [@jlowin](https://github.com/jlowin) in [#239](https://github.com/PrefectHQ/fastmcp/pull/239)\n\n**Full Changelog**: [v2.2.1...v2.2.2](https://github.com/PrefectHQ/fastmcp/compare/v2.2.1...v2.2.2)\n\n\n\n\n## [v2.2.1: Template for Success](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.1)\n\n### New Features 🎉\n\n* Add resource templates by [@jlowin](https://github.com/jlowin) in [#230](https://github.com/PrefectHQ/fastmcp/pull/230)\n\n### Fixes 🐞\n\n* Ensure that resource templates are properly exposed by [@jlowin](https://github.com/jlowin) in [#231](https://github.com/PrefectHQ/fastmcp/pull/231)\n\n### Docs 📚\n\n* Update docs for resource templates by [@jlowin](https://github.com/jlowin) in [#232](https://github.com/PrefectHQ/fastmcp/pull/232)\n\n### Other Changes 🦾\n\n* Add resource template tests by [@jlowin](https://github.com/jlowin) in [#233](https://github.com/PrefectHQ/fastmcp/pull/233)\n\n**Full Changelog**: [v2.2.0...v2.2.1](https://github.com/PrefectHQ/fastmcp/compare/v2.2.0...v2.2.1)\n\n\n\n\n## [v2.2.0: Compose Yourself](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.2.0)\n\n### New Features 🎉\n\n* Add support for mounting FastMCP servers by [@jlowin](https://github.com/jlowin) in [#175](https://github.com/PrefectHQ/fastmcp/pull/175)\n* Add support for duplicate behavior == ignore by [@jlowin](https://github.com/jlowin) in [#169](https://github.com/PrefectHQ/fastmcp/pull/169)\n\n### Breaking Changes 🛫\n\n* Refactor MCP composition by [@jlowin](https://github.com/jlowin) in [#176](https://github.com/PrefectHQ/fastmcp/pull/176)\n\n### Docs 📚\n\n* Improve integration documentation by [@jlowin](https://github.com/jlowin) in [#184](https://github.com/PrefectHQ/fastmcp/pull/184)\n* Improve documentation by [@jlowin](https://github.com/jlowin) in [#185](https://github.com/PrefectHQ/fastmcp/pull/185)\n\n### Other Changes 🦾\n\n* Add transport kwargs for mcp.run() and fastmcp run by [@jlowin](https://github.com/jlowin) in [#161](https://github.com/PrefectHQ/fastmcp/pull/161)\n* Allow resource templates to have optional / excluded arguments by [@jlowin](https://github.com/jlowin) in [#164](https://github.com/PrefectHQ/fastmcp/pull/164)\n* Update resources.mdx by [@jlowin](https://github.com/jlowin) in [#165](https://github.com/PrefectHQ/fastmcp/pull/165)\n\n### New Contributors\n\n* [@kongqi404](https://github.com/kongqi404) made their first contribution in [#181](https://github.com/PrefectHQ/fastmcp/pull/181)\n\n**Full Changelog**: [v2.1.2...v2.2.0](https://github.com/PrefectHQ/fastmcp/compare/v2.1.2...v2.2.0)\n\n\n\n\n## [v2.1.2: Copy That, Good Buddy](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.2)\n\nThe main improvement in this release is a fix that allows FastAPI / OpenAPI-generated servers to be mounted as sub-servers.\n\n### Fixes 🐞\n\n* Ensure objects are copied properly and test mounting fastapi by [@jlowin](https://github.com/jlowin) in [#153](https://github.com/PrefectHQ/fastmcp/pull/153)\n\n### Docs 📚\n\n* Fix broken links in docs by [@jlowin](https://github.com/jlowin) in [#154](https://github.com/PrefectHQ/fastmcp/pull/154)\n\n### Other Changes 🦾\n\n* Update README.md by [@jlowin](https://github.com/jlowin) in [#149](https://github.com/PrefectHQ/fastmcp/pull/149)\n* Only apply log config to FastMCP loggers by [@jlowin](https://github.com/jlowin) in [#155](https://github.com/PrefectHQ/fastmcp/pull/155)\n* Update pyproject.toml by [@jlowin](https://github.com/jlowin) in [#156](https://github.com/PrefectHQ/fastmcp/pull/156)\n\n**Full Changelog**: [v2.1.1...v2.1.2](https://github.com/PrefectHQ/fastmcp/compare/v2.1.1...v2.1.2)\n\n\n\n\n## [v2.1.1: Doc Holiday](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.1)\n\nFastMCP's docs are now available at gofastmcp.com.\n\n### Docs 📚\n\n* Add docs by [@jlowin](https://github.com/jlowin) in [#136](https://github.com/PrefectHQ/fastmcp/pull/136)\n* Add docs link to readme by [@jlowin](https://github.com/jlowin) in [#137](https://github.com/PrefectHQ/fastmcp/pull/137)\n* Minor docs updates by [@jlowin](https://github.com/jlowin) in [#138](https://github.com/PrefectHQ/fastmcp/pull/138)\n\n### Fixes 🐞\n\n* fix branch name in example by [@zzstoatzz](https://github.com/zzstoatzz) in [#140](https://github.com/PrefectHQ/fastmcp/pull/140)\n\n### Other Changes 🦾\n\n* smart home example by [@zzstoatzz](https://github.com/zzstoatzz) in [#115](https://github.com/PrefectHQ/fastmcp/pull/115)\n* Remove mac os tests by [@jlowin](https://github.com/jlowin) in [#142](https://github.com/PrefectHQ/fastmcp/pull/142)\n* Expand support for various method interactions by [@jlowin](https://github.com/jlowin) in [#143](https://github.com/PrefectHQ/fastmcp/pull/143)\n* Update docs and add\\_resource\\_fn by [@jlowin](https://github.com/jlowin) in [#144](https://github.com/PrefectHQ/fastmcp/pull/144)\n* Update description by [@jlowin](https://github.com/jlowin) in [#145](https://github.com/PrefectHQ/fastmcp/pull/145)\n* Support openapi 3.0 and 3.1 by [@jlowin](https://github.com/jlowin) in [#147](https://github.com/PrefectHQ/fastmcp/pull/147)\n\n**Full Changelog**: [v2.1.0...v2.1.1](https://github.com/PrefectHQ/fastmcp/compare/v2.1.0...v2.1.1)\n\n\n\n\n## [v2.1.0: Tag, You're It](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.1.0)\n\nThe 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.\n\n### New Features 🎉\n\n* Add tags for all core MCP objects by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)\n* Ensure that openapi tags are transferred to MCP objects by [@jlowin](https://github.com/jlowin) in [#124](https://github.com/PrefectHQ/fastmcp/pull/124)\n\n### Fixes 🐞\n\n* Change default mounted tool separator from / to \\_ by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)\n* Enter mounted app lifespans by [@jlowin](https://github.com/jlowin) in [#129](https://github.com/PrefectHQ/fastmcp/pull/129)\n* Fix CLI that called mcp instead of fastmcp by [@jlowin](https://github.com/jlowin) in [#128](https://github.com/PrefectHQ/fastmcp/pull/128)\n\n### Breaking Changes 🛫\n\n* Changed configuration for duplicate resources/tools/prompts by [@jlowin](https://github.com/jlowin) in [#121](https://github.com/PrefectHQ/fastmcp/pull/121)\n* Improve client return types by [@jlowin](https://github.com/jlowin) in [#123](https://github.com/PrefectHQ/fastmcp/pull/123)\n\n### Other Changes 🦾\n\n* Add tests for tags in server decorators by [@jlowin](https://github.com/jlowin) in [#122](https://github.com/PrefectHQ/fastmcp/pull/122)\n* Clean up server tests by [@jlowin](https://github.com/jlowin) in [#125](https://github.com/PrefectHQ/fastmcp/pull/125)\n\n**Full Changelog**: [v2.0.0...v2.1.0](https://github.com/PrefectHQ/fastmcp/compare/v2.0.0...v2.1.0)\n\n\n\n\n## [v2.0.0: Second to None](https://github.com/PrefectHQ/fastmcp/releases/tag/v2.0.0)\n\n### New Features 🎉\n\n* Support mounting FastMCP instances as sub-MCPs by [@jlowin](https://github.com/jlowin) in [#99](https://github.com/PrefectHQ/fastmcp/pull/99)\n* 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)\n* Add MCP proxy server by [@jlowin](https://github.com/jlowin) in [#105](https://github.com/PrefectHQ/fastmcp/pull/105)\n* Update FastMCP for upstream changes by [@jlowin](https://github.com/jlowin) in [#107](https://github.com/PrefectHQ/fastmcp/pull/107)\n* Generate FastMCP servers from OpenAPI specs and FastAPI by [@jlowin](https://github.com/jlowin) in [#110](https://github.com/PrefectHQ/fastmcp/pull/110)\n* Reorganize all client / transports by [@jlowin](https://github.com/jlowin) in [#111](https://github.com/PrefectHQ/fastmcp/pull/111)\n* Add sampling and roots by [@jlowin](https://github.com/jlowin) in [#117](https://github.com/PrefectHQ/fastmcp/pull/117)\n\n### Fixes 🐞\n\n* Fix bug with tools that return lists by [@jlowin](https://github.com/jlowin) in [#116](https://github.com/PrefectHQ/fastmcp/pull/116)\n\n### Other Changes 🦾\n\n* Add back FastMCP CLI by [@jlowin](https://github.com/jlowin) in [#108](https://github.com/PrefectHQ/fastmcp/pull/108)\n* Update Readme for v2 by [@jlowin](https://github.com/jlowin) in [#112](https://github.com/PrefectHQ/fastmcp/pull/112)\n* fix deprecation warnings by [@zzstoatzz](https://github.com/zzstoatzz) in [#113](https://github.com/PrefectHQ/fastmcp/pull/113)\n* Readme by [@jlowin](https://github.com/jlowin) in [#118](https://github.com/PrefectHQ/fastmcp/pull/118)\n* FastMCP 2.0 by [@jlowin](https://github.com/jlowin) in [#119](https://github.com/PrefectHQ/fastmcp/pull/119)\n\n**Full Changelog**: [v1.0...v2.0.0](https://github.com/PrefectHQ/fastmcp/compare/v1.0...v2.0.0)\n\n\n\n\n## [v1.0: It's Official](https://github.com/PrefectHQ/fastmcp/releases/tag/v1.0)\n\nThis release commemorates FastMCP 1.0, which is included in the official Model Context Protocol SDK:\n\n```python\nfrom mcp.server.fastmcp import FastMCP\n```\n\nTo the best of my knowledge, v1 is identical to the upstream version included with `mcp`.\n\n### Docs 📚\n\n* Update readme to redirect to the official SDK by [@jlowin](https://github.com/jlowin) in [#79](https://github.com/PrefectHQ/fastmcp/pull/79)\n\n### Other Changes 🦾\n\n* 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)\n\n### New Contributors\n\n* [@samihamine](https://github.com/samihamine) made their first contribution in [#77](https://github.com/PrefectHQ/fastmcp/pull/77)\n\n**Full Changelog**: [v0.4.1...v1.0](https://github.com/PrefectHQ/fastmcp/compare/v0.4.1...v1.0)\n\n\n\n\n## [v0.4.1: String Theory](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.1)\n\n### Fixes 🐞\n\n* fix: handle strings containing numbers correctly by [@sd2k](https://github.com/sd2k) in [#63](https://github.com/PrefectHQ/fastmcp/pull/63)\n\n### Docs 📚\n\n* patch: Update pyproject.toml license by [@leonkozlowski](https://github.com/leonkozlowski) in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)\n\n### Other Changes 🦾\n\n* Avoid new try\\_eval\\_type unavailable with older pydantic by [@jurasofish](https://github.com/jurasofish) in [#57](https://github.com/PrefectHQ/fastmcp/pull/57)\n* Decorator typing by [@jurasofish](https://github.com/jurasofish) in [#56](https://github.com/PrefectHQ/fastmcp/pull/56)\n\n### New Contributors\n\n* [@leonkozlowski](https://github.com/leonkozlowski) made their first contribution in [#67](https://github.com/PrefectHQ/fastmcp/pull/67)\n\n**Full Changelog**: [v0.4.0...v0.4.1](https://github.com/PrefectHQ/fastmcp/compare/v0.4.0...v0.4.1)\n\n\n\n\n## [v0.4.0: Nice to MIT You](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.4.0)\n\nThis 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.\n\n### New Features 🎉\n\n* Add pyright + tests by [@jlowin](https://github.com/jlowin) in [#52](https://github.com/PrefectHQ/fastmcp/pull/52)\n* add pgvector memory example by [@zzstoatzz](https://github.com/zzstoatzz) in [#49](https://github.com/PrefectHQ/fastmcp/pull/49)\n\n### Fixes 🐞\n\n* fix: use stderr for logging by [@sd2k](https://github.com/sd2k) in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)\n\n### Docs 📚\n\n* Update ai-labeler.yml by [@jlowin](https://github.com/jlowin) in [#48](https://github.com/PrefectHQ/fastmcp/pull/48)\n* Relicense from Apache 2.0 to MIT by [@jlowin](https://github.com/jlowin) in [#54](https://github.com/PrefectHQ/fastmcp/pull/54)\n\n### Other Changes 🦾\n\n* fix warning and flake by [@zzstoatzz](https://github.com/zzstoatzz) in [#47](https://github.com/PrefectHQ/fastmcp/pull/47)\n\n### New Contributors\n\n* [@sd2k](https://github.com/sd2k) made their first contribution in [#51](https://github.com/PrefectHQ/fastmcp/pull/51)\n\n**Full Changelog**: [v0.3.5...v0.4.0](https://github.com/PrefectHQ/fastmcp/compare/v0.3.5...v0.4.0)\n\n\n\n\n## [v0.3.5: Windows of Opportunity](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.5)\n\nThis release is highlighted by the ability to handle complex JSON objects as MCP inputs and improved Windows compatibility.\n\n### New Features 🎉\n\n* Set up multiple os tests by [@jlowin](https://github.com/jlowin) in [#44](https://github.com/PrefectHQ/fastmcp/pull/44)\n* Changes to accommodate windows users. by [@justjoehere](https://github.com/justjoehere) in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)\n* Handle complex inputs by [@jurasofish](https://github.com/jurasofish) in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)\n\n### Docs 📚\n\n* Make AI labeler more conservative by [@jlowin](https://github.com/jlowin) in [#46](https://github.com/PrefectHQ/fastmcp/pull/46)\n\n### Other Changes 🦾\n\n* 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)\n\n### New Contributors\n\n* [@justjoehere](https://github.com/justjoehere) made their first contribution in [#42](https://github.com/PrefectHQ/fastmcp/pull/42)\n* [@jurasofish](https://github.com/jurasofish) made their first contribution in [#31](https://github.com/PrefectHQ/fastmcp/pull/31)\n\n**Full Changelog**: [v0.3.4...v0.3.5](https://github.com/PrefectHQ/fastmcp/compare/v0.3.4...v0.3.5)\n\n\n\n\n## [v0.3.4: URL's Well That Ends Well](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.4)\n\n### Fixes 🐞\n\n* Handle missing config file when installing by [@jlowin](https://github.com/jlowin) in [#37](https://github.com/PrefectHQ/fastmcp/pull/37)\n* Remove BaseURL reference and use AnyURL by [@jlowin](https://github.com/jlowin) in [#40](https://github.com/PrefectHQ/fastmcp/pull/40)\n\n**Full Changelog**: [v0.3.3...v0.3.4](https://github.com/PrefectHQ/fastmcp/compare/v0.3.3...v0.3.4)\n\n\n\n\n## [v0.3.3: Dependence Day](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.3)\n\n### New Features 🎉\n\n* Surge example by [@zzstoatzz](https://github.com/zzstoatzz) in [#29](https://github.com/PrefectHQ/fastmcp/pull/29)\n* Support Python dependencies in Server by [@jlowin](https://github.com/jlowin) in [#34](https://github.com/PrefectHQ/fastmcp/pull/34)\n\n### Docs 📚\n\n* add `Contributing` section to README by [@zzstoatzz](https://github.com/zzstoatzz) in [#32](https://github.com/PrefectHQ/fastmcp/pull/32)\n\n**Full Changelog**: [v0.3.2...v0.3.3](https://github.com/PrefectHQ/fastmcp/compare/v0.3.2...v0.3.3)\n\n\n\n\n## [v0.3.2: Green with ENVy](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.2)\n\n### New Features 🎉\n\n* Support env vars when installing by [@jlowin](https://github.com/jlowin) in [#27](https://github.com/PrefectHQ/fastmcp/pull/27)\n\n### Docs 📚\n\n* Remove top level env var by [@jlowin](https://github.com/jlowin) in [#28](https://github.com/PrefectHQ/fastmcp/pull/28)\n\n**Full Changelog**: [v0.3.1...v0.3.2](https://github.com/PrefectHQ/fastmcp/compare/v0.3.1...v0.3.2)\n\n\n\n\n## [v0.3.1](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.1)\n\n### New Features 🎉\n\n* Update README.md by [@jlowin](https://github.com/jlowin) in [#23](https://github.com/PrefectHQ/fastmcp/pull/23)\n* add rich handler and dotenv loading for settings by [@zzstoatzz](https://github.com/zzstoatzz) in [#22](https://github.com/PrefectHQ/fastmcp/pull/22)\n* print exception when server can't start by [@jlowin](https://github.com/jlowin) in [#25](https://github.com/PrefectHQ/fastmcp/pull/25)\n\n### Docs 📚\n\n* Update README.md by [@jlowin](https://github.com/jlowin) in [#24](https://github.com/PrefectHQ/fastmcp/pull/24)\n\n### Other Changes 🦾\n\n* Remove log by [@jlowin](https://github.com/jlowin) in [#26](https://github.com/PrefectHQ/fastmcp/pull/26)\n\n**Full Changelog**: [v0.3.0...v0.3.1](https://github.com/PrefectHQ/fastmcp/compare/v0.3.0...v0.3.1)\n\n\n\n\n## [v0.3.0: Prompt and Circumstance](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.3.0)\n\n### New Features 🎉\n\n* Update README by [@jlowin](https://github.com/jlowin) in [#3](https://github.com/PrefectHQ/fastmcp/pull/3)\n* Make log levels strings by [@jlowin](https://github.com/jlowin) in [#4](https://github.com/PrefectHQ/fastmcp/pull/4)\n* Make content method a function by [@jlowin](https://github.com/jlowin) in [#5](https://github.com/PrefectHQ/fastmcp/pull/5)\n* Add template support by [@jlowin](https://github.com/jlowin) in [#6](https://github.com/PrefectHQ/fastmcp/pull/6)\n* Refactor resources module by [@jlowin](https://github.com/jlowin) in [#7](https://github.com/PrefectHQ/fastmcp/pull/7)\n* Clean up cli imports by [@jlowin](https://github.com/jlowin) in [#8](https://github.com/PrefectHQ/fastmcp/pull/8)\n* Prepare to list templates by [@jlowin](https://github.com/jlowin) in [#11](https://github.com/PrefectHQ/fastmcp/pull/11)\n* Move image to separate module by [@jlowin](https://github.com/jlowin) in [#9](https://github.com/PrefectHQ/fastmcp/pull/9)\n* Add support for request context, progress, logging, etc. by [@jlowin](https://github.com/jlowin) in [#12](https://github.com/PrefectHQ/fastmcp/pull/12)\n* Add context tests and better runtime loads by [@jlowin](https://github.com/jlowin) in [#13](https://github.com/PrefectHQ/fastmcp/pull/13)\n* Refactor tools + resourcemanager by [@jlowin](https://github.com/jlowin) in [#14](https://github.com/PrefectHQ/fastmcp/pull/14)\n* func → fn everywhere by [@jlowin](https://github.com/jlowin) in [#15](https://github.com/PrefectHQ/fastmcp/pull/15)\n* Add support for prompts by [@jlowin](https://github.com/jlowin) in [#16](https://github.com/PrefectHQ/fastmcp/pull/16)\n* Create LICENSE by [@jlowin](https://github.com/jlowin) in [#18](https://github.com/PrefectHQ/fastmcp/pull/18)\n* Update cli file spec by [@jlowin](https://github.com/jlowin) in [#19](https://github.com/PrefectHQ/fastmcp/pull/19)\n* Update readmeUpdate README by [@jlowin](https://github.com/jlowin) in [#20](https://github.com/PrefectHQ/fastmcp/pull/20)\n* Use hatchling for version by [@jlowin](https://github.com/jlowin) in [#21](https://github.com/PrefectHQ/fastmcp/pull/21)\n\n### Other Changes 🦾\n\n* Add echo server by [@jlowin](https://github.com/jlowin) in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)\n* Add github workflows by [@jlowin](https://github.com/jlowin) in [#2](https://github.com/PrefectHQ/fastmcp/pull/2)\n* typing updates by [@zzstoatzz](https://github.com/zzstoatzz) in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)\n\n### New Contributors\n\n* [@jlowin](https://github.com/jlowin) made their first contribution in [#1](https://github.com/PrefectHQ/fastmcp/pull/1)\n* [@zzstoatzz](https://github.com/zzstoatzz) made their first contribution in [#17](https://github.com/PrefectHQ/fastmcp/pull/17)\n\n**Full Changelog**: [v0.2.0...v0.3.0](https://github.com/PrefectHQ/fastmcp/compare/v0.2.0...v0.3.0)\n\n\n\n\n## [v0.2.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.2.0)\n\n**Full Changelog**: [v0.1.0...v0.2.0](https://github.com/PrefectHQ/fastmcp/compare/v0.1.0...v0.2.0)\n\n\n\n\n## [v0.1.0](https://github.com/PrefectHQ/fastmcp/releases/tag/v0.1.0)\n\nThe very first release of FastMCP! 🎉\n\n**Full Changelog**: [Initial commits](https://github.com/PrefectHQ/fastmcp/commits/v0.1.0)\n" }, { "path": "docs/cli/auth.mdx", "content": "---\ntitle: Auth Utilities\nsidebarTitle: Auth\ndescription: Create and validate CIMD documents for OAuth\nicon: key\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nThe `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.\n\n## Creating a CIMD\n\n`fastmcp auth cimd create` generates a CIMD document:\n\n```bash\nfastmcp auth cimd create \\\n --name \"My App\" \\\n --redirect-uri \"http://localhost:*/callback\"\n```\n\n```json\n{\n \"client_id\": \"https://your-domain.com/oauth/client.json\",\n \"client_name\": \"My App\",\n \"redirect_uris\": [\"http://localhost:*/callback\"],\n \"token_endpoint_auth_method\": \"none\"\n}\n```\n\nThe generated document includes a placeholder `client_id` — update it to match the URL where you'll host the document before deploying.\n\n### Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Name | `--name` | **Required.** Human-readable client name |\n| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (repeatable) |\n| Client URI | `--client-uri` | Client's home page URL |\n| Logo URI | `--logo-uri` | Client's logo URL |\n| Scope | `--scope` | Space-separated list of scopes |\n| Output | `--output`, `-o` | Save to file (default: stdout) |\n| Pretty | `--pretty` | Pretty-print JSON (default: true) |\n\n### Example\n\n```bash\nfastmcp auth cimd create \\\n --name \"My Production App\" \\\n --redirect-uri \"http://localhost:*/callback\" \\\n --redirect-uri \"https://myapp.example.com/callback\" \\\n --client-uri \"https://myapp.example.com\" \\\n --scope \"read write\" \\\n --output client.json\n```\n\n## Validating a CIMD\n\n`fastmcp auth cimd validate` fetches a hosted CIMD and verifies it conforms to the spec:\n\n```bash\nfastmcp auth cimd validate https://myapp.example.com/oauth/client.json\n```\n\nThe 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.\n\nOn success:\n\n```\n→ Fetching https://myapp.example.com/oauth/client.json...\n✓ Valid CIMD document\n\nDocument details:\n client_id: https://myapp.example.com/oauth/client.json\n client_name: My App\n token_endpoint_auth_method: none\n redirect_uris:\n • http://localhost:*/callback\n```\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Timeout | `--timeout`, `-t` | HTTP request timeout in seconds (default: 10) |\n" }, { "path": "docs/cli/client.mdx", "content": "---\ntitle: Client Commands\nsidebarTitle: Client\ndescription: List tools, call them, and discover configured servers\nicon: satellite-dish\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nThe 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.\n\n## Listing Tools\n\n`fastmcp list` connects to a server and prints its tools as function signatures, showing parameter names, types, and descriptions at a glance:\n\n```bash\nfastmcp list http://localhost:8000/mcp\nfastmcp list server.py\nfastmcp list weather # name-based resolution\n```\n\nWhen 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`:\n\n```bash\nfastmcp list server.py --input-schema\n```\n\n### Resources and Prompts\n\nBy default, only tools are shown. Add `--resources` or `--prompts` to include those:\n\n```bash\nfastmcp list server.py --resources --prompts\n```\n\n### Machine-Readable Output\n\nThe `--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:\n\n```bash\nfastmcp list server.py --json\n```\n\n### Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Command | `--command` | Connect via stdio (e.g., `'npx -y @mcp/server'`) |\n| Transport | `--transport`, `-t` | Force `http` or `sse` for URL targets |\n| Resources | `--resources` | Include resources in output |\n| Prompts | `--prompts` | Include prompts in output |\n| Input Schema | `--input-schema` | Show full input schemas |\n| Output Schema | `--output-schema` | Show full output schemas |\n| JSON | `--json` | Structured JSON output |\n| Timeout | `--timeout` | Connection timeout in seconds |\n| Auth | `--auth` | `oauth` (default for HTTP), a bearer token, or `none` |\n\n## Calling Tools\n\n`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:\n\n```bash\nfastmcp call server.py greet name=World\nfastmcp call http://localhost:8000/mcp search query=hello limit=5\n```\n\nType 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.\n\n### Complex Arguments\n\nFor tools with nested or structured parameters, `key=value` syntax gets awkward. Pass a single JSON object instead:\n\n```bash\nfastmcp call server.py create_item '{\"name\": \"Widget\", \"tags\": [\"sale\"], \"metadata\": {\"color\": \"blue\"}}'\n```\n\nOr use `--input-json` to provide a base dictionary, then override individual keys with `key=value` pairs:\n\n```bash\nfastmcp call server.py search --input-json '{\"query\": \"hello\", \"limit\": 5}' limit=10\n```\n\n### Error Handling\n\nIf 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.\n\n### Structured Output\n\n`--json` emits the raw result including content blocks, error status, and structured content:\n\n```bash\nfastmcp call server.py get_weather city=London --json\n```\n\n### Interactive Elicitation\n\nSome 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.\n\n### Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Command | `--command` | Connect via stdio |\n| Transport | `--transport`, `-t` | Force `http` or `sse` |\n| Input JSON | `--input-json` | Base arguments as JSON (merged with `key=value`) |\n| JSON | `--json` | Raw JSON output |\n| Timeout | `--timeout` | Connection timeout in seconds |\n| Auth | `--auth` | `oauth`, a bearer token, or `none` |\n\n## Discovering Configured Servers\n\n`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks:\n\n- **Claude Desktop** — `claude_desktop_config.json`\n- **Claude Code** — `~/.claude.json`\n- **Cursor** — `.cursor/mcp.json` (walks up from current directory)\n- **Gemini CLI** — `~/.gemini/settings.json`\n- **Goose** — `~/.config/goose/config.yaml`\n- **Project** — `./mcp.json` in the current directory\n\n```bash\nfastmcp discover\n```\n\nThe output groups servers by source, showing each server's name and transport. Filter by source or get machine-readable output:\n\n```bash\nfastmcp discover --source claude-code\nfastmcp discover --source cursor --source gemini --json\n```\n\nAny 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.\n\n## LLM Agent Integration\n\nFor 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.\n\nBecause 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.\n" }, { "path": "docs/cli/generate-cli.mdx", "content": "---\ntitle: Generate CLI\nsidebarTitle: Generate CLI\ndescription: Scaffold a standalone typed CLI from any MCP server\nicon: wand-magic-sparkles\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n`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.\n\nMCP 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.\n\n## Generating a Script\n\nPoint the command at any [server target](/cli/overview#server-targets) and it writes a CLI script:\n\n```bash\nfastmcp generate-cli weather\nfastmcp generate-cli http://localhost:8000/mcp\nfastmcp generate-cli server.py my_weather_cli.py\n```\n\nThe second positional argument sets the output path (defaults to `cli.py`). If the file already exists, pass `-f` to overwrite:\n\n```bash\nfastmcp generate-cli weather -f\n```\n\n## What You Get\n\nThe generated script is a regular Python file — executable, editable, and yours:\n\n```\n$ python cli.py call-tool --help\nUsage: weather-cli call-tool COMMAND\n\nCall a tool on the server\n\nCommands:\n get_forecast Get the weather forecast for a city.\n search_city Search for a city by name.\n```\n\nEach tool has typed parameters with help text pulled directly from the server's schema:\n\n```\n$ python cli.py call-tool get_forecast --help\nUsage: weather-cli call-tool get_forecast [OPTIONS]\n\nGet the weather forecast for a city.\n\nOptions:\n --city [str] City name (required)\n --days [int] Number of forecast days (default: 3)\n```\n\nBeyond 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.\n\n## Parameter Handling\n\nParameters are mapped based on their JSON Schema type:\n\n**Simple types** (`string`, `integer`, `number`, `boolean`) become typed flags:\n\n```bash\npython cli.py call-tool get_forecast --city London --days 3\n```\n\n**Arrays of simple types** become repeatable flags:\n\n```bash\npython cli.py call-tool tag_items --tags python --tags fastapi --tags mcp\n```\n\n**Complex types** (objects, nested arrays, unions) accept JSON strings. The `--help` output shows the full schema so you know what structure to pass:\n\n```bash\npython cli.py call-tool create_user \\\n --name John \\\n --metadata '{\"role\": \"admin\", \"dept\": \"engineering\"}'\n```\n\n## Agent Skill\n\nAlongside 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.\n\nTo skip skill generation:\n\n```bash\nfastmcp generate-cli weather --no-skill\n```\n\n## How It Works\n\nThe 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).\n\nThe 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.\n\nThe script requires `fastmcp` as a dependency. If it lives outside a project that already has FastMCP installed:\n\n```bash\nuv run --with fastmcp python cli.py call-tool get_forecast --city London\n```\n" }, { "path": "docs/cli/inspecting.mdx", "content": "---\ntitle: Inspecting Servers\nsidebarTitle: Inspecting\ndescription: View a server's components and metadata\nicon: magnifying-glass\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n`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:\n\n```bash\nfastmcp inspect server.py\n```\n\n```\nServer: MyServer\nInstructions: A helpful MCP server\nVersion: 1.0.0\n\nComponents:\n Tools: 5\n Prompts: 2\n Resources: 3\n Templates: 1\n\nEnvironment:\n FastMCP: 2.0.0\n MCP: 1.0.0\n\nUse --format [fastmcp|mcp] for complete JSON output\n```\n\n## JSON Output\n\nFor programmatic use, two JSON formats are available:\n\n**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.\n\n**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.\n\n```bash\n# Full FastMCP metadata to stdout\nfastmcp inspect server.py --format fastmcp\n\n# MCP protocol view saved to file\nfastmcp inspect server.py --format mcp -o manifest.json\n```\n\n## Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Format | `--format`, `-f` | `fastmcp` or `mcp` (required when using `-o`) |\n| Output File | `--output`, `-o` | Save to file instead of stdout |\n\n## Entrypoints\n\nThe `inspect` command supports the same local entrypoints as [`fastmcp run`](/cli/running): inferred instances, explicit entrypoints, factory functions, and `fastmcp.json` configs.\n\n```bash\nfastmcp inspect server.py # inferred instance\nfastmcp inspect server.py:my_server # explicit entrypoint\nfastmcp inspect server.py:create_server # factory function\nfastmcp inspect fastmcp.json # config file\n```\n\n\n`inspect` only works with local files and `fastmcp.json` — it doesn't connect to remote URLs or standard MCP config files.\n\n" }, { "path": "docs/cli/install-mcp.mdx", "content": "---\ntitle: Install MCP Servers\nsidebarTitle: Install MCPs\ndescription: Install MCP servers into Claude, Cursor, Gemini, and other clients\nicon: download\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n`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.\n\n```bash\nfastmcp install claude-desktop server.py\nfastmcp install claude-code server.py --with pandas --with matplotlib\nfastmcp install cursor server.py -e .\n```\n\n\n`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`.\n\n\n## Supported Clients\n\n| Client | Install method |\n| ------ | -------------- |\n| `claude-code` | Claude Code's built-in MCP management |\n| `claude-desktop` | Direct config file modification |\n| `cursor` | Deeplink that opens Cursor for confirmation |\n| `gemini-cli` | Gemini CLI's built-in MCP management |\n| `goose` | Deeplink that opens Goose for confirmation (uses `uvx`) |\n| `mcp-json` | Generates standard MCP JSON config for manual use |\n| `stdio` | Outputs the shell command to run via stdio |\n\n## Declaring Dependencies\n\nBecause MCP clients run servers in isolation, you need to tell the install command what your server needs. There are two approaches:\n\n**Command-line flags** let you specify dependencies directly:\n\n```bash\nfastmcp install claude-desktop server.py --with pandas --with \"sqlalchemy>=2.0\"\nfastmcp install cursor server.py -e . --with-requirements requirements.txt\n```\n\n**`fastmcp.json`** configuration files declare dependencies alongside the server definition. When you install from a config file, dependencies are picked up automatically:\n\n```bash\nfastmcp install claude-desktop fastmcp.json\nfastmcp install claude-desktop # auto-detects fastmcp.json in current directory\n```\n\nSee [Server Configuration](/deployment/server-configuration) for the full config format.\n\n## Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Server Name | `--server-name`, `-n` | Custom name for the server |\n| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |\n| Extra Packages | `--with` | Additional packages (repeatable) |\n| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable) |\n| Environment File | `--env-file`, `-f` | Load env vars from a `.env` file |\n| Python | `--python` | Python version (e.g., `3.11`) |\n| Project | `--project` | Run within a uv project directory |\n| Requirements | `--with-requirements` | Install from a requirements file |\n| Config Path | `--config-path` | Custom path to Claude Desktop config directory (`claude-desktop` only) |\n\n## Examples\n\n```bash\n# Basic install with auto-detected server instance\nfastmcp install claude-desktop server.py\n\n# Install from fastmcp.json with auto-detection\nfastmcp install claude-desktop\n\n# Explicit entrypoint with dependencies\nfastmcp install claude-desktop server.py:my_server \\\n --server-name \"My Analysis Server\" \\\n --with pandas\n\n# With environment variables\nfastmcp install claude-code server.py \\\n --env API_KEY=secret \\\n --env DEBUG=true\n\n# With env file\nfastmcp install cursor server.py --env-file .env\n\n# Specific Python version and requirements file\nfastmcp install claude-desktop server.py \\\n --python 3.11 \\\n --with-requirements requirements.txt\n\n# With custom config path (claude-desktop only)\nfastmcp install claude-desktop server.py \\\n --config-path \"C:\\Users\\username\\AppData\\Local\\Packages\\Claude_xyz\\LocalCache\\Roaming\\Claude\"\n```\n\n## Generating MCP JSON\n\nThe `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:\n\n```bash\nfastmcp install mcp-json server.py\n```\n\nThe output follows the standard format used by Claude Desktop, Cursor, and other MCP clients:\n\n```json\n{\n \"server-name\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"fastmcp\", \"fastmcp\", \"run\", \"/path/to/server.py\"],\n \"env\": {\n \"API_KEY\": \"value\"\n }\n }\n}\n```\n\nUse `--copy` to send it to your clipboard instead of stdout.\n\n## Generating Stdio Commands\n\nThe `stdio` target outputs the shell command an MCP host would use to start your server over stdio:\n\n```bash\nfastmcp install stdio server.py\n# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py\n```\n\nWhen installing from a `fastmcp.json`, dependencies from the config are included automatically:\n\n```bash\nfastmcp install stdio fastmcp.json\n# Output: uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /path/to/server.py\n```\n\nUse `--copy` to copy to clipboard.\n\n\n`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.\n\n" }, { "path": "docs/cli/overview.mdx", "content": "---\ntitle: CLI\nsidebarTitle: Overview\ndescription: The fastmcp command-line interface\nicon: terminal\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\nThe `fastmcp` CLI is installed automatically with FastMCP. It's the primary way to run, test, install, and interact with MCP servers from your terminal.\n\n```bash\nfastmcp --help\n```\n\n## Commands at a Glance\n\n| Command | What it does |\n| ------- | ------------ |\n| [`run`](/cli/running) | Run a server (local file, factory function, remote URL, or config file) |\n| [`dev apps`](/cli/running#previewing-apps) | Launch a browser-based preview UI for Prefab App tools |\n| [`dev inspector`](/cli/running#development-with-the-inspector) | Launch a server inside the MCP Inspector for interactive testing |\n| [`install`](/cli/install-mcp) | Install a server into Claude Code, Claude Desktop, Cursor, Gemini CLI, or Goose |\n| [`inspect`](/cli/inspecting) | Print a server's tools, resources, and prompts as a summary or JSON report |\n| [`list`](/cli/client) | List a server's tools (and optionally resources and prompts) |\n| [`call`](/cli/client#calling-tools) | Call a single tool with arguments |\n| [`discover`](/cli/client#discovering-configured-servers) | Find MCP servers configured in your editors and tools |\n| [`generate-cli`](/cli/generate-cli) | Scaffold a standalone typed CLI from a server's tool schemas |\n| [`project prepare`](/cli/running#pre-building-environments) | Pre-install dependencies into a reusable uv project |\n| [`auth cimd`](/cli/auth) | Create and validate CIMD documents for OAuth |\n| `version` | Print version info (`--copy` to copy to clipboard) |\n\n## Server Targets\n\nMost 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.\n\n**URLs** connect to a running HTTP server:\n\n```bash\nfastmcp list http://localhost:8000/mcp\nfastmcp call http://localhost:8000/mcp get_forecast city=London\n```\n\n**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:\n\n```bash\nfastmcp list server.py\nfastmcp run server.py:my_custom_server\n```\n\n**Config files** work too — both FastMCP's own `fastmcp.json` format and standard MCP config files with an `mcpServers` key:\n\n```bash\nfastmcp run fastmcp.json\nfastmcp list mcp-config.json\n```\n\n**Stdio commands** connect to any MCP server that speaks over standard I/O. Use `--command` instead of a positional argument:\n\n```bash\nfastmcp list --command 'npx -y @modelcontextprotocol/server-github'\n```\n\n### Name-Based Resolution\n\nIf 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:\n\n```bash\nfastmcp list weather\nfastmcp call weather get_forecast city=London\n```\n\nWhen the same name appears in multiple configs, use the `source:name` form to be specific:\n\n```bash\nfastmcp list claude-code:my-server\nfastmcp call cursor:weather get_forecast city=London\n```\n\nRun [`fastmcp discover`](/cli/client#discovering-configured-servers) to see what's available on your machine.\n\n## Authentication\n\nWhen 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.\n\nTo skip authentication entirely — useful for local development servers — pass `--auth none`:\n\n```bash\nfastmcp call http://localhost:8000/mcp my_tool --auth none\n```\n\nYou can also pass a bearer token directly:\n\n```bash\nfastmcp list http://localhost:8000/mcp --auth \"Bearer sk-...\"\n```\n\n## Transport Override\n\nFastMCP defaults to Streamable HTTP for URL targets. If the server only supports Server-Sent Events (SSE), force the older transport:\n\n```bash\nfastmcp list http://localhost:8000 --transport sse\n```\n" }, { "path": "docs/cli/running.mdx", "content": "---\ntitle: Running Servers\nsidebarTitle: Running\ndescription: Start, develop, and configure servers from the command line\nicon: play\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n## Starting a Server\n\n`fastmcp run` starts a server. Point it at a Python file, a factory function, a remote URL, or a config file:\n\n```bash\nfastmcp run server.py\nfastmcp run server.py:create_server\nfastmcp run https://example.com/mcp\nfastmcp run fastmcp.json\n```\n\nBy default, the server runs over **stdio** — the transport that MCP clients like Claude Desktop expect. To serve over HTTP instead, specify the transport:\n\n```bash\nfastmcp run server.py --transport http\nfastmcp run server.py --transport http --host 0.0.0.0 --port 9000\n```\n\n### Entrypoints\n\nFastMCP supports several ways to locate and start your server:\n\n**Inferred instance** — FastMCP imports the file and looks for a variable named `mcp`, `server`, or `app`:\n\n```bash\nfastmcp run server.py\n```\n\n**Explicit instance** — point at a specific variable:\n\n```bash\nfastmcp run server.py:my_server\n```\n\n**Factory function** — FastMCP calls the function and uses the returned server. Useful when your server needs async setup or configuration that runs before startup:\n\n```bash\nfastmcp run server.py:create_server\n```\n\n**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:\n\n```bash\nfastmcp run https://example.com/mcp\n```\n\n**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:\n\n```bash\nfastmcp run\nfastmcp run my-config.fastmcp.json\n```\n\nSee [Server Configuration](/deployment/server-configuration) for the full `fastmcp.json` format.\n\n**MCP config** — runs servers defined in a standard MCP configuration file (any `.json` with an `mcpServers` key):\n\n```bash\nfastmcp run mcp.json\n```\n\n\n`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).\n\n\n### Options\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Transport | `--transport`, `-t` | `stdio` (default), `http`, or `sse` |\n| Host | `--host` | Bind address for HTTP (default: `127.0.0.1`) |\n| Port | `--port`, `-p` | Bind port for HTTP (default: `8000`) |\n| Path | `--path` | URL path for HTTP (default: `/mcp/`) |\n| Log Level | `--log-level`, `-l` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |\n| No Banner | `--no-banner` | Suppress the startup banner |\n| Auto-Reload | `--reload` / `--no-reload` | Watch for file changes and restart automatically |\n| Reload Dirs | `--reload-dir` | Directories to watch (repeatable) |\n| Skip Env | `--skip-env` | Don't set up a uv environment (use when already in one) |\n| Python | `--python` | Python version to use (e.g., `3.11`) |\n| Extra Packages | `--with` | Additional packages to install (repeatable) |\n| Project | `--project` | Run within a specific uv project directory |\n| Requirements | `--with-requirements` | Install from a requirements file |\n\n### Dependency Management\n\nBy 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.\n\nThe `--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.\n\n## Previewing Apps\n\n\n\n`fastmcp dev apps` launches a browser-based preview UI for servers with [Prefab App tools](/apps/prefab). It starts your MCP server on one port and a local dev UI on another — giving you a live, interactive picker where you can call app tools and see their rendered output without needing a full MCP host client.\n\n```bash\nfastmcp dev apps server.py\nfastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090\n```\n\nThe picker auto-generates a form from each tool's input schema. Submit the form and the result opens in a new tab as a rendered Prefab UI.\n\nAuto-reload is on by default — save a file and the MCP server restarts automatically.\n\n\n`fastmcp dev apps` requires `fastmcp[apps]` — install with `pip install \"fastmcp[apps]\"`.\n\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| MCP Port | `--mcp-port` | Port for the MCP server (default: `8000`) |\n| Dev Port | `--dev-port` | Port for the dev UI (default: `8080`) |\n| Auto-Reload | `--reload` / `--no-reload` | Watch for file changes (default: on) |\n\n## Development with the Inspector\n\n`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.\n\n```bash\nfastmcp dev inspector server.py\nfastmcp dev inspector server.py -e . --with pandas\n```\n\n\nThe 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.\n\n\n\nThe 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.\n\n\n| Option | Flag | Description |\n| ------ | ---- | ----------- |\n| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |\n| Extra Packages | `--with` | Additional packages (repeatable) |\n| Inspector Version | `--inspector-version` | MCP Inspector version to use |\n| UI Port | `--ui-port` | Port for the Inspector UI |\n| Server Port | `--server-port` | Port for the Inspector proxy |\n| Auto-Reload | `--reload` / `--no-reload` | File watching (default: on) |\n| Reload Dirs | `--reload-dir` | Directories to watch (repeatable) |\n| Python | `--python` | Python version |\n| Project | `--project` | Run within a uv project directory |\n| Requirements | `--with-requirements` | Install from a requirements file |\n\n## Pre-Building Environments\n\n`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.\n\n```bash\n# Step 1: Build the environment (slow, does dependency resolution)\nfastmcp project prepare fastmcp.json --output-dir ./env\n\n# Step 2: Run using the prepared environment (fast, no install step)\nfastmcp run fastmcp.json --project ./env\n```\n\nThe 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.\n" }, { "path": "docs/clients/auth/bearer.mdx", "content": "---\ntitle: Bearer Token Authentication\nsidebarTitle: Bearer Auth\ndescription: Authenticate your FastMCP client with a Bearer token.\nicon: key\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\n\nBearer Token authentication is only relevant for HTTP-based transports.\n\n\nYou 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.\n\nA 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:\n\n```http\nAuthorization: Bearer \n```\n\n\n## Client Usage\n\nThe 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.\n\n\nIf you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you.\n\n\n```python {5}\nfrom fastmcp import Client\n\nasync with Client(\n \"https://your-server.fastmcp.app/mcp\", \n auth=\"\",\n) as client:\n await client.ping()\n```\n\nYou can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`:\n\n```python {6}\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\ntransport = StreamableHttpTransport(\n \"http://your-server.fastmcp.app/mcp\", \n auth=\"\",\n)\n\nasync with Client(transport) as client:\n await client.ping()\n```\n\n## `BearerAuth` Helper\n\nIf 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.\n\n```python {6}\nfrom fastmcp import Client\nfrom fastmcp.client.auth import BearerAuth\n\nasync with Client(\n \"https://your-server.fastmcp.app/mcp\", \n auth=BearerAuth(token=\"\"),\n) as client:\n await client.ping()\n```\n\n## Custom Headers\n\nIf 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:\n\n```python {5}\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\nasync with Client(\n transport=StreamableHttpTransport(\n \"https://your-server.fastmcp.app/mcp\", \n headers={\"X-API-Key\": \"\"},\n ),\n) as client:\n await client.ping()\n```\n" }, { "path": "docs/clients/auth/cimd.mdx", "content": "---\ntitle: CIMD Authentication\nsidebarTitle: CIMD\ndescription: Use Client ID Metadata Documents for verifiable, domain-based client identity.\nicon: id-badge\ntag: NEW\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\n\nCIMD authentication is only relevant for HTTP-based transports and requires a server that advertises CIMD support.\n\n\nWith 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.\n\nCIMD (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.\n\n## Client Usage\n\nPass your CIMD document URL to the `client_metadata_url` parameter of `OAuth`:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\nasync with Client(\n \"https://mcp-server.example.com/mcp\",\n auth=OAuth(\n client_metadata_url=\"https://myapp.example.com/oauth/client.json\",\n ),\n) as client:\n await client.ping()\n```\n\nWhen 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.\n\n\nYou don't need to pass `mcp_url` when using `OAuth` with `Client(auth=...)` — the transport provides the server URL automatically.\n\n\n## Creating a CIMD Document\n\nA 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.\n\nUse the FastMCP CLI to generate one:\n\n```bash\nfastmcp auth cimd create \\\n --name \"My Application\" \\\n --redirect-uri \"http://localhost:*/callback\" \\\n --client-id \"https://myapp.example.com/oauth/client.json\"\n```\n\nThis produces:\n\n```json\n{\n \"client_id\": \"https://myapp.example.com/oauth/client.json\",\n \"client_name\": \"My Application\",\n \"redirect_uris\": [\"http://localhost:*/callback\"],\n \"token_endpoint_auth_method\": \"none\",\n \"grant_types\": [\"authorization_code\"],\n \"response_types\": [\"code\"]\n}\n```\n\nIf you omit `--client-id`, the CLI generates a placeholder value and reminds you to update it before hosting.\n\n### CLI Options\n\nThe `create` command accepts these flags:\n\n| Flag | Description |\n|------|-------------|\n| `--name` | Human-readable client name (required) |\n| `--redirect-uri`, `-r` | Allowed redirect URIs — can be specified multiple times (required) |\n| `--client-id` | The URL where you'll host this document (sets `client_id` directly) |\n| `--output`, `-o` | Write to a file instead of stdout |\n| `--scope` | Space-separated list of scopes the client may request |\n| `--client-uri` | URL of the client's home page |\n| `--logo-uri` | URL of the client's logo image |\n| `--no-pretty` | Output compact JSON |\n\n### Redirect URIs\n\nThe `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).\n\n## Hosting Requirements\n\nCIMD documents must be hosted at a publicly accessible HTTPS URL with a non-root path:\n\n- **HTTPS required** — HTTP URLs are rejected for security\n- **Non-root path** — The URL must have a path component (e.g., `/oauth/client.json`, not just `/`)\n- **Public accessibility** — The server must be able to fetch the document over the internet\n- **Matching `client_id`** — The `client_id` field in the document must exactly match the hosting URL\n\nCommon hosting options include static file hosting services like GitHub Pages, Cloudflare Pages, Vercel, or S3 — anywhere you can serve a JSON file over HTTPS.\n\n## Validating Your Document\n\nBefore deploying, verify your hosted document passes validation:\n\n```bash\nfastmcp auth cimd validate https://myapp.example.com/oauth/client.json\n```\n\nThe validator fetches the document and checks that:\n- The URL is valid (HTTPS, non-root path)\n- The document is well-formed JSON conforming to the CIMD schema\n- The `client_id` in the document matches the URL it was fetched from\n\n## How It Works\n\nWhen your client connects to a CIMD-enabled server, the flow works like this:\n\n\n\nYour client sends its `client_metadata_url` as the `client_id` in the OAuth authorization request.\n\n\nThe server sees that the `client_id` is an HTTPS URL with a path — the signature of a CIMD client — and skips Dynamic Client Registration.\n\n\nThe server fetches your JSON document from the URL, validates that `client_id` matches the URL, and extracts your client metadata (name, redirect URIs, scopes).\n\n\nThe standard OAuth flow continues: browser opens for user consent, authorization code exchange, token issuance. The consent screen shows your verified domain.\n\n\n\nThe server caches your CIMD document according to HTTP cache headers, so subsequent requests don't require re-fetching.\n\n## Server Configuration\n\nCIMD 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.\n" }, { "path": "docs/clients/auth/oauth.mdx", "content": "---\ntitle: OAuth Authentication\nsidebarTitle: OAuth\ndescription: Authenticate your FastMCP client via OAuth 2.1.\nicon: window\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\n\nOAuth authentication is only relevant for HTTP-based transports and requires user interaction via a web browser.\n\n\nWhen 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.\n\nThis flow is common for user-facing applications where the application acts on behalf of the user.\n\n## Client Usage\n\n\n### Default Configuration\n\nThe 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:\n\n```python {4}\nfrom fastmcp import Client\n\n# Uses default OAuth settings\nasync with Client(\"https://your-server.fastmcp.app/mcp\", auth=\"oauth\") as client:\n await client.ping()\n```\n\n\n### `OAuth` Helper\n\nTo 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.\n\n```python {2, 4, 6}\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\noauth = OAuth(scopes=[\"user\"])\n\nasync with Client(\"https://your-server.fastmcp.app/mcp\", auth=oauth) as client:\n await client.ping()\n```\n\n\nYou don't need to pass `mcp_url` when using `OAuth` with `Client(auth=...)` — the transport provides the server URL automatically.\n\n\n#### `OAuth` Parameters\n\n- **`scopes`** (`str | list[str]`, optional): OAuth scopes to request. Can be space-separated string or list of strings\n- **`client_name`** (`str`, optional): Client name for dynamic registration. Defaults to `\"FastMCP Client\"`\n- **`client_id`** (`str`, optional): Pre-registered OAuth client ID. When provided, skips Dynamic Client Registration entirely. See [Pre-Registered Clients](#pre-registered-clients)\n- **`client_secret`** (`str`, optional): OAuth client secret for pre-registered clients. Optional — public clients that rely on PKCE can omit this\n- **`client_metadata_url`** (`str`, optional): URL-based client identity (CIMD). See [CIMD Authentication](/clients/auth/cimd) for details\n- **`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\n- **`additional_client_metadata`** (`dict[str, Any]`, optional): Extra metadata for client registration\n- **`callback_port`** (`int`, optional): Fixed port for OAuth callback server. If not specified, uses a random available port\n- **`httpx_client_factory`** (`McpHttpClientFactory`, optional): Factory for creating httpx clients\n\n\n## OAuth Flow\n\nThe OAuth flow is triggered when you use a FastMCP `Client` configured to use OAuth.\n\n\n\nThe 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.\n\n\nIf 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`.\n\n\nIf 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.\n\n\nA 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:/callback`) acts as the `redirect_uri` for the OAuth flow.\n\n\nThe 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`.\n\n\nUpon 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.\n\n\nThe obtained tokens are saved to the configured `token_storage` backend for future use, eliminating the need for repeated browser interactions.\n\n\nThe access token is automatically included in the `Authorization` header for requests to the MCP server.\n\n\nIf the access token expires, the client will automatically use the refresh token to get a new access token.\n\n\n\n## Token Storage\n\n\n\nBy 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.\n\n\n**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.\n\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\nfrom key_value.aio.stores.disk import DiskStore\nfrom key_value.aio.wrappers.encryption import FernetEncryptionWrapper\nfrom cryptography.fernet import Fernet\nimport os\n\n# Create encrypted disk storage\nencrypted_storage = FernetEncryptionWrapper(\n key_value=DiskStore(directory=\"~/.fastmcp/oauth-tokens\"),\n fernet=Fernet(os.environ[\"OAUTH_STORAGE_ENCRYPTION_KEY\"])\n)\n\noauth = OAuth(token_storage=encrypted_storage)\n\nasync with Client(\"https://your-server.fastmcp.app/mcp\", auth=oauth) as client:\n await client.ping()\n```\n\nYou 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.\n\n\nWhen 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.\n\n\n## CIMD Authentication\n\n\n\nClient 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.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\nasync with Client(\n \"https://mcp-server.example.com/mcp\",\n auth=OAuth(\n client_metadata_url=\"https://myapp.example.com/oauth/client.json\",\n ),\n) as client:\n await client.ping()\n```\n\nSee the [CIMD Authentication](/clients/auth/cimd) page for complete documentation on creating, hosting, and validating CIMD documents.\n\n## Pre-Registered Clients\n\n\n\nSome 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.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\nasync with Client(\n \"https://mcp-server.example.com/mcp\",\n auth=OAuth(\n client_id=\"my-registered-client-id\",\n client_secret=\"my-client-secret\",\n ),\n) as client:\n await client.ping()\n```\n\nPublic clients that rely on PKCE for security can omit `client_secret`:\n\n```python\noauth = OAuth(client_id=\"my-public-client-id\")\n```\n\n\nWhen 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.\n\n" }, { "path": "docs/clients/cli.mdx", "content": "---\ntitle: Client CLI\nsidebarTitle: CLI\ndescription: Query and invoke MCP server tools directly from the terminal with fastmcp list and fastmcp call.\nicon: terminal\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nMCP 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.\n\nThese 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.\n\n## Server Targets\n\nBoth 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.\n\n```bash\nfastmcp list http://localhost:8000/mcp\nfastmcp list server.py\nfastmcp list mcp-config.json\n```\n\nPython 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.\n\nFor 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.\n\n```bash\nfastmcp list --command 'npx -y @modelcontextprotocol/server-github'\n```\n\n### Name-Based Resolution\n\nIf 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.\n\n```bash\nfastmcp list weather\nfastmcp call weather get_forecast city=London\n```\n\nYou 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.\n\n```bash\nfastmcp list claude-code:my-server\nfastmcp call cursor:weather get_forecast city=London\n```\n\nThe available source names are `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, and `project` (for `./mcp.json`). Run `fastmcp discover` to see what's available.\n\n## Discovering Configured Servers\n\n`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.\n\n```bash\nfastmcp discover\n```\n\nThe 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.\n\n```bash\nfastmcp discover --source claude-code\nfastmcp discover --source cursor --source gemini --json\n```\n\nAny 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.\n\n## Discovering Tools\n\n`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.\n\n```bash\nfastmcp list http://localhost:8000/mcp\n```\n\nThe 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.\n\nWhen 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.\n\n### Beyond Tools\n\nMCP 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.\n\n```bash\nfastmcp list server.py --resources --prompts\n```\n\nResources appear with their URIs and descriptions. Prompts appear with their argument names so you can see what parameters they accept.\n\n### Machine-Readable Output\n\nThe `--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.\n\n```bash\nfastmcp list server.py --json\n```\n\nThis 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.\n\n## Calling Tools\n\n`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.\n\n```bash\nfastmcp call http://localhost:8000/mcp search query=hello limit=5\n```\n\nType 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.\n\nFor 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.\n\n```bash\nfastmcp call server.py create_item '{\"name\": \"Widget\", \"tags\": [\"sale\", \"new\"], \"metadata\": {\"color\": \"blue\"}}'\n```\n\nAlternatively, `--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.\n\n### Error Handling\n\nThe 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.\n\nWhen 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.\n\n### Structured Output\n\nLike `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.\n\n```bash\nfastmcp call server.py get_weather city=London --json\n```\n\n## Authentication\n\nWhen 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.\n\nTo explicitly disable authentication -- for example, when connecting to a local development server where OAuth setup would just slow you down -- pass `--auth none`.\n\n```bash\nfastmcp call http://localhost:8000/mcp my_tool --auth none\n```\n\n## Transport Override\n\nFastMCP 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.\n\n```bash\nfastmcp list http://localhost:8000 --transport sse\n```\n\n## Interactive Elicitation\n\nSome 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.\n\nYou 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.\n\n## LLM Agent Integration\n\nFor 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.\n\nBecause 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.\n" }, { "path": "docs/clients/client.mdx", "content": "---\ntitle: The FastMCP Client\nsidebarTitle: Overview\ndescription: Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface.\nicon: user-robot\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nThe `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.\n\nThe 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.\n\n\nThis 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.\n\n\n## Creating a Client\n\nYou provide a server source and the client automatically infers the appropriate transport mechanism.\n\n```python\nimport asyncio\nfrom fastmcp import Client, FastMCP\n\n# In-memory server (ideal for testing)\nserver = FastMCP(\"TestServer\")\nclient = Client(server)\n\n# HTTP server\nclient = Client(\"https://example.com/mcp\")\n\n# Local Python script\nclient = Client(\"my_mcp_server.py\")\n\nasync def main():\n async with client:\n # Basic server interaction\n await client.ping()\n\n # List available operations\n tools = await client.list_tools()\n resources = await client.list_resources()\n prompts = await client.list_prompts()\n\n # Execute operations\n result = await client.call_tool(\"example_tool\", {\"param\": \"value\"})\n print(result)\n\nasyncio.run(main())\n```\n\nAll client operations require using the `async with` context manager for proper connection lifecycle management.\n\n## Choosing a Transport\n\nThe client automatically selects a transport based on what you pass to it, but different transports have different characteristics that matter for your use case.\n\n**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.\n\n```python\nfrom fastmcp import Client, FastMCP\n\nserver = FastMCP(\"TestServer\")\nclient = Client(server) # In-memory, no network or subprocess\n```\n\n**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.\n\n```python\nfrom fastmcp import Client\n\n# Simple inference from file path\nclient = Client(\"my_server.py\")\n\n# With explicit environment configuration\nclient = Client(\"my_server.py\", env={\"API_KEY\": \"secret\"})\n```\n\n**HTTP transport** connects to servers running as web services. Use this for production deployments where the server runs independently and manages its own lifecycle.\n\n```python\nfrom fastmcp import Client\n\nclient = Client(\"https://api.example.com/mcp\")\n```\n\nSee [Transports](/clients/transports) for detailed configuration options including authentication headers, session persistence, and multi-server configurations.\n\n## Configuration-Based Clients\n\n\n\nCreate 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.\n\n```python\nconfig = {\n \"mcpServers\": {\n \"weather\": {\n \"url\": \"https://weather-api.example.com/mcp\"\n },\n \"assistant\": {\n \"command\": \"python\",\n \"args\": [\"./assistant_server.py\"]\n }\n }\n}\n\nclient = Client(config)\n\nasync with client:\n # Tools are prefixed with server names\n weather_data = await client.call_tool(\"weather_get_forecast\", {\"city\": \"London\"})\n response = await client.call_tool(\"assistant_answer_question\", {\"question\": \"What's the capital of France?\"})\n\n # Resources use prefixed URIs\n icons = await client.read_resource(\"weather://weather/icons/sunny\")\n```\n\n## Connection Lifecycle\n\nThe 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.\n\n```python\nfrom fastmcp import Client, FastMCP\n\nmcp = FastMCP(name=\"MyServer\", instructions=\"Use the greet tool to say hello!\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n \"\"\"Greet a user by name.\"\"\"\n return f\"Hello, {name}!\"\n\nasync with Client(mcp) as client:\n # Initialization already happened automatically\n print(f\"Server: {client.initialize_result.serverInfo.name}\")\n print(f\"Instructions: {client.initialize_result.instructions}\")\n print(f\"Capabilities: {client.initialize_result.capabilities.tools}\")\n```\n\nFor advanced scenarios where you need precise control over when initialization happens, disable automatic initialization and call `initialize()` manually:\n\n```python\nfrom fastmcp import Client\n\nclient = Client(\"my_mcp_server.py\", auto_initialize=False)\n\nasync with client:\n # Connection established, but not initialized yet\n print(f\"Connected: {client.is_connected()}\")\n print(f\"Initialized: {client.initialize_result is not None}\") # False\n\n # Initialize manually with custom timeout\n result = await client.initialize(timeout=10.0)\n print(f\"Server: {result.serverInfo.name}\")\n\n # Now ready for operations\n tools = await client.list_tools()\n```\n\n## Operations\n\nFastMCP clients interact with three types of server components.\n\n**Tools** are server-side functions that the client can execute with arguments. Call them with `call_tool()` and receive structured results.\n\n```python\nasync with client:\n tools = await client.list_tools()\n result = await client.call_tool(\"multiply\", {\"a\": 5, \"b\": 3})\n print(result.data) # 15\n```\n\nSee [Tools](/clients/tools) for detailed documentation including version selection, error handling, and structured output.\n\n**Resources** are data sources that the client can read, either static or templated. Access them with `read_resource()` using URIs.\n\n```python\nasync with client:\n resources = await client.list_resources()\n content = await client.read_resource(\"file:///config/settings.json\")\n print(content[0].text)\n```\n\nSee [Resources](/clients/resources) for detailed documentation including templates and binary content.\n\n**Prompts** are reusable message templates that can accept arguments. Retrieve rendered prompts with `get_prompt()`.\n\n```python\nasync with client:\n prompts = await client.list_prompts()\n messages = await client.get_prompt(\"analyze_data\", {\"data\": [1, 2, 3]})\n print(messages.messages)\n```\n\nSee [Prompts](/clients/prompts) for detailed documentation including argument serialization.\n\n## Callback Handlers\n\nThe client supports callback handlers for advanced server interactions. These let you respond to server-initiated requests and receive notifications.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.logging import LogMessage\n\nasync def log_handler(message: LogMessage):\n print(f\"Server log: {message.data}\")\n\nasync def progress_handler(progress: float, total: float | None, message: str | None):\n print(f\"Progress: {progress}/{total} - {message}\")\n\nasync def sampling_handler(messages, params, context):\n # Integrate with your LLM service here\n return \"Generated response\"\n\nclient = Client(\n \"my_mcp_server.py\",\n log_handler=log_handler,\n progress_handler=progress_handler,\n sampling_handler=sampling_handler,\n timeout=30.0\n)\n```\n\nEach handler type has its own documentation:\n\n- **[Sampling](/clients/sampling)** - Respond to server LLM requests\n- **[Elicitation](/clients/elicitation)** - Handle server requests for user input\n- **[Progress](/clients/progress)** - Monitor long-running operations\n- **[Logging](/clients/logging)** - Handle server log messages\n- **[Roots](/clients/roots)** - Provide local context to servers\n\n\nThe 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.\n\n" }, { "path": "docs/clients/elicitation.mdx", "content": "---\ntitle: User Elicitation\nsidebarTitle: Elicitation\ndescription: Handle server requests for structured user input.\nicon: message-question\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\";\n\n\n\nUse this when you need to respond to server requests for user input during tool execution.\n\nElicitation 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.\n\n## Handler Template\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.elicitation import ElicitResult, ElicitRequestParams, RequestContext\n\nasync def elicitation_handler(\n message: str,\n response_type: type | None,\n params: ElicitRequestParams,\n context: RequestContext\n) -> ElicitResult | object:\n \"\"\"\n Handle server requests for user input.\n\n Args:\n message: The prompt to display to the user\n response_type: Python dataclass type for the response (None if no data expected)\n params: Original MCP elicitation parameters including raw JSON schema\n context: Request context with metadata\n\n Returns:\n - Data directly (implicitly accepts the elicitation)\n - ElicitResult for explicit control over the action\n \"\"\"\n # Present the message and collect input\n user_input = input(f\"{message}: \")\n\n if not user_input:\n return ElicitResult(action=\"decline\")\n\n # Create response using the provided dataclass type\n return response_type(value=user_input)\n\nclient = Client(\n \"my_mcp_server.py\",\n elicitation_handler=elicitation_handler,\n)\n```\n\n## How It Works\n\nWhen 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.\n\nThe handler receives four parameters:\n\n\n\n The prompt message to display to the user\n\n\n\n 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`.\n\n\n\n The original MCP elicitation parameters, including the raw JSON schema in `params.requestedSchema`\n\n\n\n Request context containing metadata about the elicitation request\n\n\n\n## Response Actions\n\nYou can return data directly, which implicitly accepts the elicitation:\n\n```python\nasync def elicitation_handler(message, response_type, params, context):\n user_input = input(f\"{message}: \")\n return response_type(value=user_input) # Implicit accept\n```\n\nOr return an `ElicitResult` for explicit control over the action:\n\n```python\nfrom fastmcp.client.elicitation import ElicitResult\n\nasync def elicitation_handler(message, response_type, params, context):\n user_input = input(f\"{message}: \")\n\n if not user_input:\n return ElicitResult(action=\"decline\") # User declined\n\n if user_input == \"cancel\":\n return ElicitResult(action=\"cancel\") # Cancel entire operation\n\n return ElicitResult(\n action=\"accept\",\n content=response_type(value=user_input)\n )\n```\n\n**Action types:**\n- **`accept`**: User provided valid input. Include the data in the `content` field.\n- **`decline`**: User chose not to provide the requested information. Omit `content`.\n- **`cancel`**: User cancelled the entire operation. Omit `content`.\n\n## Example\n\nA file management tool might ask which directory to create:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.elicitation import ElicitResult\n\nasync def elicitation_handler(message, response_type, params, context):\n print(f\"Server asks: {message}\")\n\n user_response = input(\"Your response: \")\n\n if not user_response:\n return ElicitResult(action=\"decline\")\n\n # Use the response_type dataclass to create a properly structured response\n return response_type(value=user_response)\n\nclient = Client(\n \"my_mcp_server.py\",\n elicitation_handler=elicitation_handler\n)\n```\n" }, { "path": "docs/clients/generate-cli.mdx", "content": "---\ntitle: Generate CLI\nsidebarTitle: Generate CLI\ndescription: Turn any MCP server into a standalone, typed command-line tool.\nicon: wand-magic-sparkles\ntag: NEW\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\n`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.\n\nThe 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.\n\n## Generating a Script\n\nPoint the command at any server spec — URLs, Python files, discovered server names, MCPConfig JSON — and it writes a CLI script:\n\n```bash\nfastmcp generate-cli weather\nfastmcp generate-cli http://localhost:8000/mcp\nfastmcp generate-cli server.py my_weather_cli.py\n```\n\nThe 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`:\n\n```bash\nfastmcp generate-cli weather -f\nfastmcp generate-cli weather my_cli.py -f\n```\n\nName-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.\n\n```bash\nfastmcp generate-cli claude-code:my-server output.py\n```\n\nThe `--timeout` and `--auth` flags work the same way they do in `fastmcp list` and `fastmcp call`.\n\n## What You Get\n\nThe generated script is a regular Python file — executable, editable, and yours. Here's what it looks like in practice:\n\n```\n$ python cli.py --help\nUsage: weather-cli COMMAND\n\nCLI for weather MCP server\n\nCommands:\n call-tool Call a tool on the server\n list-tools List available tools.\n list-resources List available resources.\n read-resource Read a resource by URI.\n list-prompts List available prompts.\n get-prompt Get a prompt by name. Pass arguments as key=value pairs.\n```\n\nThe `call-tool` subcommand is where the generated code lives. Each tool on the server becomes its own command:\n\n```\n$ python cli.py call-tool --help\nUsage: weather-cli call-tool COMMAND\n\nCall a tool on the server\n\nCommands:\n get_forecast Get the weather forecast for a city.\n search_city Search for a city by name.\n```\n\nAnd each tool has typed parameters with help text pulled directly from the server's schema:\n\n```\n$ python cli.py call-tool get_forecast --help\nUsage: weather-cli call-tool get_forecast [OPTIONS]\n\nGet the weather forecast for a city.\n\nOptions:\n --city [str] City name (required)\n --days [int] Number of forecast days (default: 3)\n```\n\nTool names are preserved exactly as the server defines them — underscores stay as underscores, so `call-tool get_forecast` matches what the server expects.\n\n## Agent Skill\n\nAlongside 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.\n\nThe skill is written to the same directory as the CLI script. For a weather server, it looks something like:\n\n````markdown\n---\nname: \"weather-cli\"\ndescription: \"CLI for the weather MCP server. Call tools, list resources, and get prompts.\"\n---\n\n# weather CLI\n\n## Tool Commands\n\n### get_forecast\n\nGet the weather forecast for a city.\n\n```bash\nuv run --with fastmcp python cli.py call-tool get_forecast --city --days \n```\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--city` | string | yes | City name |\n| `--days` | integer | no | Number of forecast days |\n````\n\nTo skip skill generation, pass `--no-skill`:\n\n```bash\nfastmcp generate-cli weather --no-skill\n```\n\n## How It Works\n\nThe 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`.\n\nAt 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.\n\n### Parameter Handling\n\nParameters are mapped intelligently based on their complexity:\n\n**Simple types** (`string`, `integer`, `number`, `boolean`) become typed Python parameters with clean flags:\n```bash\npython cli.py call-tool get_forecast --city London --days 3\n```\n\n**Arrays of simple types** (`array` with `string`/`integer`/`number`/`boolean` items) become `list[T]` parameters that accept multiple flags:\n```bash\npython cli.py call-tool tag_items --tags python --tags fastapi --tags mcp\n```\n\n**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:\n```bash\npython cli.py call-tool create_user \\\n --name John \\\n --metadata '{\"role\": \"admin\", \"dept\": \"engineering\"}'\n```\n\nRequired parameters are mandatory flags; optional ones default to their schema default or `None`. Empty values are filtered out before calling the server.\n\nBeyond 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.\n\n## Editing the Output\n\nThe 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`.\n\nBeyond 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.\n\nThe 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:\n\n```bash\nuv run --with fastmcp python cli.py call-tool get_forecast --city London\n```\n" }, { "path": "docs/clients/logging.mdx", "content": "---\ntitle: Server Logging\nsidebarTitle: Logging\ndescription: Receive and handle log messages from MCP servers.\nicon: receipt\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to capture or process log messages sent by the server.\n\nMCP servers can emit log messages to clients. The client handles these through a log handler callback.\n\n## Log Handler\n\nProvide a `log_handler` function when creating the client:\n\n```python\nimport logging\nfrom fastmcp import Client\nfrom fastmcp.client.logging import LogMessage\n\nlogging.basicConfig(\n level=logging.INFO,\n format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'\n)\n\nlogger = logging.getLogger(__name__)\nLOGGING_LEVEL_MAP = logging.getLevelNamesMapping()\n\nasync def log_handler(message: LogMessage):\n \"\"\"Forward MCP server logs to Python's logging system.\"\"\"\n msg = message.data.get('msg')\n extra = message.data.get('extra')\n\n level = LOGGING_LEVEL_MAP.get(message.level.upper(), logging.INFO)\n logger.log(level, msg, extra=extra)\n\nclient = Client(\n \"my_mcp_server.py\",\n log_handler=log_handler,\n)\n```\n\nThe handler receives a `LogMessage` object:\n\n\n\n The log level\n\n\n\n The logger name (may be None)\n\n\n\n The log payload, containing `msg` and `extra` keys\n\n\n\n## Structured Logs\n\nThe `message.data` attribute is a dictionary containing the log payload. This enables structured logging with rich contextual information.\n\n```python\nasync def detailed_log_handler(message: LogMessage):\n msg = message.data.get('msg')\n extra = message.data.get('extra')\n\n if message.level == \"error\":\n print(f\"ERROR: {msg} | Details: {extra}\")\n elif message.level == \"warning\":\n print(f\"WARNING: {msg} | Details: {extra}\")\n else:\n print(f\"{message.level.upper()}: {msg}\")\n```\n\nThis structure is preserved even when logs are forwarded through a FastMCP proxy, making it useful for debugging multi-server applications.\n\n## Default Behavior\n\nIf 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.\n\n```python\nclient = Client(\"my_mcp_server.py\")\n\nasync with client:\n # Server logs are forwarded at proper severity automatically\n await client.call_tool(\"some_tool\")\n```\n" }, { "path": "docs/clients/notifications.mdx", "content": "---\ntitle: Notifications\nsidebarTitle: Notifications\ndescription: Handle server-sent notifications for list changes and other events.\nicon: envelope\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\";\n\n\n\nUse this when you need to react to server-side changes like tool list updates or resource modifications.\n\nMCP servers can send notifications to inform clients about state changes. The message handler provides a unified way to process these notifications.\n\n## Handling Notifications\n\nThe simplest approach is a function that receives all messages and filters for the notifications you care about:\n\n```python\nfrom fastmcp import Client\n\nasync def message_handler(message):\n \"\"\"Handle MCP notifications from the server.\"\"\"\n if hasattr(message, 'root'):\n method = message.root.method\n\n if method == \"notifications/tools/list_changed\":\n print(\"Tools have changed - refresh tool cache\")\n elif method == \"notifications/resources/list_changed\":\n print(\"Resources have changed\")\n elif method == \"notifications/prompts/list_changed\":\n print(\"Prompts have changed\")\n\nclient = Client(\n \"my_mcp_server.py\",\n message_handler=message_handler,\n)\n```\n\n## MessageHandler Class\n\nFor fine-grained targeting, subclass `MessageHandler` to use specific hooks:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.messages import MessageHandler\nimport mcp.types\n\nclass MyMessageHandler(MessageHandler):\n async def on_tool_list_changed(\n self, notification: mcp.types.ToolListChangedNotification\n ) -> None:\n \"\"\"Handle tool list changes.\"\"\"\n print(\"Tool list changed - refreshing available tools\")\n\n async def on_resource_list_changed(\n self, notification: mcp.types.ResourceListChangedNotification\n ) -> None:\n \"\"\"Handle resource list changes.\"\"\"\n print(\"Resource list changed\")\n\n async def on_prompt_list_changed(\n self, notification: mcp.types.PromptListChangedNotification\n ) -> None:\n \"\"\"Handle prompt list changes.\"\"\"\n print(\"Prompt list changed\")\n\nclient = Client(\n \"my_mcp_server.py\",\n message_handler=MyMessageHandler(),\n)\n```\n\n### Handler Template\n\n```python\nfrom fastmcp.client.messages import MessageHandler\nimport mcp.types\n\nclass MyMessageHandler(MessageHandler):\n async def on_message(self, message) -> None:\n \"\"\"Called for ALL messages (requests and notifications).\"\"\"\n pass\n\n async def on_notification(\n self, notification: mcp.types.ServerNotification\n ) -> None:\n \"\"\"Called for notifications (fire-and-forget).\"\"\"\n pass\n\n async def on_tool_list_changed(\n self, notification: mcp.types.ToolListChangedNotification\n ) -> None:\n \"\"\"Called when the server's tool list changes.\"\"\"\n pass\n\n async def on_resource_list_changed(\n self, notification: mcp.types.ResourceListChangedNotification\n ) -> None:\n \"\"\"Called when the server's resource list changes.\"\"\"\n pass\n\n async def on_prompt_list_changed(\n self, notification: mcp.types.PromptListChangedNotification\n ) -> None:\n \"\"\"Called when the server's prompt list changes.\"\"\"\n pass\n\n async def on_progress(\n self, notification: mcp.types.ProgressNotification\n ) -> None:\n \"\"\"Called for progress updates during long-running operations.\"\"\"\n pass\n\n async def on_logging_message(\n self, notification: mcp.types.LoggingMessageNotification\n ) -> None:\n \"\"\"Called for log messages from the server.\"\"\"\n pass\n```\n\n## List Change Notifications\n\nA practical example of maintaining a tool cache that refreshes when tools change:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.messages import MessageHandler\nimport mcp.types\n\nclass ToolCacheHandler(MessageHandler):\n def __init__(self):\n self.cached_tools = []\n\n async def on_tool_list_changed(\n self, notification: mcp.types.ToolListChangedNotification\n ) -> None:\n \"\"\"Clear tool cache when tools change.\"\"\"\n print(\"Tools changed - clearing cache\")\n self.cached_tools = [] # Force refresh on next access\n\nclient = Client(\"server.py\", message_handler=ToolCacheHandler())\n```\n\n## Server Requests\n\nWhile the message handler receives server-initiated requests, you should use dedicated callback parameters for most interactive scenarios:\n\n- **Sampling requests**: Use [`sampling_handler`](/clients/sampling)\n- **Elicitation requests**: Use [`elicitation_handler`](/clients/elicitation)\n- **Progress updates**: Use [`progress_handler`](/clients/progress)\n- **Log messages**: Use [`log_handler`](/clients/logging)\n\nThe message handler is primarily for monitoring and handling notifications rather than responding to requests.\n" }, { "path": "docs/clients/progress.mdx", "content": "---\ntitle: Progress Monitoring\nsidebarTitle: Progress\ndescription: Handle progress notifications from long-running server operations.\nicon: bars-progress\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to track progress of long-running operations.\n\nMCP servers can report progress during operations. The client receives these updates through a progress handler.\n\n## Progress Handler\n\nSet a handler when creating the client:\n\n```python\nfrom fastmcp import Client\n\nasync def progress_handler(\n progress: float,\n total: float | None,\n message: str | None\n) -> None:\n if total is not None:\n percentage = (progress / total) * 100\n print(f\"Progress: {percentage:.1f}% - {message or ''}\")\n else:\n print(f\"Progress: {progress} - {message or ''}\")\n\nclient = Client(\n \"my_mcp_server.py\",\n progress_handler=progress_handler\n)\n```\n\nThe handler receives three parameters:\n\n\n\n Current progress value\n\n\n\n Expected total value (may be None if unknown)\n\n\n\n Optional status message\n\n\n\n## Per-Call Handler\n\nOverride the client-level handler for specific tool calls:\n\n```python\nasync with client:\n result = await client.call_tool(\n \"long_running_task\",\n {\"param\": \"value\"},\n progress_handler=my_progress_handler\n )\n```\n" }, { "path": "docs/clients/prompts.mdx", "content": "---\ntitle: Getting Prompts\nsidebarTitle: Prompts\ndescription: Retrieve rendered message templates with automatic argument serialization.\nicon: message-lines\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to retrieve server-defined message templates for LLM interactions.\n\nPrompts are reusable message templates exposed by MCP servers. They can accept arguments to generate personalized message sequences for LLM interactions.\n\n## Basic Usage\n\nRequest a rendered prompt with `get_prompt()`:\n\n```python\nasync with client:\n # Simple prompt without arguments\n result = await client.get_prompt(\"welcome_message\")\n # result -> mcp.types.GetPromptResult\n\n # Access the generated messages\n for message in result.messages:\n print(f\"Role: {message.role}\")\n print(f\"Content: {message.content}\")\n```\n\nPass arguments to customize the prompt:\n\n```python\nasync with client:\n result = await client.get_prompt(\"user_greeting\", {\n \"name\": \"Alice\",\n \"role\": \"administrator\"\n })\n\n for message in result.messages:\n print(f\"Generated message: {message.content}\")\n```\n\n## Argument Serialization\n\n\n\nFastMCP automatically serializes complex arguments to JSON strings as required by the MCP specification. You can pass typed objects directly:\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass UserData:\n name: str\n age: int\n\nasync with client:\n result = await client.get_prompt(\"analyze_user\", {\n \"user\": UserData(name=\"Alice\", age=30), # Automatically serialized\n \"preferences\": {\"theme\": \"dark\"}, # Dict serialized\n \"scores\": [85, 92, 78], # List serialized\n \"simple_name\": \"Bob\" # Strings unchanged\n })\n```\n\nThe client handles serialization using `pydantic_core.to_json()` for consistent formatting. FastMCP servers automatically deserialize these JSON strings back to the expected types.\n\n## Working with Results\n\nThe `get_prompt()` method returns a `GetPromptResult` containing a list of messages:\n\n```python\nasync with client:\n result = await client.get_prompt(\"conversation_starter\", {\"topic\": \"climate\"})\n\n for i, message in enumerate(result.messages):\n print(f\"Message {i + 1}:\")\n print(f\" Role: {message.role}\")\n print(f\" Content: {message.content.text if hasattr(message.content, 'text') else message.content}\")\n```\n\nPrompts can generate different message types. System messages configure LLM behavior:\n\n```python\nasync with client:\n result = await client.get_prompt(\"system_configuration\", {\n \"role\": \"helpful assistant\",\n \"expertise\": \"python programming\"\n })\n\n # Access the returned messages\n message = result.messages[0]\n print(f\"Prompt: {message.content}\")\n```\n\nConversation templates generate multi-turn flows:\n\n```python\nasync with client:\n result = await client.get_prompt(\"interview_template\", {\n \"candidate_name\": \"Alice\",\n \"position\": \"Senior Developer\"\n })\n\n # Multiple messages for a conversation flow\n for message in result.messages:\n print(f\"{message.role}: {message.content}\")\n```\n\n## Version Selection\n\n\n\nWhen a server exposes multiple versions of a prompt, you can request a specific version:\n\n```python\nasync with client:\n # Get the highest version (default)\n result = await client.get_prompt(\"summarize\", {\"text\": \"...\"})\n\n # Get a specific version\n result_v1 = await client.get_prompt(\"summarize\", {\"text\": \"...\"}, version=\"1.0\")\n```\n\nSee [Metadata](/servers/versioning#version-discovery) for how to discover available versions.\n\n## Multi-Server Clients\n\nWhen using multi-server clients, prompts are accessible directly without prefixing:\n\n```python\nasync with client: # Multi-server client\n result1 = await client.get_prompt(\"weather_prompt\", {\"city\": \"London\"})\n result2 = await client.get_prompt(\"assistant_prompt\", {\"query\": \"help\"})\n```\n\n## Raw Protocol Access\n\nFor complete control, use `get_prompt_mcp()` which returns the full MCP protocol object:\n\n```python\nasync with client:\n result = await client.get_prompt_mcp(\"example_prompt\", {\"arg\": \"value\"})\n # result -> mcp.types.GetPromptResult\n```\n" }, { "path": "docs/clients/resources.mdx", "content": "---\ntitle: Reading Resources\nsidebarTitle: Resources\ndescription: Access static and templated data sources from MCP servers.\nicon: folder-open\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to read data from server-exposed resources like configuration files, generated content, or external data sources.\n\nResources 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.\n\n## Reading Resources\n\nRead a resource using its URI:\n\n```python\nasync with client:\n content = await client.read_resource(\"file:///path/to/README.md\")\n # content -> list[TextResourceContents | BlobResourceContents]\n\n # Access text content\n if hasattr(content[0], 'text'):\n print(content[0].text)\n\n # Access binary content\n if hasattr(content[0], 'blob'):\n print(f\"Binary data: {len(content[0].blob)} bytes\")\n```\n\nResource templates generate content based on URI parameters. The template defines a pattern like `weather://{{city}}/current`, and you fill in the parameters when reading:\n\n```python\nasync with client:\n # Read from a resource template\n weather_content = await client.read_resource(\"weather://london/current\")\n print(weather_content[0].text)\n```\n\n## Content Types\n\nResources return different content types depending on what they expose.\n\nText resources include configuration files, JSON data, and other human-readable content:\n\n```python\nasync with client:\n content = await client.read_resource(\"resource://config/settings.json\")\n\n for item in content:\n if hasattr(item, 'text'):\n print(f\"Text content: {item.text}\")\n print(f\"MIME type: {item.mimeType}\")\n```\n\nBinary resources include images, PDFs, and other non-text data:\n\n```python\nasync with client:\n content = await client.read_resource(\"resource://images/logo.png\")\n\n for item in content:\n if hasattr(item, 'blob'):\n print(f\"Binary content: {len(item.blob)} bytes\")\n print(f\"MIME type: {item.mimeType}\")\n\n # Save to file\n with open(\"downloaded_logo.png\", \"wb\") as f:\n f.write(item.blob)\n```\n\n## Multi-Server Clients\n\nWhen using multi-server clients, resource URIs are prefixed with the server name:\n\n```python\nasync with client: # Multi-server client\n weather_icons = await client.read_resource(\"weather://weather/icons/sunny\")\n templates = await client.read_resource(\"resource://assistant/templates/list\")\n```\n\n## Version Selection\n\n\n\nWhen a server exposes multiple versions of a resource, you can request a specific version:\n\n```python\nasync with client:\n # Read the highest version (default)\n content = await client.read_resource(\"data://config\")\n\n # Read a specific version\n content_v1 = await client.read_resource(\"data://config\", version=\"1.0\")\n```\n\nSee [Metadata](/servers/versioning#version-discovery) for how to discover available versions.\n\n## Raw Protocol Access\n\nFor complete control, use `read_resource_mcp()` which returns the full MCP protocol object:\n\n```python\nasync with client:\n result = await client.read_resource_mcp(\"resource://example\")\n # result -> mcp.types.ReadResourceResult\n```\n" }, { "path": "docs/clients/roots.mdx", "content": "---\ntitle: Client Roots\nsidebarTitle: Roots\ndescription: Provide local context and resource boundaries to MCP servers.\nicon: folder-tree\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to tell servers what local resources the client has access to.\n\nRoots inform servers about resources the client can provide. Servers can use this information to adjust behavior or provide more relevant responses.\n\n## Static Roots\n\nProvide a list of roots when creating the client:\n\n```python\nfrom fastmcp import Client\n\nclient = Client(\n \"my_mcp_server.py\",\n roots=[\"/path/to/root1\", \"/path/to/root2\"]\n)\n```\n\n## Dynamic Roots\n\nUse a callback to compute roots dynamically when the server requests them:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.roots import RequestContext\n\nasync def roots_callback(context: RequestContext) -> list[str]:\n print(f\"Server requested roots (Request ID: {context.request_id})\")\n return [\"/path/to/root1\", \"/path/to/root2\"]\n\nclient = Client(\n \"my_mcp_server.py\",\n roots=roots_callback\n)\n```\n" }, { "path": "docs/clients/sampling.mdx", "content": "---\ntitle: LLM Sampling\nsidebarTitle: Sampling\ndescription: Handle server-initiated LLM completion requests.\nicon: robot\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\";\n\n\n\nUse this when you need to respond to server requests for LLM completions.\n\nMCP 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.\n\n## Handler Template\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.sampling import SamplingMessage, SamplingParams, RequestContext\n\nasync def sampling_handler(\n messages: list[SamplingMessage],\n params: SamplingParams,\n context: RequestContext\n) -> str:\n \"\"\"\n Handle server requests for LLM completions.\n\n Args:\n messages: Conversation messages to send to the LLM\n params: Sampling parameters (temperature, max_tokens, etc.)\n context: Request context with metadata\n\n Returns:\n Generated text response from your LLM\n \"\"\"\n # Extract message content\n conversation = []\n for message in messages:\n content = message.content.text if hasattr(message.content, 'text') else str(message.content)\n conversation.append(f\"{message.role}: {content}\")\n\n # Use the system prompt if provided\n system_prompt = params.systemPrompt or \"You are a helpful assistant.\"\n\n # Integrate with your LLM service here\n return \"Generated response based on the messages\"\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=sampling_handler,\n)\n```\n\n## Handler Parameters\n\n\n\n The role of the message\n\n\n\n The content of the message. TextContent has a `.text` attribute.\n\n\n\n\n\n Optional system prompt the server wants to use\n\n\n\n Server preferences for model selection (hints, cost/speed/intelligence priorities)\n\n\n\n Sampling temperature\n\n\n\n Maximum tokens to generate\n\n\n\n Stop sequences for sampling\n\n\n\n Tools the LLM can use during sampling\n\n\n\n Tool usage behavior (`auto`, `required`, or `none`)\n\n\n\n## Built-in Handlers\n\nFastMCP provides built-in handlers for OpenAI, Anthropic, and Google Gemini APIs that support the full sampling API including tool use.\n\n### OpenAI Handler\n\n\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.sampling.handlers.openai import OpenAISamplingHandler\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=OpenAISamplingHandler(default_model=\"gpt-4o\"),\n)\n```\n\nFor OpenAI-compatible APIs (like local models):\n\n```python\nfrom openai import AsyncOpenAI\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=OpenAISamplingHandler(\n default_model=\"llama-3.1-70b\",\n client=AsyncOpenAI(base_url=\"http://localhost:8000/v1\"),\n ),\n)\n```\n\n\nInstall the OpenAI handler with `pip install fastmcp[openai]`.\n\n\n### Anthropic Handler\n\n\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=AnthropicSamplingHandler(default_model=\"claude-sonnet-4-5\"),\n)\n```\n\n\nInstall the Anthropic handler with `pip install fastmcp[anthropic]`.\n\n\n### Google Gemini Handler\n\n\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.sampling.handlers.google_genai import GoogleGenAISamplingHandler\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=GoogleGenAISamplingHandler(default_model=\"gemini-2.0-flash\"),\n)\n```\n\n\nInstall the Google Gemini handler with `pip install fastmcp[gemini]`.\n\n\n## Sampling Capabilities\n\nWhen you provide a `sampling_handler`, FastMCP automatically advertises full sampling capabilities to the server, including tool support. To disable tool support for simpler handlers:\n\n```python\nfrom mcp.types import SamplingCapability\n\nclient = Client(\n \"my_mcp_server.py\",\n sampling_handler=basic_handler,\n sampling_capabilities=SamplingCapability(), # No tool support\n)\n```\n\n## Tool Execution\n\nTool 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.\n\n\nTo 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.\n\n" }, { "path": "docs/clients/tasks.mdx", "content": "---\ntitle: Background Tasks\nsidebarTitle: Tasks\ndescription: Execute operations asynchronously and track their progress.\nicon: clock\ntag: \"NEW\"\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\nUse this when you need to run long operations asynchronously while doing other work.\n\nThe 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.\n\n## Requesting Background Execution\n\nPass `task=True` to run an operation as a background task:\n\n```python\nfrom fastmcp import Client\n\nasync with Client(server) as client:\n # Start a background task\n task = await client.call_tool(\"slow_computation\", {\"duration\": 10}, task=True)\n\n print(f\"Task started: {task.task_id}\")\n\n # Do other work while it runs...\n\n # Get the result when ready\n result = await task.result()\n```\n\nThis works with tools, resources, and prompts:\n\n```python\ntool_task = await client.call_tool(\"my_tool\", args, task=True)\nresource_task = await client.read_resource(\"file://large.txt\", task=True)\nprompt_task = await client.get_prompt(\"my_prompt\", args, task=True)\n```\n\n## Task API\n\nAll task types share a common interface.\n\n### Getting Results\n\nCall `await task.result()` or simply `await task` to block until the task completes:\n\n```python\ntask = await client.call_tool(\"analyze\", {\"text\": \"hello\"}, task=True)\n\n# Wait for result (blocking)\nresult = await task.result()\n# or: result = await task\n```\n\n### Checking Status\n\nCheck the current status without blocking:\n\n```python\nstatus = await task.status()\nprint(f\"{status.status}: {status.statusMessage}\")\n# status.status is \"working\", \"completed\", \"failed\", or \"cancelled\"\n```\n\n### Waiting with Control\n\nUse `task.wait()` for more control over waiting:\n\n```python\n# Wait up to 30 seconds for completion\nstatus = await task.wait(timeout=30.0)\n\n# Wait for a specific state\nstatus = await task.wait(state=\"completed\", timeout=30.0)\n```\n\n### Cancellation\n\nCancel a running task:\n\n```python\nawait task.cancel()\n```\n\n## Status Updates\n\nRegister callbacks to receive real-time status updates as the server reports progress:\n\n```python\ndef on_status_change(status):\n print(f\"Task {status.taskId}: {status.status} - {status.statusMessage}\")\n\ntask.on_status_change(on_status_change)\n\n# Async callbacks work too\nasync def on_status_async(status):\n await log_status(status)\n\ntask.on_status_change(on_status_async)\n```\n\n### Handler Template\n\n```python\nfrom fastmcp import Client\n\ndef status_handler(status):\n \"\"\"\n Handle task status updates.\n\n Args:\n status: Task status object with:\n - taskId: Unique task identifier\n - status: \"working\", \"completed\", \"failed\", or \"cancelled\"\n - statusMessage: Optional progress message from server\n \"\"\"\n if status.status == \"working\":\n print(f\"Progress: {status.statusMessage}\")\n elif status.status == \"completed\":\n print(\"Task completed\")\n elif status.status == \"failed\":\n print(f\"Task failed: {status.statusMessage}\")\n\ntask.on_status_change(status_handler)\n```\n\n## Graceful Degradation\n\nYou 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.\n\n```python\ntask = await client.call_tool(\"my_tool\", args, task=True)\n\nif task.returned_immediately:\n print(\"Server executed immediately (no background support)\")\nelse:\n print(\"Running in background\")\n\n# Either way, this works\nresult = await task.result()\n```\n\nThis lets you write task-aware client code without worrying about server capabilities.\n\n## Example\n\n```python\nimport asyncio\nfrom fastmcp import Client\n\nasync def main():\n async with Client(server) as client:\n # Start background task\n task = await client.call_tool(\n \"slow_computation\",\n {\"duration\": 10},\n task=True,\n )\n\n # Subscribe to updates\n def on_update(status):\n print(f\"Progress: {status.statusMessage}\")\n\n task.on_status_change(on_update)\n\n # Do other work while task runs\n print(\"Doing other work...\")\n await asyncio.sleep(2)\n\n # Wait for completion and get result\n result = await task.result()\n print(f\"Result: {result.content}\")\n\nasyncio.run(main())\n```\n\nSee [Server Background Tasks](/servers/tasks) for how to enable background task support on the server side.\n" }, { "path": "docs/clients/tools.mdx", "content": "---\ntitle: Calling Tools\nsidebarTitle: Tools\ndescription: Execute server-side tools and handle structured results.\nicon: wrench\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\n\n\nUse this when you need to execute server-side functions and process their results.\n\nTools are executable functions exposed by MCP servers. The client's `call_tool()` method executes a tool by name with arguments and returns structured results.\n\n## Basic Execution\n\n```python\nasync with client:\n result = await client.call_tool(\"add\", {\"a\": 5, \"b\": 3})\n # result -> CallToolResult with structured and unstructured data\n\n # Access structured data (automatically deserialized)\n print(result.data) # 8\n\n # Access traditional content blocks\n print(result.content[0].text) # \"8\"\n```\n\nArguments 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).\n\n## Execution Options\n\nThe `call_tool()` method supports timeout control and progress monitoring:\n\n```python\nasync with client:\n # With timeout (aborts if execution takes longer than 2 seconds)\n result = await client.call_tool(\n \"long_running_task\",\n {\"param\": \"value\"},\n timeout=2.0\n )\n\n # With progress handler\n result = await client.call_tool(\n \"long_running_task\",\n {\"param\": \"value\"},\n progress_handler=my_progress_handler\n )\n```\n\n## Structured Results\n\n\n\nTool 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.\n\n```python\nfrom datetime import datetime\nfrom uuid import UUID\n\nasync with client:\n result = await client.call_tool(\"get_weather\", {\"city\": \"London\"})\n\n # FastMCP reconstructs complete Python objects\n weather = result.data\n print(f\"Temperature: {weather.temperature}C at {weather.timestamp}\")\n\n # Complex types are properly deserialized\n assert isinstance(weather.timestamp, datetime)\n assert isinstance(weather.station_id, UUID)\n\n # Raw structured JSON is also available\n print(f\"Raw JSON: {result.structured_content}\")\n```\n\n\n\n Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). FastMCP exclusive.\n\n\n\n Standard MCP content blocks (`TextContent`, `ImageContent`, `AudioContent`, etc.).\n\n\n\n Standard MCP structured JSON data as sent by the server.\n\n\n\n Boolean indicating if the tool execution failed.\n\n\n\nFor tools without output schemas or when deserialization fails, `.data` will be `None`. Fall back to content blocks in that case:\n\n```python\nasync with client:\n result = await client.call_tool(\"legacy_tool\", {\"param\": \"value\"})\n\n if result.data is not None:\n print(f\"Structured: {result.data}\")\n else:\n for content in result.content:\n if hasattr(content, 'text'):\n print(f\"Text result: {content.text}\")\n```\n\n\nFastMCP 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`.\n\n\n## Error Handling\n\nBy default, `call_tool()` raises a `ToolError` if the tool execution fails:\n\n```python\nfrom fastmcp.exceptions import ToolError\n\nasync with client:\n try:\n result = await client.call_tool(\"potentially_failing_tool\", {\"param\": \"value\"})\n print(\"Tool succeeded:\", result.data)\n except ToolError as e:\n print(f\"Tool failed: {e}\")\n```\n\nTo handle errors manually instead of catching exceptions, disable automatic error raising:\n\n```python\nasync with client:\n result = await client.call_tool(\n \"potentially_failing_tool\",\n {\"param\": \"value\"},\n raise_on_error=False\n )\n\n if result.is_error:\n print(f\"Tool failed: {result.content[0].text}\")\n else:\n print(f\"Tool succeeded: {result.data}\")\n```\n\n## Sending Metadata\n\n\n\nThe `meta` parameter sends ancillary information alongside tool calls for observability, debugging, or client identification:\n\n```python\nasync with client:\n result = await client.call_tool(\n name=\"send_email\",\n arguments={\n \"to\": \"user@example.com\",\n \"subject\": \"Hello\",\n \"body\": \"Welcome!\"\n },\n meta={\n \"trace_id\": \"abc-123\",\n \"request_source\": \"mobile_app\"\n }\n )\n```\n\nSee [Client Metadata](/servers/context#client-metadata) to learn how servers access this data.\n\n## Raw Protocol Access\n\nFor complete control, use `call_tool_mcp()` which returns the raw MCP protocol object:\n\n```python\nasync with client:\n result = await client.call_tool_mcp(\"my_tool\", {\"param\": \"value\"})\n # result -> mcp.types.CallToolResult\n\n if result.isError:\n print(f\"Tool failed: {result.content}\")\n else:\n print(f\"Tool succeeded: {result.content}\")\n # Note: No automatic deserialization with call_tool_mcp()\n```\n" }, { "path": "docs/clients/transports.mdx", "content": "---\ntitle: Client Transports\nsidebarTitle: Transports\ndescription: Configure how clients connect to and communicate with MCP servers.\nicon: link\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\nTransports 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.\n\n## STDIO Transport\n\nSTDIO transport communicates with MCP servers through subprocess pipes. When using STDIO, your client launches and manages the server process, controlling its lifecycle and environment.\n\n\nSTDIO 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.\n\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StdioTransport\n\ntransport = StdioTransport(\n command=\"python\",\n args=[\"my_server.py\", \"--verbose\"],\n env={\"API_KEY\": \"secret\", \"LOG_LEVEL\": \"DEBUG\"},\n cwd=\"/path/to/server\"\n)\nclient = Client(transport)\n```\n\nFor convenience, the client can infer STDIO transport from file paths, though this limits configuration options:\n\n```python\nfrom fastmcp import Client\n\nclient = Client(\"my_server.py\") # Limited - no configuration options\n```\n\n### Environment Variables\n\nSince STDIO servers do not inherit your environment, you need strategies for passing configuration.\n\n**Selective forwarding** passes only the variables your server needs:\n\n```python\nimport os\nfrom fastmcp.client.transports import StdioTransport\n\nrequired_vars = [\"API_KEY\", \"DATABASE_URL\", \"REDIS_HOST\"]\nenv = {var: os.environ[var] for var in required_vars if var in os.environ}\n\ntransport = StdioTransport(command=\"python\", args=[\"server.py\"], env=env)\nclient = Client(transport)\n```\n\n**Loading from .env files** keeps configuration separate from code:\n\n```python\nfrom dotenv import dotenv_values\nfrom fastmcp.client.transports import StdioTransport\n\nenv = dotenv_values(\".env\")\ntransport = StdioTransport(command=\"python\", args=[\"server.py\"], env=env)\nclient = Client(transport)\n```\n\n### Session Persistence\n\nSTDIO transports maintain sessions across multiple client contexts by default (`keep_alive=True`). This reuses the same subprocess for multiple connections, improving performance.\n\n```python\nfrom fastmcp.client.transports import StdioTransport\n\ntransport = StdioTransport(command=\"python\", args=[\"server.py\"])\nclient = Client(transport)\n\nasync def efficient_multiple_operations():\n async with client:\n await client.ping()\n\n async with client: # Reuses the same subprocess\n await client.call_tool(\"process_data\", {\"file\": \"data.csv\"})\n```\n\nFor complete isolation between connections, disable session persistence:\n\n```python\ntransport = StdioTransport(command=\"python\", args=[\"server.py\"], keep_alive=False)\n```\n\n## HTTP Transport\n\n\n\nHTTP transport connects to MCP servers running as web services. This is the recommended transport for production deployments.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\ntransport = StreamableHttpTransport(\n url=\"https://api.example.com/mcp\",\n headers={\n \"Authorization\": \"Bearer your-token-here\",\n \"X-Custom-Header\": \"value\"\n }\n)\nclient = Client(transport)\n```\n\nFastMCP also provides authentication helpers:\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import BearerAuth\n\nclient = Client(\n \"https://api.example.com/mcp\",\n auth=BearerAuth(\"your-token-here\")\n)\n```\n\n### SSL Verification\n\nBy default, HTTPS connections verify the server's SSL certificate. You can customize this behavior with the `verify` parameter, which accepts the same values as [httpx](https://www.python-httpx.org/advanced/ssl/):\n\n```python\nfrom fastmcp import Client\n\n# Disable SSL verification (e.g., for self-signed certs in development)\nclient = Client(\"https://dev-server.internal/mcp\", verify=False)\n\n# Use a custom CA bundle\nclient = Client(\"https://corp-server.internal/mcp\", verify=\"/path/to/ca-bundle.pem\")\n\n# Use a custom SSL context for full control\nimport ssl\nctx = ssl.create_default_context()\nctx.load_verify_locations(\"/path/to/internal-ca.pem\")\nclient = Client(\"https://corp-server.internal/mcp\", verify=ctx)\n```\n\nThe `verify` parameter is also available directly on `StreamableHttpTransport` and `SSETransport`:\n\n```python\nfrom fastmcp.client.transports import StreamableHttpTransport\n\ntransport = StreamableHttpTransport(\n url=\"https://dev-server.internal/mcp\",\n verify=False,\n)\nclient = Client(transport)\n```\n\n### SSE Transport\n\nServer-Sent Events transport is maintained for backward compatibility. Use Streamable HTTP for new deployments unless you have specific infrastructure requirements.\n\n```python\nfrom fastmcp.client.transports import SSETransport\n\ntransport = SSETransport(\n url=\"https://api.example.com/sse\",\n headers={\"Authorization\": \"Bearer token\"}\n)\nclient = Client(transport)\n```\n\n## In-Memory Transport\n\nIn-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.\n\n```python\nfrom fastmcp import FastMCP, Client\nimport os\n\nmcp = FastMCP(\"TestServer\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n prefix = os.environ.get(\"GREETING_PREFIX\", \"Hello\")\n return f\"{prefix}, {name}!\"\n\nclient = Client(mcp)\n\nasync with client:\n result = await client.call_tool(\"greet\", {\"name\": \"World\"})\n```\n\n\nUnlike STDIO transports, in-memory servers share the same memory space and environment variables as your client code.\n\n\n## Multi-Server Configuration\n\n\n\nConnect to multiple servers defined in a configuration dictionary:\n\n```python\nfrom fastmcp import Client\n\nconfig = {\n \"mcpServers\": {\n \"weather\": {\n \"url\": \"https://weather.example.com/mcp\",\n \"transport\": \"http\"\n },\n \"assistant\": {\n \"command\": \"python\",\n \"args\": [\"./assistant.py\"],\n \"env\": {\"LOG_LEVEL\": \"INFO\"}\n }\n }\n}\n\nclient = Client(config)\n\nasync with client:\n # Tools are namespaced by server\n weather = await client.call_tool(\"weather_get_forecast\", {\"city\": \"NYC\"})\n answer = await client.call_tool(\"assistant_ask\", {\"question\": \"What?\"})\n```\n\n### Tool Transformations\n\nFastMCP supports tool transformations within the configuration. You can change names, descriptions, tags, and arguments for tools from a server.\n\n```python\nconfig = {\n \"mcpServers\": {\n \"weather\": {\n \"url\": \"https://weather.example.com/mcp\",\n \"transport\": \"http\",\n \"tools\": {\n \"weather_get_forecast\": {\n \"name\": \"miami_weather\",\n \"description\": \"Get the weather for Miami\",\n \"arguments\": {\n \"city\": {\n \"default\": \"Miami\",\n \"hide\": True,\n }\n }\n }\n }\n }\n }\n}\n```\n\nTo filter tools by tag, use `include_tags` or `exclude_tags` at the server level:\n\n```python\nconfig = {\n \"mcpServers\": {\n \"weather\": {\n \"url\": \"https://weather.example.com/mcp\",\n \"include_tags\": [\"forecast\"] # Only tools with this tag\n }\n }\n}\n```\n" }, { "path": "docs/community/README.md", "content": "# Community Section\n\nThis directory contains community-contributed content and showcases for FastMCP.\n\n## Structure\n\n- `showcase.mdx` - Main community showcase page featuring high-quality projects and examples\n\n## Adding Content\n\nTo add new community content:\n1. Create a new MDX file in this directory\n2. Update `docs.json` to include it in the navigation\n3. Follow the existing format for consistency\n\n## Guidelines\n\nCommunity content should:\n- Demonstrate best practices\n- Provide educational value\n- Include proper documentation\n- Be maintained and up-to-date" }, { "path": "docs/community/showcase.mdx", "content": "---\ntitle: 'Community Showcase'\ndescription: 'High-quality projects and examples from the FastMCP community'\nicon: 'users'\n---\n\nimport { YouTubeEmbed } from '/snippets/youtube-embed.mdx'\n\n## Join the Community\n\n\n Connect with other FastMCP developers, share your projects, and discuss ideas.\n\n\n## Featured Projects\n\nDiscover exemplary MCP servers and implementations created by our community. These projects demonstrate best practices and innovative uses of FastMCP.\n\n### Learning Resources\n\n\n A comprehensive educational example demonstrating FastMCP best practices with professional dual-transport server implementation, interactive test client, and detailed documentation.\n\n\n#### Video Tutorials\n\n**Build Remote MCP Servers w/ Python & FastMCP** - Claude Integrations Tutorial by Greg + Code\n\n\n\n**FastMCP — the best way to build an MCP server with Python** - Tutorial by ZazenCodes\n\n\n\n**Speedrun a MCP server for Claude Desktop (fastmcp)** - Tutorial by Nate from Prefect\n\n\n\n### Community Examples\n\nHave 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.\n\n## Contributing\n\nTo get your project featured:\n\n1. Ensure your project demonstrates best practices\n2. Include comprehensive documentation\n3. Add clear usage examples\n4. Open a discussion in our [GitHub Discussions](https://github.com/PrefectHQ/fastmcp/discussions)\n\nWe review submissions regularly and feature projects that provide value to the FastMCP community.\n\n## Further Reading\n\n- [Contrib Modules](/patterns/contrib) - Community-contributed modules that are distributed with FastMCP itself" }, { "path": "docs/css/banner.css", "content": "/* Banner styling -- improve readability with better contrast */\n#banner {\n background: #f1f5f9 !important;\n color: #1e293b !important;\n font-size: 0.95rem !important;\n font-weight: 600 !important;\n padding-top: 12px !important;\n padding-bottom: 12px !important;\n overflow: hidden !important;\n}\n\n#banner::before {\n content: \"\";\n position: absolute;\n top: 0;\n left: 0;\n width: 100%;\n height: 100%;\n background: linear-gradient(\n 90deg,\n rgba(6, 182, 212, 0.25) 0%,\n rgba(6, 182, 212, 0.05) 25%,\n rgba(6, 182, 212, 0.35) 50%,\n rgba(6, 182, 212, 0.08) 75%,\n rgba(6, 182, 212, 0.28) 100%\n );\n background-size: 300% 100%;\n animation: colorWave 14s ease-in-out infinite alternate;\n pointer-events: none;\n}\n\n.dark #banner {\n background: #475569 !important;\n color: #f1f5f9 !important;\n}\n\n.dark #banner::before {\n background: linear-gradient(\n 90deg,\n rgba(247, 37, 133, 0.35) 0%,\n rgba(247, 37, 133, 0.08) 25%,\n rgba(247, 37, 133, 0.45) 50%,\n rgba(247, 37, 133, 0.12) 75%,\n rgba(247, 37, 133, 0.38) 100%\n );\n background-size: 300% 100%;\n}\n\n@keyframes colorWave {\n 0% {\n background-position: 0% 0%;\n }\n 100% {\n background-position: 100% 0%;\n }\n}\n\n#banner * {\n color: #1e293b !important;\n margin: 0 !important;\n}\n\n.dark #banner * {\n color: #f1f5f9 !important;\n}\n\n@media (max-width: 767px) {\n #banner {\n font-size: 0.8rem !important;\n padding-top: 8px !important;\n padding-bottom: 8px !important;\n }\n}\n\n" }, { "path": "docs/css/python-sdk.css", "content": "a:has(svg.icon) {\n border: none !important;\n}" }, { "path": "docs/css/style.css", "content": "html:not([data-page-mode=\"wide\"]) #content-area {\n max-width: 44rem !important;\n}\n\nimg.nav-logo {\n max-width: 200px;\n}\n\n/* Code highlighting -- target only inline code elements, not code blocks */\np code:not(pre code),\ntable code:not(pre code),\n.prose code:not(pre code),\nli code:not(pre code),\nh1 code:not(pre code),\nh2 code:not(pre code),\nh3 code:not(pre code),\nh4 code:not(pre code),\nh5 code:not(pre code),\nh6 code:not(pre code) {\n color: #f72585 !important;\n background-color: rgba(247, 37, 133, 0.09);\n}\n\n/* V2 banner - inside content-container, breaks out of padding with negative margins */\n#v2-banner {\n display: block;\n background: linear-gradient(135deg, #4cc9f0 0%, #2d00f7 100%);\n color: white;\n text-align: center;\n padding: 10px 16px;\n font-size: 0.875rem;\n font-weight: 600;\n box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);\n margin: -2rem -2rem 1.5rem -2rem;\n width: calc(100% + 4rem);\n border-radius: 8px 8px 0 0;\n}\n\n#v2-banner a {\n color: white;\n text-decoration: underline;\n font-weight: 700;\n}\n\n#v2-banner a:hover {\n opacity: 0.9;\n}\n\n@media (min-width: 1024px) {\n #v2-banner {\n margin: -3rem -4rem 1.5rem -4rem;\n width: calc(100% + 8rem);\n }\n}\n\n.dark #v2-banner {\n background: linear-gradient(135deg, #2d00f7 0%, #4cc9f0 100%);\n}\n\n\n\n\n\n" }, { "path": "docs/css/version-badge.css", "content": "/* Version badge -- display a badge with the current version of the documentation */\n.version-badge {\n --color-text: #ff5400 !important;\n --color-bg: #fef2f2 !important;\n color: #ff5400 !important;\n background: #fef2f2 !important;\n border: 1px solid rgba(220, 38, 38, 0.3) !important;\n transition: box-shadow 0.2s, transform 0.15s;\n}\n\n.version-badge:hover {\n box-shadow: 0 2px 8px 0 rgba(160, 132, 252, 0.1);\n transform: translateY(-1px) scale(1.03);\n}\n\n.dark .version-badge {\n --color-text: #f1f5f9 !important;\n --color-bg: #334155 !important;\n color: #f1f5f9 !important;\n background: #334155 !important;\n border: 1px solid #64748b !important;\n}\n\n" }, { "path": "docs/deployment/http.mdx", "content": "---\ntitle: HTTP Deployment\nsidebarTitle: HTTP Deployment\ndescription: Deploy your FastMCP server over HTTP for remote access\nicon: server\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\";\n\n\nSTDIO 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.\n\n\nThis 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.\n\n## Choosing Your Approach\n\nFastMCP provides two ways to deploy your server as an HTTP service. Understanding the trade-offs helps you choose the right approach for your needs.\n\nThe **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.\n\nThe **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.\n\n### Direct HTTP Server\n\nThe 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.\n\n```python server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool\ndef process_data(input: str) -> str:\n \"\"\"Process data on the server\"\"\"\n return f\"Processed: {input}\"\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\", host=\"0.0.0.0\", port=8000)\n```\n\nRun your server with a simple Python command:\n```bash\npython server.py\n```\n\nYour server is now accessible at `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).\n\nThis 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.\n\n### ASGI Application\n\nFor 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.\n\n```python app.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool\ndef process_data(input: str) -> str:\n \"\"\"Process data on the server\"\"\"\n return f\"Processed: {input}\"\n\n# Create ASGI application\napp = mcp.http_app()\n```\n\nRun with any ASGI server - here's an example with Uvicorn:\n```bash\nuvicorn app:app --host 0.0.0.0 --port 8000\n```\n\nYour server is accessible at the same URL: `http://localhost:8000/mcp` (or use your server's actual IP address for remote access).\n\nThe 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.\n\n## Configuring Your Server\n\n### Custom Path\n\nBy 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.\n\n```python\n# Option 1: With mcp.run()\nmcp.run(transport=\"http\", host=\"0.0.0.0\", port=8000, path=\"/api/mcp/\")\n\n# Option 2: With ASGI app\napp = mcp.http_app(path=\"/api/mcp/\")\n```\n\nNow your server is accessible at `http://localhost:8000/api/mcp/`.\n\n### Authentication\n\n\nAuthentication is **highly recommended** for remote MCP servers. Some LLM clients require authentication for remote servers and will refuse to connect without it.\n\n\nFastMCP 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.\n\nIf you're mounting an authenticated server under a path prefix, see [Mounting Authenticated Servers](#mounting-authenticated-servers) below for important routing considerations.\n\n### Health Checks\n\nHealth 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.\n\n```python\nfrom starlette.responses import JSONResponse\n\n@mcp.custom_route(\"/health\", methods=[\"GET\"])\nasync def health_check(request):\n return JSONResponse({\"status\": \"healthy\", \"service\": \"mcp-server\"})\n```\n\nThis 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.\n\n### Custom Middleware\n\n\n\n\nAdd custom Starlette middleware to your FastMCP ASGI apps:\n\n```python\nfrom fastmcp import FastMCP\nfrom starlette.middleware import Middleware\nfrom starlette.middleware.cors import CORSMiddleware\n\n# Create your FastMCP server\nmcp = FastMCP(\"MyServer\")\n\n# Define middleware\nmiddleware = [\n Middleware(\n CORSMiddleware,\n allow_origins=[\"*\"],\n allow_methods=[\"*\"],\n allow_headers=[\"*\"],\n )\n]\n\n# Create ASGI app with middleware\nhttp_app = mcp.http_app(middleware=middleware)\n```\n\n### CORS for Browser-Based Clients\n\n\nMost 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.\n\n\nCORS (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).\n\nBrowser-based MCP clients that need CORS include:\n\n- **MCP Inspector** - Browser-based debugging tool for testing MCP servers\n- **Custom browser-based MCP clients** - If you're building a web app that directly connects to MCP servers\n\nFor these scenarios, add CORS middleware with the specific headers required for MCP protocol:\n\n```python\nfrom fastmcp import FastMCP\nfrom starlette.middleware import Middleware\nfrom starlette.middleware.cors import CORSMiddleware\n\nmcp = FastMCP(\"MyServer\")\n\n# Configure CORS for browser-based clients\nmiddleware = [\n Middleware(\n CORSMiddleware,\n allow_origins=[\"*\"], # Allow all origins; use specific origins for security\n allow_methods=[\"GET\", \"POST\", \"DELETE\", \"OPTIONS\"],\n allow_headers=[\n \"mcp-protocol-version\",\n \"mcp-session-id\",\n \"Authorization\",\n \"Content-Type\",\n ],\n expose_headers=[\"mcp-session-id\"],\n )\n]\n\napp = mcp.http_app(middleware=middleware)\n```\n\n**Key configuration details:**\n\n- **`allow_origins`**: Specify exact origins (e.g., `[\"http://localhost:3000\"]`) rather than `[\"*\"]` for production deployments\n- **`allow_headers`**: Must include `mcp-protocol-version`, `mcp-session-id`, and `Authorization` (for authenticated servers)\n- **`expose_headers`**: Must include `mcp-session-id` so JavaScript can read the session ID from responses and send it in subsequent requests\n\nWithout `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.\n\n\n**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.\n\n\n### SSE Polling for Long-Running Operations\n\n\n\n\nThis feature only applies to the **StreamableHTTP transport** (the default for `http_app()`). It does not apply to the legacy SSE transport (`transport=\"sse\"`).\n\n\nWhen 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.\n\nTo enable SSE polling, configure an `EventStore` when creating your HTTP application:\n\n```python\nfrom fastmcp import FastMCP, Context\nfrom fastmcp.server.event_store import EventStore\n\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool\nasync def long_running_task(ctx: Context) -> str:\n \"\"\"A task that takes several minutes to complete.\"\"\"\n for i in range(100):\n await ctx.report_progress(i, 100)\n\n # Periodically close the connection to avoid load balancer timeouts\n # Client will automatically reconnect and resume receiving progress\n if i % 30 == 0 and i > 0:\n await ctx.close_sse_stream()\n\n await do_expensive_work()\n\n return \"Done!\"\n\n# Configure with EventStore for resumability\nevent_store = EventStore()\napp = mcp.http_app(\n event_store=event_store,\n retry_interval=2000, # Client reconnects after 2 seconds\n)\n```\n\n**How it works:**\n\n1. When `event_store` is configured, the server stores all events (progress updates, results) with unique IDs\n2. Calling `ctx.close_sse_stream()` gracefully closes the HTTP connection\n3. The client automatically reconnects with a `Last-Event-ID` header\n4. The server replays any events the client missed during the disconnection\n\nThe `retry_interval` parameter (in milliseconds) controls how long clients wait before reconnecting. Choose a value that balances responsiveness with server load.\n\n\n`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.\n\n\n#### Custom Storage Backends\n\nBy 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:\n\n```python\nfrom fastmcp.server.event_store import EventStore\nfrom key_value.aio.stores.redis import RedisStore\n\n# Use Redis for distributed deployments\nredis_store = RedisStore(url=\"redis://localhost:6379\")\nevent_store = EventStore(\n storage=redis_store,\n max_events_per_stream=100, # Keep last 100 events per stream\n ttl=3600, # Events expire after 1 hour\n)\n\napp = mcp.http_app(event_store=event_store)\n```\n\n## Integration with Web Frameworks\n\nIf 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.\n\n### Mounting in Starlette\n\nMount your FastMCP server in a Starlette application:\n\n```python\nfrom fastmcp import FastMCP\nfrom starlette.applications import Starlette\nfrom starlette.routing import Mount\n\n# Create your FastMCP server\nmcp = FastMCP(\"MyServer\")\n\n@mcp.tool\ndef analyze(data: str) -> dict:\n return {\"result\": f\"Analyzed: {data}\"}\n\n# Create the ASGI app\nmcp_app = mcp.http_app(path='/mcp')\n\n# Create a Starlette app and mount the MCP server\napp = Starlette(\n routes=[\n Mount(\"/mcp-server\", app=mcp_app),\n # Add other routes as needed\n ],\n lifespan=mcp_app.lifespan,\n)\n```\n\nThe MCP endpoint will be available at `/mcp-server/mcp/` of the resulting Starlette app.\n\n\nFor 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.\n\n\n#### Nested Mounts\n\nYou can create complex routing structures by nesting mounts:\n\n```python\nfrom fastmcp import FastMCP\nfrom starlette.applications import Starlette\nfrom starlette.routing import Mount\n\n# Create your FastMCP server\nmcp = FastMCP(\"MyServer\")\n\n# Create the ASGI app\nmcp_app = mcp.http_app(path='/mcp')\n\n# Create nested application structure\ninner_app = Starlette(routes=[Mount(\"/inner\", app=mcp_app)])\napp = Starlette(\n routes=[Mount(\"/outer\", app=inner_app)],\n lifespan=mcp_app.lifespan,\n)\n```\n\nIn this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.\n\n### FastAPI Integration\n\nFor 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).\n\nHere's a quick example showing how to add MCP to an existing FastAPI application:\n\n```python\nfrom fastapi import FastAPI\nfrom fastmcp import FastMCP\n\n# Create your MCP server\nmcp = FastMCP(\"API Tools\")\n\n@mcp.tool\ndef query_database(query: str) -> dict:\n \"\"\"Run a database query\"\"\"\n return {\"result\": \"data\"}\n\n# Create the MCP ASGI app with path=\"/\" since we'll mount at /mcp\nmcp_app = mcp.http_app(path=\"/\")\n\n# Create FastAPI app with MCP lifespan (required for session management)\napi = FastAPI(lifespan=mcp_app.lifespan)\n\n@api.get(\"/api/status\")\ndef status():\n return {\"status\": \"ok\"}\n\n# Mount MCP at /mcp\napi.mount(\"/mcp\", mcp_app)\n\n# Run with: uvicorn app:api --host 0.0.0.0 --port 8000\n```\n\nYour existing API remains at `http://localhost:8000/api` while MCP is available at `http://localhost:8000/mcp`.\n\n\nJust 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.\n\n\n## Mounting Authenticated Servers\n\n\n\n\nThis section only applies if you're **mounting an OAuth-protected FastMCP server under a path prefix** (like `/api`) inside another application using `Mount()`.\n\nIf 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.\n\n\nOAuth 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.\n\n\n**Common Mistakes to Avoid:**\n\n1. **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.\n\n2. **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.\n\n ✅ **Correct:**\n ```python\n base_url = \"http://localhost:8000/api\"\n mcp_path = \"/mcp\"\n # Result: /api/mcp\n ```\n\n ❌ **Wrong:**\n ```python\n base_url = \"http://localhost:8000/api\"\n mcp_path = \"/api/mcp\"\n # Result: /api/api/mcp (double prefix!)\n ```\n\nFollow the configuration instructions below to set up mounting correctly.\n\n\n\n**CORS Middleware Conflicts:**\n\nIf 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).\n\nFastMCP 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.\n\n\n### Route Types\n\nOAuth-protected MCP servers expose two categories of routes:\n\n**Operational routes** handle the OAuth flow and MCP protocol:\n- `/authorize` - OAuth authorization endpoint\n- `/token` - Token exchange endpoint\n- `/auth/callback` - OAuth callback handler\n- `/mcp` - MCP protocol endpoint\n\n**Discovery routes** provide metadata for OAuth clients:\n- `/.well-known/oauth-authorization-server` - Authorization server metadata\n- `/.well-known/oauth-protected-resource/*` - Protected resource metadata\n\nWhen you mount your MCP app under a prefix, operational routes move with it, but discovery routes must stay at root level for RFC compliance.\n\n### Configuration Parameters\n\nThree parameters control where routes are located and how they combine:\n\n**`base_url`** tells clients where to find operational endpoints. This includes any Starlette `Mount()` path prefix (e.g., `/api`):\n\n```python\nbase_url=\"http://localhost:8000/api\" # Includes mount prefix\n```\n\n**`mcp_path`** is the internal FastMCP endpoint path, which gets appended to `base_url`:\n\n```python\nmcp_path=\"/mcp\" # Internal MCP path, NOT the mount prefix\n```\n\n**`issuer_url`** (optional) controls the authorization server identity for OAuth discovery. Defaults to `base_url`.\n\n```python\n# Usually not needed - just set base_url and it works\nissuer_url=\"http://localhost:8000\" # Only if you want root-level discovery\n```\n\nWhen `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`.\n\n**Key Invariant:** `base_url + mcp_path = actual externally-accessible MCP URL`\n\nExample:\n- `base_url`: `http://localhost:8000/api` (mount prefix `/api`)\n- `mcp_path`: `/mcp` (internal path)\n- Result: `http://localhost:8000/api/mcp` (final MCP endpoint)\n\nNote 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`.\n\n### Mounting Strategy\n\nWhen mounting an OAuth-protected server under a path prefix, declare your URLs upfront to make the relationships clear:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.auth.providers.github import GitHubProvider\nfrom starlette.applications import Starlette\nfrom starlette.routing import Mount\n\n# Define the routing structure\nROOT_URL = \"http://localhost:8000\"\nMOUNT_PREFIX = \"/api\"\nMCP_PATH = \"/mcp\"\n```\n\nCreate the auth provider with `base_url`:\n\n```python\nauth = GitHubProvider(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n base_url=f\"{ROOT_URL}{MOUNT_PREFIX}\", # Operational endpoints under prefix\n # issuer_url defaults to base_url - path-aware discovery works automatically\n)\n```\n\nCreate the MCP app, which generates operational routes at the specified path:\n\n```python\nmcp = FastMCP(\"Protected Server\", auth=auth)\nmcp_app = mcp.http_app(path=MCP_PATH)\n```\n\nRetrieve the discovery routes from the auth provider. The `mcp_path` argument should match the path used when creating the MCP app:\n\n```python\nwell_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)\n```\n\nFinally, mount everything in the Starlette app with discovery routes at root and the MCP app under the prefix:\n\n```python\napp = Starlette(\n routes=[\n *well_known_routes, # Discovery routes at root level\n Mount(MOUNT_PREFIX, app=mcp_app), # Operational routes under prefix\n ],\n lifespan=mcp_app.lifespan,\n)\n```\n\nThis configuration produces the following URL structure:\n\n- MCP endpoint: `http://localhost:8000/api/mcp`\n- OAuth authorization: `http://localhost:8000/api/authorize`\n- OAuth callback: `http://localhost:8000/api/auth/callback`\n- Authorization server metadata: `http://localhost:8000/.well-known/oauth-authorization-server/api`\n- Protected resource metadata: `http://localhost:8000/.well-known/oauth-protected-resource/api/mcp`\n\nBoth discovery endpoints use path-aware URLs per RFC 8414 and RFC 9728, matching the `base_url` path.\n\n### Complete Example\n\nHere's a complete working example showing all the pieces together:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.auth.providers.github import GitHubProvider\nfrom starlette.applications import Starlette\nfrom starlette.routing import Mount\nimport uvicorn\n\n# Define routing structure\nROOT_URL = \"http://localhost:8000\"\nMOUNT_PREFIX = \"/api\"\nMCP_PATH = \"/mcp\"\n\n# Create OAuth provider\nauth = GitHubProvider(\n client_id=\"your-client-id\",\n client_secret=\"your-client-secret\",\n base_url=f\"{ROOT_URL}{MOUNT_PREFIX}\",\n # issuer_url defaults to base_url - path-aware discovery works automatically\n)\n\n# Create MCP server\nmcp = FastMCP(\"Protected Server\", auth=auth)\n\n@mcp.tool\ndef analyze(data: str) -> dict:\n return {\"result\": f\"Analyzed: {data}\"}\n\n# Create MCP app\nmcp_app = mcp.http_app(path=MCP_PATH)\n\n# Get discovery routes for root level\nwell_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)\n\n# Assemble the application\napp = Starlette(\n routes=[\n *well_known_routes,\n Mount(MOUNT_PREFIX, app=mcp_app),\n ],\n lifespan=mcp_app.lifespan,\n)\n\nif __name__ == \"__main__\":\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n```\n\nFor more details on OAuth authentication, see the [Authentication guide](/servers/auth).\n\n## Production Deployment\n\n### Running with Uvicorn\n\nWhen deploying to production, you'll want to optimize your server for performance and reliability. Uvicorn provides several options to improve your server's capabilities:\n\n```bash\n# Run with basic configuration\nuvicorn app:app --host 0.0.0.0 --port 8000\n\n# Run with multiple workers for production (requires stateless mode - see below)\nuvicorn app:app --host 0.0.0.0 --port 8000 --workers 4\n```\n\n### Horizontal Scaling\n\n\n\nWhen 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.\n\n#### Understanding Sessions\n\nBy 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.\n\nThis works perfectly for single-instance deployments. However, sessions are stored in memory on each server instance, which creates challenges when scaling horizontally.\n\n#### Without Stateless Mode\n\nWhen running multiple server instances behind a load balancer (Traefik, nginx, HAProxy, Kubernetes, etc.), requests from the same client may be routed to different instances:\n\n1. Client connects to Instance A → session created on Instance A\n2. Next request routes to Instance B → session doesn't exist → **request fails**\n\nYou might expect sticky sessions (session affinity) to solve this, but they don't work reliably with MCP clients.\n\n\n**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.\n\n\n#### Enabling Stateless Mode\n\nFor horizontally scaled deployments, enable stateless HTTP mode. In stateless mode, each request creates a fresh transport context, eliminating the need for session affinity entirely.\n\n**Option 1: Via constructor**\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool\ndef process(data: str) -> str:\n return f\"Processed: {data}\"\n\napp = mcp.http_app(stateless_http=True)\n```\n\n**Option 2: Via `run()`**\n\n```python\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\", stateless_http=True)\n```\n\n**Option 3: Via environment variable**\n\n```bash\nFASTMCP_STATELESS_HTTP=true uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4\n```\n\n### Environment Variables\n\nProduction 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.\n\nHere's an example using bearer token authentication (though OAuth is recommended for production):\n\n```python\nimport os\nfrom fastmcp import FastMCP\nfrom fastmcp.server.auth import BearerTokenAuth\n\n# Read configuration from environment\nauth_token = os.environ.get(\"MCP_AUTH_TOKEN\")\nif auth_token:\n auth = BearerTokenAuth(token=auth_token)\n mcp = FastMCP(\"Production Server\", auth=auth)\nelse:\n mcp = FastMCP(\"Production Server\")\n\napp = mcp.http_app()\n```\n\nDeploy with your secrets safely stored in environment variables:\n```bash\nMCP_AUTH_TOKEN=secret uvicorn app:app --host 0.0.0.0 --port 8000\n```\n\n### OAuth Token Security\n\n\n\nIf 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.\n\n**Default Behavior (Development Only):**\n\nBy default, FastMCP automatically manages cryptographic keys:\n- **Mac/Windows**: Keys are generated and stored in your system keyring, surviving server restarts. Suitable **only** for development and local testing.\n- **Linux**: Keys are ephemeral (random salt at startup), so tokens are invalidated on restart.\n\nThis automatic approach is convenient for development but not suitable for production deployments.\n\n**For Production:**\n\nProduction 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:\n\n1. **Explicit JWT signing key** for signing tokens issued to clients\n3. **Persistent network-accessible storage** for upstream tokens (wrapped in `FernetEncryptionWrapper` to encrypt sensitive data at rest)\n\n**Configuration:**\n\nAdd two parameters to your auth provider:\n\n```python {8-12}\nfrom key_value.aio.stores.redis import RedisStore\nfrom key_value.aio.wrappers.encryption import FernetEncryptionWrapper\nfrom cryptography.fernet import Fernet\n\nauth = GitHubProvider(\n client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n jwt_signing_key=os.environ[\"JWT_SIGNING_KEY\"],\n client_storage=FernetEncryptionWrapper(\n key_value=RedisStore(host=\"redis.example.com\", port=6379),\n fernet=Fernet(os.environ[\"STORAGE_ENCRYPTION_KEY\"])\n ),\n base_url=\"https://your-server.com\" # use HTTPS\n)\n```\n\nBoth 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.\n\nFor more details on the token architecture and key management, see [OAuth Proxy Key and Storage Management](/servers/auth/oauth-proxy#key-and-storage-management).\n\n## Reverse Proxy (nginx)\n\nIn 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.\n\n### Running FastMCP as a Linux Service\n\nBefore 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.\n\nCreate a file at `/etc/systemd/system/fastmcp.service`:\n\n```ini\n[Unit]\nDescription=FastMCP Server\nAfter=network.target\n\n[Service]\nUser=www-data\nGroup=www-data\nWorkingDirectory=/opt/fastmcp\nExecStart=/opt/fastmcp/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000\nRestart=always\nRestartSec=5\nEnvironment=\"PATH=/opt/fastmcp/.venv/bin\"\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start the service:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable fastmcp\nsudo systemctl start fastmcp\n```\n\nThis 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.\n\n### nginx Configuration\n\nFastMCP'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.\n\nCreate a site configuration at `/etc/nginx/sites-available/fastmcp`:\n\n```nginx\nserver {\n listen 80;\n server_name mcp.example.com;\n\n # Redirect HTTP to HTTPS\n return 301 https://$host$request_uri;\n}\n\nserver {\n listen 443 ssl;\n server_name mcp.example.com;\n\n ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;\n ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;\n\n location / {\n proxy_pass http://127.0.0.1:8000;\n proxy_http_version 1.1;\n proxy_set_header Connection '';\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n\n # Required for SSE (Server-Sent Events) streaming\n proxy_buffering off;\n proxy_cache off;\n\n # Allow long-lived connections for streaming responses\n proxy_read_timeout 300s;\n proxy_send_timeout 300s;\n }\n}\n```\n\nEnable the site and reload nginx:\n\n```bash\nsudo ln -s /etc/nginx/sites-available/fastmcp /etc/nginx/sites-enabled/\nsudo nginx -t\nsudo systemctl reload nginx\n```\n\nYour FastMCP server is now accessible at `https://mcp.example.com/mcp`.\n\n\n**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.\n\n\n### Key Considerations\n\nWhen deploying FastMCP behind a reverse proxy, keep these points in mind:\n\n- **Disable buffering**: SSE requires `proxy_buffering off` so events reach clients immediately. This is the single most important setting.\n- **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.\n- **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.\n- **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.\n- **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.\n\n### Mounting Under a Path Prefix\n\nIf 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:\n\n```nginx\nlocation /api/ {\n proxy_pass http://127.0.0.1:8000/;\n proxy_http_version 1.1;\n proxy_set_header Connection '';\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n\n # Required for SSE streaming\n proxy_buffering off;\n proxy_cache off;\n proxy_read_timeout 300s;\n proxy_send_timeout 300s;\n}\n```\n\nNote 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.\n\n## Testing Your Deployment\n\nOnce 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.\n\n## Hosting Your Server\n\nThis 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:\n\n- **Cloud VMs** (AWS EC2, Google Compute Engine, Azure VMs)\n- **Container platforms** (Cloud Run, Container Instances, ECS) \n- **Platform-as-a-Service** (Railway, Render, Vercel)\n- **Edge platforms** (Cloudflare Workers)\n- **Kubernetes clusters** (self-managed or managed)\n\nThe 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).\n" }, { "path": "docs/deployment/prefect-horizon.mdx", "content": "---\ntitle: Prefect Horizon\nsidebarTitle: Prefect Horizon\ndescription: The MCP platform from the FastMCP team\nicon: cloud\n---\n\n[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.\n\nHorizon 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.\n\n\nHorizon is free for personal projects. Enterprise governance features are available for teams deploying to thousands of users.\n\n\n## The Platform\n\nHorizon is organized into four integrated pillars:\n\n- **Deploy**: Managed hosting with CI/CD, scaling, monitoring, and rollbacks. Push code and get a live, governed endpoint in 60 seconds.\n- **Registry**: A central catalog of MCP servers across your organization—first-party, third-party, and curated remix servers composed from multiple sources.\n- **Gateway**: Role-based access control, authentication, and audit logs. Define what agents can see and do at the tool level.\n- **Agents**: A permissioned chat interface for interacting with any MCP server or curated combination of servers.\n\nThis guide focuses on **Horizon Deploy**, the managed hosting layer that gives you the fastest path from a FastMCP server to a production URL.\n\n## Prerequisites\n\nTo 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.\n\nYour repo can be public or private, but must include at least a Python file containing a FastMCP server instance.\n\n\nTo verify your file is compatible with Horizon, run `fastmcp inspect ` to see what Horizon will see when it runs your server.\n\n\nIf 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.\n\nFor example, a minimal server file might look like:\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"MyServer\")\n\n@mcp.tool\ndef hello(name: str) -> str:\n return f\"Hello, {name}!\"\n```\n\n## Getting Started\n\nThere are just three steps to deploying a server to Horizon:\n\n### Step 1: Select a Repository\n\nVisit [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.\n\n\"Horizon\n\n### Step 2: Configure Your Server\n\nNext, you'll configure how Horizon should build and deploy your server.\n\n\"Horizon\n\nThe configuration screen lets you specify:\n- **Server name**: A unique name for your server. This determines your server's URL.\n- **Description**: A brief description of what your server does.\n- **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.\n- **Authentication**: When enabled, only authenticated users in your organization can connect. Horizon handles all the OAuth complexity for you.\n\nHorizon will automatically detect your server's Python dependencies from either a `requirements.txt` or `pyproject.toml` file.\n\n### Step 3: Deploy and Connect\n\nClick **Deploy Server** and Horizon will clone your repository, build your server, and deploy it to a unique URL—typically in under 60 seconds.\n\n\"Horizon\n\nOnce deployed, your server is accessible at a URL like:\n\n```\nhttps://your-server-name.fastmcp.app/mcp\n```\n\nHorizon 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.\n\n## Testing Your Server\n\nHorizon provides two ways to verify your server is working before connecting external clients.\n\n### Inspector\n\nThe 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.\n\n### ChatMCP\n\nFor 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.\n\n\"Horizon\n\nChatMCP 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.\n\n## Horizon Agents\n\nBeyond 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.\n\n\"Horizon\n\nTo create an agent:\n1. Navigate to **Agents** in the sidebar\n2. Click **Create Agent** and give it a name and description\n3. Add MCP servers to the agent—these can be servers you've deployed to Horizon or external servers in the registry\n\nOnce configured, you can chat with your agent directly in Horizon:\n\n\"Chatting\n\nAgents 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.\n" }, { "path": "docs/deployment/running-server.mdx", "content": "---\ntitle: Running Your Server\nsidebarTitle: Running Your Server\ndescription: Learn how to run your FastMCP server locally for development and testing\nicon: circle-play\n---\n\nimport { VersionBadge } from '/snippets/version-badge.mdx'\n\nFastMCP 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.\n\n## The `run()` Method\n\nEvery 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.\n\n\nFor 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.\n\n\n```python {9-10} my_server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(name=\"MyServer\")\n\n@mcp.tool\ndef hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\nYou can now run this MCP server by executing `python my_server.py`.\n\n## Transport Protocols\n\nMCP 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.\n\nThe 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.\n\n### STDIO Transport (Default)\n\nSTDIO (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.\n\nWith 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.\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"MyServer\")\n\n@mcp.tool\ndef hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run() # Uses STDIO transport by default\n```\n\nSTDIO is ideal for:\n- Local development and testing\n- Claude Desktop integration\n- Command-line tools\n- Single-user applications\n\n### HTTP Transport (Streamable)\n\nHTTP 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.\n\nThe 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.\n\nTo use HTTP transport, specify it in the `run()` method along with networking options:\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"MyServer\")\n\n@mcp.tool\ndef hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n # Start an HTTP server on port 8000\n mcp.run(transport=\"http\", host=\"127.0.0.1\", port=8000)\n```\n\nYour server is now accessible at `http://localhost:8000/mcp`. This URL is the MCP endpoint that clients will connect to. HTTP transport enables:\n- Network accessibility\n- Multiple concurrent clients\n- Integration with web infrastructure\n- Remote deployment capabilities\n\nFor production HTTP deployment with authentication and advanced configuration, see the [HTTP Deployment](/deployment/http) guide.\n\n### SSE Transport (Legacy)\n\nServer-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.\n\n```python\nif __name__ == \"__main__\":\n # SSE transport - use HTTP instead for new projects\n mcp.run(transport=\"sse\", host=\"127.0.0.1\", port=8000)\n```\n\nWe 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.\n\n### Choosing the Right Transport\n\nEach 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.\n\nConsider 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.\n\n## The FastMCP CLI\n\nFastMCP 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:\n\n```bash\nfastmcp run server.py\n```\n\nThe 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.\n\n### Dependency Management\n\nThe CLI integrates with `uv` to manage Python environments and dependencies:\n\n```bash\n# Run with a specific Python version\nfastmcp run server.py --python 3.11\n\n# Run with additional packages\nfastmcp run server.py --with pandas --with numpy\n\n# Run with dependencies from a requirements file\nfastmcp run server.py --with-requirements requirements.txt\n\n# Combine multiple options\nfastmcp run server.py --python 3.10 --with httpx --transport http\n\n# Run within a specific project directory\nfastmcp run server.py --project /path/to/project\n```\n\n\nWhen using `--python`, `--with`, `--project`, or `--with-requirements`, the server runs via `uv run` subprocess instead of using your local environment.\n\n\n### Passing Arguments to Servers\n\nWhen servers accept command line arguments (using argparse, click, or other libraries), you can pass them after `--`:\n\n```bash\nfastmcp run config_server.py -- --config config.json\nfastmcp run database_server.py -- --database-path /tmp/db.sqlite --debug\n```\n\nThis is useful for servers that need configuration files, database paths, API keys, or other runtime options.\n\nFor more CLI features including development mode with the MCP Inspector, see the [CLI documentation](/cli/running).\n\n### Auto-Reload for Development\n\n\n\nDuring development, you can use the `--reload` flag to automatically restart your server when source files change:\n\n```bash\nfastmcp run server.py --reload\n```\n\nThe 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.\n\n```bash\n# Watch specific directories for changes\nfastmcp run server.py --reload --reload-dir ./src --reload-dir ./lib\n\n# Combine with other options\nfastmcp run server.py --reload --transport http --port 8080\n```\n\n\nAuto-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.\n\n\nSSE transport does not support auto-reload due to session limitations. Use HTTP transport instead if you need both network access and auto-reload.\n\n### Async Usage\n\nFastMCP 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.\n\nFor applications that are already running in an async context, FastMCP provides the `run_async()` method:\n\n```python {10-12}\nfrom fastmcp import FastMCP\nimport asyncio\n\nmcp = FastMCP(name=\"MyServer\")\n\n@mcp.tool\ndef hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nasync def main():\n # Use run_async() in async contexts\n await mcp.run_async(transport=\"http\", port=8000)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n\nThe `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.\n\nAlways use `run_async()` inside async functions and `run()` in synchronous contexts.\n\n\nBoth `run()` and `run_async()` accept the same transport arguments, so all the examples above apply to both methods.\n\n## Custom Routes\n\nWhen 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:\n\n```python\nfrom fastmcp import FastMCP\nfrom starlette.requests import Request\nfrom starlette.responses import PlainTextResponse\n\nmcp = FastMCP(\"MyServer\")\n\n@mcp.custom_route(\"/health\", methods=[\"GET\"])\nasync def health_check(request: Request) -> PlainTextResponse:\n return PlainTextResponse(\"OK\")\n\n@mcp.tool\ndef process(data: str) -> str:\n return f\"Processed: {data}\"\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\") # Health check at http://localhost:8000/health\n```\n\nCustom 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).\n\n## Alternative Initialization Patterns\n\nThe `if __name__ == \"__main__\"` pattern works well for standalone scripts, but some deployment scenarios require different approaches. FastMCP handles these cases automatically.\n\n### CLI-Only Servers\n\nWhen using the FastMCP CLI, you don't need the `if __name__` block at all. The CLI will find your FastMCP instance and run it:\n\n```python\n# server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"MyServer\") # CLI looks for 'mcp', 'server', or 'app'\n\n@mcp.tool\ndef process(data: str) -> str:\n return f\"Processed: {data}\"\n\n# No if __name__ block needed - CLI will find and run 'mcp'\n```\n\n### ASGI Applications\n\nFor 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:\n\n```python\n# app.py\nfrom fastmcp import FastMCP\n\ndef create_app():\n mcp = FastMCP(\"MyServer\")\n \n @mcp.tool\n def process(data: str) -> str:\n return f\"Processed: {data}\"\n \n return mcp.http_app()\n\napp = create_app() # Uvicorn will use this\n```\n\nSee the [HTTP Deployment](/deployment/http) guide for more ASGI deployment patterns." }, { "path": "docs/deployment/server-configuration.mdx", "content": "---\ntitle: \"Project Configuration\"\nsidebarTitle: \"Project Configuration\"\ndescription: Use fastmcp.json for portable, declarative project configuration\nicon: file-code\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\n\n\nFastMCP 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.\n\nThe `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.\n\n## Overview\n\nThe `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.\n\nWhen you have a `fastmcp.json` file, running your server becomes as simple as:\n\n```bash\n# Run the server using the configuration\nfastmcp run fastmcp.json\n\n# Or if fastmcp.json exists in the current directory\nfastmcp run\n```\n\nThis 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.\n\n## File Structure\n\nThe `fastmcp.json` configuration answers three fundamental questions about your server:\n\n- **Source** = WHERE does your server code live?\n- **Environment** = WHAT environment setup does it require?\n- **Deployment** = HOW should the server run?\n\nThis 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:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n // WHERE: Location of your server code\n \"type\": \"filesystem\", // Optional, defaults to \"filesystem\"\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"environment\": {\n // WHAT: Environment setup and dependencies\n \"type\": \"uv\", // Optional, defaults to \"uv\"\n \"python\": \">=3.10\",\n \"dependencies\": [\"pandas\", \"numpy\"]\n },\n \"deployment\": {\n // HOW: Runtime configuration\n \"transport\": \"stdio\",\n \"log_level\": \"INFO\"\n }\n}\n```\n\nOnly the `source` field is required. The `environment` and `deployment` sections are optional and provide additional configuration when needed.\n\n### JSON Schema Support\n\nFastMCP provides JSON schemas for IDE autocomplete and validation. Add the schema reference to your `fastmcp.json` for enhanced developer experience:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n }\n}\n```\n\nTwo schema URLs are available:\n- **Version-specific**: `https://gofastmcp.com/public/schemas/fastmcp.json/v1.json`\n- **Latest version**: `https://gofastmcp.com/public/schemas/fastmcp.json/latest.json`\n\nModern IDEs like VS Code will automatically provide autocomplete suggestions, validation, and inline documentation when the schema is specified.\n\n### Source Configuration\n\nThe 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.\n\n\n\n The server source configuration that determines where your server code lives.\n \n \n 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.\n \n \n \n When `type` is `\"filesystem\"` (or omitted), the source points to a local Python file containing your FastMCP server:\n \n \n Path to the Python file containing your FastMCP server. \n \n \n \n Name of the server instance or factory function within the module:\n - Can be a FastMCP server instance (e.g., `mcp = FastMCP(\"MyServer\")`)\n - Can be a function with no arguments that returns a FastMCP server\n - If not specified, FastMCP searches for common names: `mcp`, `server`, or `app`\n \n \n **Example:**\n ```json\n \"source\": {\n \"type\": \"filesystem\",\n \"path\": \"src/server.py\",\n \"entrypoint\": \"mcp\"\n }\n ```\n \n Note: File paths are resolved relative to the configuration file's location.\n \n\n\n\n\n**Future Source Types**\n\nFuture releases will support additional source types:\n- **Git repositories** (`type: \"git\"`) for loading server code directly from version control\n- **Prefect Horizon** (`type: \"cloud\"`) for hosted servers with automatic scaling and management\n\n\n### Environment Configuration\n\nThe 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.\n\nFastMCP 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.\n\n\n\n Optional environment configuration. When specified, FastMCP uses the appropriate environment implementation to set up your server's runtime.\n \n \n The environment type identifier that determines which implementation to use. Currently supports `\"uv\"` for Python environments managed by uv. If omitted, defaults to `\"uv\"`.\n \n \n \n When `type` is `\"uv\"` (or omitted), the environment uses uv to manage Python dependencies:\n \n \n Python version constraint. Examples:\n - Exact version: `\"3.12\"`\n - Minimum version: `\">=3.10\"`\n - Version range: `\">=3.10,<3.13\"`\n \n \n \n List of pip packages with optional version specifiers (PEP 508 format).\n ```json\n \"dependencies\": [\"pandas>=2.0\", \"requests\", \"httpx\"]\n ```\n \n \n \n Path to a requirements.txt file, resolved relative to the config file location.\n ```json\n \"requirements\": \"requirements.txt\"\n ```\n \n \n \n Path to a project directory containing pyproject.toml for uv project management.\n ```json\n \"project\": \".\"\n ```\n \n \n \n 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.\n ```json\n \"editable\": [\".\"]\n ```\n Or with multiple packages:\n ```json\n \"editable\": [\".\", \"../shared-lib\", \"/path/to/another-package\"]\n ```\n \n \n **Example:**\n ```json\n \"environment\": {\n \"type\": \"uv\",\n \"python\": \">=3.10\",\n \"dependencies\": [\"pandas\", \"numpy\"],\n \"editable\": [\".\"]\n }\n ```\n \n Note: When any UVEnvironment field is specified, FastMCP automatically creates an isolated environment using `uv` before running your server.\n \n\n\n\nWhen environment configuration is provided, FastMCP:\n1. Detects the environment type (defaults to `\"uv\"` if not specified)\n2. Creates an isolated environment using the appropriate provider\n3. Installs the specified dependencies\n4. Runs your server in this clean environment\n\nThis build-time setup ensures your server always has the dependencies it needs, without polluting your system Python or conflicting with other projects.\n\n\n**Future Environment Types**\n\nSimilar to source types, future releases may support additional environment types for different runtime requirements, such as Docker containers or language-specific environments beyond Python.\n\n\n### Deployment Configuration\n\nThe 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.\n\nEnvironment 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.\n\n\n\n Optional runtime configuration for the server.\n \n \n \n Protocol for client communication:\n - `\"stdio\"`: Standard input/output for desktop clients\n - `\"http\"`: Network-accessible HTTP server\n - `\"sse\"`: Server-sent events\n \n \n \n Network interface to bind (HTTP transport only):\n - `\"127.0.0.1\"`: Local connections only\n - `\"0.0.0.0\"`: All network interfaces\n \n \n \n Port number for HTTP transport.\n \n \n \n URL path for the MCP endpoint when using HTTP transport.\n \n \n \n Server logging verbosity. Options:\n - `\"DEBUG\"`: Detailed debugging information\n - `\"INFO\"`: General informational messages\n - `\"WARNING\"`: Warning messages\n - `\"ERROR\"`: Error messages only\n - `\"CRITICAL\"`: Critical errors only\n \n \n \n Environment variables to set when running the server. Supports `${VAR_NAME}` syntax for runtime interpolation.\n ```json\n \"env\": {\n \"API_KEY\": \"secret-key\",\n \"DATABASE_URL\": \"postgres://${DB_USER}@${DB_HOST}/mydb\"\n }\n ```\n \n \n \n Working directory for the server process. Relative paths are resolved from the config file location.\n \n \n \n Command-line arguments to pass to the server, passed after `--` to the server's argument parser.\n ```json\n \"args\": [\"--config\", \"server-config.json\"]\n ```\n \n \n\n\n\n#### Environment Variable Interpolation\n\nThe `env` field in deployment configuration supports runtime interpolation of environment variables using `${VAR_NAME}` syntax. This enables dynamic configuration based on your deployment environment:\n\n```json\n{\n \"deployment\": {\n \"env\": {\n \"API_URL\": \"https://api.${ENVIRONMENT}.example.com\",\n \"DATABASE_URL\": \"postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/myapp\",\n \"CACHE_KEY\": \"myapp_${ENVIRONMENT}_${VERSION}\"\n }\n }\n}\n```\n\nWhen 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.\n\n**Example**: If your system has `ENVIRONMENT=production` and `DB_HOST=db.example.com`:\n```json\n// Configuration\n{\n \"deployment\": {\n \"env\": {\n \"API_URL\": \"https://api.${ENVIRONMENT}.example.com\",\n \"DB_HOST\": \"${DB_HOST}\"\n }\n }\n}\n\n// Result at runtime\n{\n \"API_URL\": \"https://api.production.example.com\",\n \"DB_HOST\": \"db.example.com\"\n}\n```\n\nThis feature is particularly useful for:\n- Deploying the same configuration across development, staging, and production\n- Keeping sensitive values out of configuration files\n- Building dynamic URLs and connection strings\n- Creating environment-specific prefixes or suffixes\n\n## Usage with CLI Commands\n\nFastMCP 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:\n\n```bash\n# Auto-detect fastmcp.json in current directory\ncd my-project\nfastmcp run # No arguments needed!\n\n# Or specify a configuration file explicitly\nfastmcp run prod.fastmcp.json\n\n# Skip environment setup when already in a uv environment\nfastmcp run fastmcp.json --skip-env\n\n# Skip source preparation when source is already prepared\nfastmcp run fastmcp.json --skip-source\n\n# Skip both environment and source preparation\nfastmcp run fastmcp.json --skip-env --skip-source\n```\n\n### Pre-building Environments\n\nYou can use `fastmcp project prepare` to create a persistent uv project with all dependencies pre-installed:\n\n```bash\n# Create a persistent environment\nfastmcp project prepare fastmcp.json --output-dir ./env\n\n# Use the pre-built environment to run the server\nfastmcp run fastmcp.json --project ./env\n```\n\nThis pattern separates environment setup (slow) from server execution (fast), useful for deployment scenarios.\n\n### Using an Existing Environment\n\nBy 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:\n\n```bash\nfastmcp run fastmcp.json --skip-env\n```\n\n**When you already have an environment:**\n- You're in an activated virtual environment with all dependencies installed\n- You're inside a Docker container with pre-installed dependencies \n- You're in a CI/CD pipeline that pre-builds the environment\n- You're using a system-wide installation with all required packages\n- You're in a uv-managed environment (prevents infinite recursion)\n\nThis flag tells FastMCP: \"I already have everything installed, just run the server.\"\n\n### Using an Existing Source\n\nWhen 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:\n\n```bash\nfastmcp run fastmcp.json --skip-source\n```\n\n**When you already have the source:**\n- You've previously cloned a git repository and don't need to re-fetch\n- You have a cached copy of a cloud-hosted server\n- You're in a CI/CD pipeline where source checkout is a separate step\n- You're iterating locally on already-downloaded code\n\nThis flag tells FastMCP: \"I already have the source code, skip any download/clone steps.\"\n\nNote: For filesystem sources (local Python files), this flag has no effect since they don't require preparation.\n\nThe configuration file works with all FastMCP commands:\n- **`run`** - Start the server in production mode\n- **`dev`** - Launch with the Inspector UI for development \n- **`inspect`** - View server capabilities and configuration\n- **`install`** - Install to Claude Desktop, Cursor, or other MCP clients\n\nWhen 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.\n\n### CLI Override Behavior\n\nCommand-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:\n\n```bash\n# Config specifies port 3000, CLI overrides to 8080\nfastmcp run fastmcp.json --port 8080\n\n# Config specifies stdio, CLI overrides to HTTP\nfastmcp run fastmcp.json --transport http\n\n# Add extra dependencies not in config\nfastmcp run fastmcp.json --with requests --with httpx\n```\n\nThis precedence order enables:\n- Quick testing of different settings\n- Environment-specific overrides in deployment scripts\n- Debugging with increased log levels\n- Temporary configuration changes\n\n### Custom Naming Patterns\n\nYou can use different configuration files for different environments:\n\n- `fastmcp.json` - Default configuration\n- `dev.fastmcp.json` - Development settings\n- `prod.fastmcp.json` - Production settings\n- `test_fastmcp.json` - Test configuration\n\nAny file with \"fastmcp.json\" in the name is recognized as a configuration file.\n\n## Examples\n\n\n\n\nA minimal configuration for a simple server:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n }\n}\n```\nThis 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.\n\n\n\nA configuration optimized for local development:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n // WHERE does the server live?\n \"source\": {\n \"path\": \"src/server.py\",\n \"entrypoint\": \"app\"\n },\n // WHAT dependencies does it need?\n \"environment\": {\n \"type\": \"uv\",\n \"python\": \"3.12\",\n \"dependencies\": [\"fastmcp[dev]\"],\n \"editable\": \".\"\n },\n // HOW should it run?\n \"deployment\": {\n \"transport\": \"http\",\n \"host\": \"127.0.0.1\",\n \"port\": 8000,\n \"log_level\": \"DEBUG\",\n \"env\": {\n \"DEBUG\": \"true\",\n \"ENV\": \"development\"\n }\n }\n}\n```\n\n\n\nA production-ready configuration with full dependency management:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n // WHERE does the server live?\n \"source\": {\n \"path\": \"app/main.py\",\n \"entrypoint\": \"mcp_server\"\n },\n // WHAT dependencies does it need?\n \"environment\": {\n \"python\": \"3.11\",\n \"requirements\": \"requirements/production.txt\",\n \"project\": \".\"\n },\n // HOW should it run?\n \"deployment\": {\n \"transport\": \"http\",\n \"host\": \"0.0.0.0\",\n \"port\": 3000,\n \"path\": \"/api/mcp/\",\n \"log_level\": \"INFO\",\n \"env\": {\n \"ENV\": \"production\",\n \"API_BASE_URL\": \"https://api.example.com\",\n \"DATABASE_URL\": \"postgresql://user:pass@db.example.com/prod\"\n },\n \"cwd\": \"/app\",\n \"args\": [\"--workers\", \"4\"]\n }\n}\n```\n\n\n\nConfiguration for a data analysis server with scientific packages:\n\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"analysis_server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"environment\": {\n \"python\": \"3.11\",\n \"dependencies\": [\n \"pandas>=2.0\",\n \"numpy\",\n \"scikit-learn\",\n \"matplotlib\",\n \"jupyterlab\"\n ]\n },\n \"deployment\": {\n \"transport\": \"stdio\",\n \"env\": {\n \"MATPLOTLIB_BACKEND\": \"Agg\",\n \"DATA_PATH\": \"./datasets\"\n }\n }\n}\n```\n\n \n\nYou can maintain multiple configuration files for different environments:\n\n**dev.fastmcp.json**:\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"deployment\": {\n \"transport\": \"http\",\n \"log_level\": \"DEBUG\"\n }\n}\n```\n\n**prod.fastmcp.json**:\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"environment\": {\n \"requirements\": \"requirements/production.txt\"\n },\n \"deployment\": {\n \"transport\": \"http\",\n \"host\": \"0.0.0.0\",\n \"log_level\": \"WARNING\"\n }\n}\n```\n\nRun different configurations:\n```bash\nfastmcp run dev.fastmcp.json # Development\nfastmcp run prod.fastmcp.json # Production\n```\n\n\n\n## Migrating from CLI Arguments\n\nIf 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:\n\n**CLI Command**:\n```bash\nuv run --with pandas --with requests \\\n fastmcp run server.py \\\n --transport http \\\n --port 8000 \\\n --log-level INFO\n```\n\n**Equivalent fastmcp.json**:\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"path\": \"server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"environment\": {\n \"dependencies\": [\"pandas\", \"requests\"]\n },\n \"deployment\": {\n \"transport\": \"http\",\n \"port\": 8000,\n \"log_level\": \"INFO\"\n }\n}\n```\n\nNow simply run:\n```bash\nfastmcp run # Automatically finds and uses fastmcp.json\n```\n\nThe configuration file approach provides better documentation, easier sharing, and consistent execution across different environments while maintaining the flexibility to override settings when needed." }, { "path": "docs/development/contributing.mdx", "content": "---\ntitle: \"Contributing\"\ndescription: \"Development workflow for FastMCP contributors\"\nicon: code-pull-request\n---\n\nContributing 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.\n\n## Design Principles\n\nEvery contribution should advance these principles:\n\n- 🚀 **Fast** — High-level interfaces mean less code and faster development\n- 🍀 **Simple** — Minimal boilerplate; the obvious way should be the right way\n- 🐍 **Pythonic** — Feels natural to Python developers; no surprising patterns\n- 🔍 **Complete** — Everything needed for production: auth, testing, deployment, observability\n\nPRs are evaluated against these principles. Code that makes FastMCP slower, harder to reason about, less Pythonic, or less complete will be rejected.\n\n## Issues\n\n### Issue First, Code Second\n\n**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.\n\n**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.\n\nUse issues to understand scope BEFORE opening PRs. The issue discussion determines whether a feature belongs in core, contrib, or not at all.\n\n### Writing Good Issues\n\nFastMCP 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.\n\n**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.\n\nWrite clear, concise issues that:\n- State the problem directly\n- Provide a minimal reproducible example\n- Skip unnecessary background or context\n- Take responsibility for clear communication\n\nIssues may be labeled \"Invalid\" simply due to confusion caused by verbosity or not adhering to the guidelines outlined here.\n\n## Pull Requests\n\nPRs 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.\n\n\n### Development Environment\n\n#### Installation\n\nTo contribute to FastMCP, you'll need to set up a development environment with all necessary tools and dependencies.\n\n```bash\n# Clone the repository\ngit clone https://github.com/PrefectHQ/fastmcp.git\ncd fastmcp\n\n# Install all dependencies including dev tools\nuv sync\n\n# Install prek hooks\nuv run prek install\n```\n\nIn addition, some development commands require [just](https://github.com/casey/just) to be installed.\n\nPrek 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.\n\n### Development Standards\n\n#### Scope\n\nLarge 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. \n\nA 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.\n\nBreaking large features into smaller PRs:\n- Creates better review experiences\n- Makes git history clear\n- Simplifies debugging with bisect\n- Reduces merge conflicts\n- Gets your code merged faster\n\n#### Code Quality\n\nFastMCP values clarity over cleverness. Every line you write will be maintained by someone else - possibly years from now, possibly without context about your decisions.\n\n**PRs can be rejected for two opposing reasons:**\n1. **Insufficient quality** - Code that doesn't meet our standards for clarity, maintainability, or idiomaticity\n2. **Overengineering** - Code that is overbearing, unnecessarily complex, or tries to be too clever\n\nThe focus is on idiomatic, high-quality Python. FastMCP uses patterns like `NotSet` type as an alternative to `None` in certain situations - follow existing patterns.\n\n#### Required Practices\n\n**Full type annotations** on all functions and methods. They catch bugs before runtime and serve as inline documentation.\n\n**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.\n\n**Descriptive names** make code self-documenting. `auth_token` is clear; `tok` requires mental translation.\n\n**Specific exception types** make error handling predictable. Catching `ValueError` tells readers exactly what error you expect. Never use bare `except` clauses.\n\n#### Anti-Patterns to Avoid\n\n**Complex one-liners** are hard to debug and modify. Break operations into clear steps.\n\n**Mutable default arguments** cause subtle bugs. Use `None` as the default and create the mutable object inside the function.\n\n**Breaking established patterns** confuses readers. If you must deviate, discuss in the issue first.\n\n### Prek Checks\n\n```bash\n# Runs automatically on commit, or manually:\nuv run prek run --all-files\n```\n\nThis runs three critical tools:\n- **Ruff**: Linting and formatting\n- **Prettier**: Code formatting\n- **ty**: Static type checking\n\nPytest runs separately as a distinct workflow step after prek checks pass. CI will reject PRs that fail these checks. Always run them locally first.\n\n### Testing\n\nTests are documentation that shows how features work. Good tests give reviewers confidence and help future maintainers understand intent.\n\n```bash\n# Run specific test directory\nuv run pytest tests/server/ -v\n\n# Run all tests before submitting PR\nuv run pytest\n```\n\nEvery new feature needs tests. See the [Testing Guide](/development/tests) for patterns and requirements.\n\n### Documentation\n\nA 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.\n\n```bash\n# Preview documentation locally\njust docs\n```\n\nDocumentation requirements:\n- **Explain concepts in prose first** - Code without context is just syntax\n- **Complete, runnable examples** - Every code block should be copy-pasteable\n- **Register in docs.json** - Makes pages appear in navigation\n- **Version badges** - Mark when features were added using ``\n\n#### SDK Documentation\n\nFastMCP'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:\n\n```bash\njust api-ref-all\n```\n\n### Submitting Your PR\n\n#### Before Submitting\n\n1. **Run all checks**: `uv run prek run --all-files && uv run pytest`\n2. **Keep scope small**: One feature or fix per PR\n3. **Write clear description**: Your PR description becomes permanent documentation\n4. **Update docs**: Include documentation for API changes\n\n#### PR Description\n\nWrite PR descriptions that explain:\n- What problem you're solving\n- Why you chose this approach \n- Any trade-offs or alternatives considered\n- Migration path for breaking changes\n\nFocus on the \"why\" - the code shows the \"what\". Keep it concise but complete.\n\n#### What We Look For\n\n**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.\n\n**Code Quality**: We verify code follows existing patterns. Consistency reduces cognitive load. When every module works similarly, developers understand new code quickly.\n\n**Test Coverage**: Not every line needs testing, but every behavior does. Tests document intent and protect against regressions.\n\n**Breaking Changes**: May be acceptable in minor versions but must be clearly documented. See the [versioning policy](/development/releases#versioning-policy).\n\n## Special Modules\n\n**`contrib`**: Community-maintained patterns and utilities. Original authors maintain their contributions. Not representative of the core framework.\n\n**`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." }, { "path": "docs/development/releases.mdx", "content": "---\ntitle: \"Releases\"\ndescription: \"FastMCP versioning and release process\"\nicon: \"truck-fast\"\n---\n\nFastMCP 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.\n\n## Versioning Policy\n\n### Semantic Versioning\n\n**Major (x.0.0)**: Complete API redesigns\n\nMajor versions represent fundamental shifts. FastMCP 2.x is entirely different from 1.x in both implementation and design philosophy.\n\n**Minor (2.x.0)**: New features and evolution\n\n\nUnlike 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.\n\n\nFastMCP 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.\n\n**Patch (2.0.x)**: Bug fixes and refinements\n\nPatch versions contain only bug fixes without breaking changes. These are safe updates you can apply with confidence.\n\n### Breaking Changes\n\nWe 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.\n\nWhen breaking changes occur:\n- They only happen in minor versions (e.g., 2.3.x to 2.4.0)\n- Release notes explain what changed and how to migrate\n- We provide deprecation warnings at least 1 minor version in advance when possible\n- Changes must substantially benefit users to justify disruption\n\nThe 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:\n- `FastMCP` server class, `Client` class, and FastMCP `Context`\n- Core MCP components: `Tool`, `Prompt`, `Resource`, `ResourceTemplate`, and transports\n- Their public methods and documented behaviors\n\nEverything 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.\n\n\nThe `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.\n\nWe expect this exemption to last through at least the 2.12.x and 2.13.x release series. \n\n\n### Production Use\n\nPin to exact versions:\n```\nfastmcp==2.11.0 # Good\nfastmcp>=2.11.0 # Bad - will install breaking changes\n```\n\n## Creating Releases\n\nOur release process is intentionally simple:\n\n1. Create GitHub release with tag `vMAJOR.MINOR.PATCH` (e.g., `v2.11.0`)\n2. Generate release notes automatically, and curate or add additional editorial information as needed\n3. GitHub releases automatically trigger PyPI deployments\n\nThis automation lets maintainers focus on code quality rather than release mechanics.\n\n### Release Cadence\n\nWe follow a feature-driven release cadence rather than a fixed schedule. Minor versions ship approximately every 3-4 weeks when significant functionality is ready.\n\nPatch releases ship promptly for:\n- Critical bug fixes\n- Security updates (immediate release)\n- Regression fixes\n\nThis approach means you get improvements as soon as they're ready rather than waiting for arbitrary release dates.\n" }, { "path": "docs/development/tests.mdx", "content": "---\ntitle: \"Tests\"\ndescription: \"Testing patterns and requirements for FastMCP\"\nicon: vial\n---\n\nimport { VersionBadge } from \"/snippets/version-badge.mdx\"\n\nGood 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.\n\n## FastMCP Tests\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test file\nuv run pytest tests/server/test_auth.py\n\n# Run with coverage\nuv run pytest --cov=fastmcp\n\n# Skip integration tests for faster runs\nuv run pytest -m \"not integration\"\n\n# Skip tests that spawn processes\nuv run pytest -m \"not integration and not client_process\"\n```\n\nTests should complete in under 1 second unless marked as integration tests. This speed encourages running them frequently, catching issues early.\n\n### Test Organization\n\nOur 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.\n\n### Test Markers\n\nWe use pytest markers to categorize tests that require special resources or take longer to run:\n\n```python\n@pytest.mark.integration\nasync def test_github_api_integration():\n \"\"\"Test GitHub API integration with real service.\"\"\"\n token = os.getenv(\"FASTMCP_GITHUB_TOKEN\")\n if not token:\n pytest.skip(\"FASTMCP_GITHUB_TOKEN not available\")\n \n # Test against real GitHub API\n client = GitHubClient(token)\n repos = await client.list_repos(\"prefecthq\")\n assert \"fastmcp\" in [repo.name for repo in repos]\n\n@pytest.mark.client_process\nasync def test_stdio_transport():\n \"\"\"Test STDIO transport with separate process.\"\"\"\n # This spawns a subprocess\n async with Client(\"python examples/simple_echo.py\") as client:\n result = await client.call_tool(\"echo\", {\"message\": \"test\"})\n assert result.content[0].text == \"test\"\n```\n\n## Writing Tests\n\n\n### Test Requirements\n\nFollowing these practices creates maintainable, debuggable test suites that serve as both documentation and regression protection.\n\n#### Single Behavior Per Test\n\nEach 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.\n\n\n\n```python Good: Atomic Test\nasync def test_tool_registration():\n \"\"\"Test that tools are properly registered with the server.\"\"\"\n mcp = FastMCP(\"test-server\")\n \n @mcp.tool\n def add(a: int, b: int) -> int:\n return a + b\n \n tools = mcp.list_tools()\n assert len(tools) == 1\n assert tools[0].name == \"add\"\n```\n\n```python Bad: Multi-Behavior Test\nasync def test_server_functionality():\n \"\"\"Test multiple server features at once.\"\"\"\n mcp = FastMCP(\"test-server\")\n \n # Tool registration\n @mcp.tool\n def add(a: int, b: int) -> int:\n return a + b\n \n # Resource creation\n @mcp.resource(\"config://app\")\n def get_config():\n return {\"version\": \"1.0\"}\n \n # Authentication setup\n mcp.auth = BearerTokenProvider({\"token\": \"user\"})\n \n # What exactly are we testing? If this fails, what broke?\n assert mcp.list_tools()\n assert mcp.list_resources()\n assert mcp.auth is not None\n```\n\n\n\n#### Self-Contained Setup\n\nEvery 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.\n\n\n\n```python Good: Self-Contained\nasync def test_tool_execution_with_error():\n \"\"\"Test that tool errors are properly handled.\"\"\"\n mcp = FastMCP(\"test-server\")\n \n @mcp.tool\n def divide(a: int, b: int) -> float:\n if b == 0:\n raise ValueError(\"Cannot divide by zero\")\n return a / b\n \n async with Client(mcp) as client:\n with pytest.raises(Exception):\n await client.call_tool(\"divide\", {\"a\": 10, \"b\": 0})\n```\n\n```python Bad: Test Dependencies\n# Global state that tests depend on\ntest_server = None\n\ndef test_setup_server():\n \"\"\"Setup for other tests.\"\"\"\n global test_server\n test_server = FastMCP(\"shared-server\")\n\ndef test_server_works():\n \"\"\"Test server functionality.\"\"\"\n # Depends on test_setup_server running first\n assert test_server is not None\n```\n\n\n\n#### Clear Intent\n\nTest 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.\n\n```python\nasync def test_authenticated_tool_requires_valid_token():\n \"\"\"Test that authenticated users can access protected tools.\"\"\"\n mcp = FastMCP(\"test-server\")\n mcp.auth = BearerTokenProvider({\"secret-token\": \"test-user\"})\n \n @mcp.tool\n def protected_action() -> str:\n return \"success\"\n \n async with Client(mcp, auth=BearerAuth(\"secret-token\")) as client:\n result = await client.call_tool(\"protected_action\", {})\n assert result.content[0].text == \"success\"\n```\n\n#### Using Fixtures\n\nUse 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.\n\n```python\nimport pytest\nfrom fastmcp import FastMCP, Client\n\n@pytest.fixture\ndef weather_server():\n server = FastMCP(\"WeatherServer\")\n \n @server.tool\n def get_temperature(city: str) -> dict:\n temps = {\"NYC\": 72, \"LA\": 85, \"Chicago\": 68}\n return {\"city\": city, \"temp\": temps.get(city, 70)}\n \n return server\n\nasync def test_temperature_tool(weather_server):\n async with Client(weather_server) as client:\n result = await client.call_tool(\"get_temperature\", {\"city\": \"LA\"})\n assert result.data == {\"city\": \"LA\", \"temp\": 85}\n```\n\n#### Effective Assertions\n\nAssertions should be specific and provide context on failure. When a test fails during CI, the assertion message should tell you exactly what went wrong.\n\n```python\n# Basic assertion - minimal context on failure\nassert result.status == \"success\"\n\n# Better - explains what was expected\nassert result.status == \"success\", f\"Expected successful operation, got {result.status}: {result.error}\"\n```\n\nTry 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.\n\n#### Inline Snapshots\n\nFastMCP 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.\n\n```python\nfrom inline_snapshot import snapshot\n\nasync def test_tool_schema_generation():\n \"\"\"Test that tool schemas are generated correctly.\"\"\"\n mcp = FastMCP(\"test-server\")\n \n @mcp.tool\n def calculate_tax(amount: float, rate: float = 0.1) -> dict:\n \"\"\"Calculate tax on an amount.\"\"\"\n return {\"amount\": amount, \"tax\": amount * rate, \"total\": amount * (1 + rate)}\n \n tools = mcp.list_tools()\n schema = tools[0].inputSchema\n \n # First run: snapshot() is empty, gets auto-populated\n # Subsequent runs: compares against stored snapshot\n assert schema == snapshot({\n \"type\": \"object\", \n \"properties\": {\n \"amount\": {\"type\": \"number\"}, \n \"rate\": {\"type\": \"number\", \"default\": 0.1}\n }, \n \"required\": [\"amount\"]\n })\n```\n\n### In-Memory Testing\n\nFastMCP 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.\n\nThe 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.\n\n```python\nfrom fastmcp import FastMCP, Client\n\n# Create your server\nserver = FastMCP(\"WeatherServer\")\n\n@server.tool\ndef get_temperature(city: str) -> dict:\n \"\"\"Get current temperature for a city\"\"\"\n temps = {\"NYC\": 72, \"LA\": 85, \"Chicago\": 68}\n return {\"city\": city, \"temp\": temps.get(city, 70)}\n\nasync def test_weather_operations():\n # Pass server directly - no deployment needed\n async with Client(server) as client:\n result = await client.call_tool(\"get_temperature\", {\"city\": \"NYC\"})\n assert result.data == {\"city\": \"NYC\", \"temp\": 72}\n```\n\nThis pattern makes tests deterministic and fast - typically completing in milliseconds rather than seconds.\n\n### Mocking External Dependencies\n\nFastMCP servers are standard Python objects, so you can mock external dependencies using your preferred approach:\n\n```python\nfrom unittest.mock import AsyncMock\n\nasync def test_database_tool():\n server = FastMCP(\"DataServer\")\n \n # Mock the database\n mock_db = AsyncMock()\n mock_db.fetch_users.return_value = [\n {\"id\": 1, \"name\": \"Alice\"},\n {\"id\": 2, \"name\": \"Bob\"}\n ]\n \n @server.tool\n async def list_users() -> list:\n return await mock_db.fetch_users()\n \n async with Client(server) as client:\n result = await client.call_tool(\"list_users\", {})\n assert len(result.data) == 2\n assert result.data[0][\"name\"] == \"Alice\"\n mock_db.fetch_users.assert_called_once()\n```\n\n### Testing Network Transports\n\nWhile 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).\n\n#### In-Process Network Testing (Preferred)\n\n\n\nFor 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:\n\n```python\nimport pytest\nfrom fastmcp import FastMCP, Client\nfrom fastmcp.client.transports import StreamableHttpTransport\nfrom fastmcp.utilities.tests import run_server_async\n\ndef create_test_server() -> FastMCP:\n \"\"\"Create a test server instance.\"\"\"\n server = FastMCP(\"TestServer\")\n\n @server.tool\n def greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n return server\n\n@pytest.fixture\nasync def http_server() -> str:\n \"\"\"Start server in-process for testing.\"\"\"\n server = create_test_server()\n async with run_server_async(server) as url:\n yield url\n\nasync def test_http_transport(http_server: str):\n \"\"\"Test actual HTTP transport behavior.\"\"\"\n async with Client(\n transport=StreamableHttpTransport(http_server)\n ) as client:\n result = await client.ping()\n assert result is True\n\n greeting = await client.call_tool(\"greet\", {\"name\": \"World\"})\n assert greeting.data == \"Hello, World!\"\n```\n\nThe `run_server_async` context manager automatically handles server lifecycle and cleanup. This approach is faster than subprocess-based testing and provides better error messages.\n\n#### Subprocess Testing (Special Cases)\n\nFor tests that require complete process isolation (like STDIO transport or testing subprocess behavior), use `run_server_in_process`:\n\n```python\nimport pytest\nfrom fastmcp.utilities.tests import run_server_in_process\nfrom fastmcp import FastMCP, Client\nfrom fastmcp.client.transports import StreamableHttpTransport\n\ndef run_server(host: str, port: int) -> None:\n \"\"\"Function to run in subprocess.\"\"\"\n server = FastMCP(\"TestServer\")\n \n @server.tool\n def greet(name: str) -> str:\n return f\"Hello, {name}!\"\n \n server.run(host=host, port=port)\n\n@pytest.fixture\nasync def http_server():\n \"\"\"Fixture that runs server in subprocess.\"\"\"\n with run_server_in_process(run_server, transport=\"http\") as url:\n yield f\"{url}/mcp\"\n\nasync def test_http_transport(http_server: str):\n \"\"\"Test actual HTTP transport behavior.\"\"\"\n async with Client(\n transport=StreamableHttpTransport(http_server)\n ) as client:\n result = await client.ping()\n assert result is True\n```\n\nThe `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.\n\n### Documentation Testing\n\nDocumentation 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:\n\n```bash\n# Start local documentation server with hot reload\njust docs\n\n# Or run Mintlify directly\nmintlify dev\n```\n\nThe local server watches for changes and automatically refreshes. This preview catches formatting issues and helps you see documentation as users will experience it." }, { "path": "docs/development/v3-notes/auth-provider-env-vars.mdx", "content": "---\ntitle: Auth Provider Environment Variables\n---\n\n## Decision: Remove automatic environment variable loading from auth providers\n\nYou can still use environment variables for configuration - you just read them yourself with `os.environ` instead of relying on FastMCP's automatic loading.\n\n**Status:** Implemented in v3.0.0\n\n### Background\n\nAuth providers in v2.x used `pydantic-settings` to automatically load configuration from environment variables with a `FASTMCP_SERVER_AUTH__` prefix. For example, `GitHubProvider` would read from:\n\n- `FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID`\n- `FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET`\n- `FASTMCP_SERVER_AUTH_GITHUB_BASE_URL`\n- etc.\n\nThis was implemented via a `*ProviderSettings(BaseSettings)` class in each provider, combined with a `NotSet` sentinel pattern to distinguish between \"not provided\" and `None`.\n\n### Why remove it\n\n1. **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.\n\n2. **Documentation complexity**: Each provider needed documentation explaining both the parameter and the corresponding environment variable. This doubled the surface area to document and maintain.\n\n3. **Contributor friction**: New contributors adding providers had to understand and replicate this pattern, which was a source of inconsistency and bugs.\n\n4. **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.\n\n5. **Implicit behavior**: Magic environment variable loading makes it harder to understand where values come from. Explicit `os.environ` calls are more traceable.\n\n### Migration path\n\nThe migration is trivial - users add explicit environment variable reads:\n\n```python\n# Before (v2.x)\nauth = GitHubProvider() # Relied on env vars\n\n# After (v3.0)\nimport os\n\nauth = GitHubProvider(\n client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n base_url=os.environ[\"MY_BASE_URL\"],\n)\n```\n\nUsers can also use `os.environ.get()` with defaults, or any other configuration library they prefer (dotenv, dynaconf, etc.).\n\n### Backwards compatibility\n\nWe chose not to provide backwards compatibility because:\n\n1. This is a major version bump (v3.0), which is the appropriate time for breaking changes\n2. The migration is straightforward (add `os.environ` calls)\n3. Maintaining compatibility would require keeping all the boilerplate we're trying to remove\n4. The pattern was likely not heavily used - most production deployments pass secrets explicitly rather than relying on magic prefixes\n\n### What was removed\n\n- `*ProviderSettings(BaseSettings)` classes from all auth providers\n- `NotSet` sentinel usage in provider constructors\n- `pydantic-settings` dependency for auth providers\n- Environment variable documentation from provider docs\n- Related test cases for env var loading\n\n### Result\n\nProvider 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.\n" }, { "path": "docs/development/v3-notes/v3-features.mdx", "content": "---\ntitle: v3.0 Feature Tracking\n---\n\nThis document tracks major features in FastMCP v3.0 for release notes preparation.\n\n## 3.0.0rc1\n\n### SamplingTool Conversion Helpers\n\nServer 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.\n\n```python\n@mcp.tool\ndef search(query: str) -> str:\n \"\"\"Search the web.\"\"\"\n return do_search(query)\n\n# Use tool directly in sampling\nresult = await ctx.sample(\n \"Research Python frameworks\",\n tools=[search] # FunctionTool works directly!\n)\n```\n\n### Google GenAI Sampling Handler\n\nFastMCP 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.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.sampling.handlers import GoogleGenaiSamplingHandler\nfrom google.genai import Client as GoogleGenaiClient\n\n# Initialize the handler\nhandler = GoogleGenaiSamplingHandler(\n default_model=\"gemini-2.0-flash-exp\",\n client=GoogleGenaiClient(), # Optional - creates one if not provided\n)\n\n# Use with MCP sampling (handler is configured at Client construction)\nasync with Client(\"http://server/mcp\", sampling_handler=handler) as client:\n result = await client.sample(\n messages=[...],\n tools=[...],\n )\n```\n\nKey features:\n- Converts MCP tool schemas to Google's function calling format\n- Supports all Google GenAI models that implement function calling\n- Handles nullable types, nested objects, and arrays in tool schemas\n- Properly maps tool choices (`auto`, `required`, `none`) to Google's configuration\n- Preserves model preferences from MCP sampling parameters\n\nThe handler joins the existing Anthropic and OpenAI handlers, providing a consistent interface for model-agnostic sampling across providers.\n\n### Concurrent Tool Execution in Sampling\n\nWhen 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.\n\n```python\nresult = await context.sample(\n messages=\"Fetch weather for NYC and LA\",\n tools=[fetch_weather],\n tool_concurrency=0, # Unlimited parallel execution\n)\n```\n\n### OpenAPI `validate_output` Option\n\n`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.\n\n```python\nmcp = FastMCP.from_openapi(\n openapi_spec=spec,\n client=client,\n validate_output=False,\n)\n```\n\n### Auth Token Injection and Azure OBO Dependencies\n\nNew 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.\n\n```python\nfrom fastmcp.server.dependencies import CurrentAccessToken, TokenClaim\nfrom fastmcp.server.auth import AccessToken\n\n@mcp.tool()\nasync def my_tool(\n token: AccessToken = CurrentAccessToken,\n user_id: str = TokenClaim(\"oid\"),\n): ...\n```\n\nFor Azure/Entra, the new `fastmcp[azure]` extra adds `EntraOBOToken`, which handles the On-Behalf-Of token exchange declaratively:\n\n```python\nfrom fastmcp.server.auth.providers.azure import EntraOBOToken\n\n@mcp.tool()\nasync def get_emails(\n graph_token: str = EntraOBOToken([\"https://graph.microsoft.com/Mail.Read\"]),\n):\n # graph_token is ready — OBO exchange happened automatically\n ...\n```\n\n### `generate-cli` Agent Skill Generation\n\n`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.\n\n### Background Task Notification Queue\n\nBackground 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.\n\n### Async Auth Checks\n\nAuth 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).\n\n### Optional `$ref` Dereferencing in Schemas\n\nSchema `$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:\n\n```python\nmcp = FastMCP(\"my-server\", dereference_schemas=False)\n```\n\nDereferencing is implemented as middleware (`DereferenceRefsMiddleware`) that runs at serve-time, so schemas are stored with `$ref` intact and only inlined when sent to clients.\n\n### Breaking: Deprecated `FastMCP()` Constructor Kwargs Removed\n\nSixteen 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.\n\n**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.\n\n```python\n# Before\nmcp = FastMCP(\"server\", host=\"0.0.0.0\", port=8080)\nmcp.run()\n\n# After\nmcp = FastMCP(\"server\")\nmcp.run(transport=\"http\", host=\"0.0.0.0\", port=8080)\n```\n\n**Duplicate handling** (`on_duplicate_tools`, `on_duplicate_resources`, `on_duplicate_prompts`): Use the unified `on_duplicate=` parameter.\n\n**Tag filtering** (`include_tags`, `exclude_tags`): Use `server.enable(tags=..., only=True)` and `server.disable(tags=...)` after construction.\n\n**Tool serializer** (`tool_serializer`): Return `ToolResult` from tools instead.\n\n**Tool transformations** (`tool_transformations`): Use `server.add_transform(ToolTransform(...))` after construction.\n\nThe `_deprecated_settings` attribute and `.settings` property are also removed. `ExperimentalSettings` has been deleted (dead code).\n\n### Breaking: `ui=` Renamed to `app=`\n\nThe 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.\n## 3.0.0beta2\n\n### CLI: `fastmcp list` and `fastmcp call`\n\nNew 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.\n\n```bash\n# Discover tools on a server\nfastmcp list http://localhost:8000/mcp\nfastmcp list server.py\nfastmcp list --command 'npx -y @modelcontextprotocol/server-github'\n\n# Call a tool\nfastmcp call server.py greet name=World\nfastmcp call http://localhost:8000/mcp search query=hello limit=5\nfastmcp call server.py create_item '{\"name\": \"Widget\", \"tags\": [\"a\", \"b\"]}'\n```\n\nKey features:\n- Tool arguments are auto-coerced using the tool's JSON schema (`limit=5` → int)\n- Single JSON objects work as positional args alongside `key=value` and `--input-json`\n- `--input-schema` / `--output-schema` for full JSON schemas, `--json` for machine-readable output\n- `--transport sse` for SSE servers, `--command` for stdio servers\n- Auto OAuth for HTTP targets (no-ops if server doesn't require auth)\n- Fuzzy tool name matching suggests alternatives on typos\n- Interactive terminal elicitation for tools that request user input mid-execution\n\nDocumentation: [CLI Querying](/cli/client)\n\n### CLI: `fastmcp discover` and name-based resolution\n\n`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`.\n\n```bash\n# See all configured servers\nfastmcp discover\n\n# Use a server by name\nfastmcp list weather\nfastmcp call weather get_forecast city=London\n\n# Target a specific source with source:name\nfastmcp list claude-code:my-server\nfastmcp call cursor:weather get_forecast city=London\n\n# Filter discovery to specific sources\nfastmcp discover --source claude-code --source cursor\n```\n\nDocumentation: [CLI Querying](/cli/client)\n\n### CLI: Expanded Reload File Watching\n\nThe `--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.\n\n### CLI: fastmcp install stdio\n\nThe new `fastmcp install stdio` command generates full `uv run` commands for running FastMCP servers over stdio ([#3032](https://github.com/PrefectHQ/fastmcp/pull/3032)).\n\n```bash\n# Generate command for a server\nfastmcp install stdio server.py\n\n# Outputs:\n# uv run --directory /path/to/project fastmcp run server.py\n```\n\nThe command automatically detects the project directory and generates the appropriate `uv run` invocation, making it easy to integrate FastMCP servers with MCP clients.\n\n### CIMD (Client ID Metadata Documents)\n\nCIMD 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.\n\n**Client usage:**\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\nasync with Client(\n \"https://mcp-server.example.com/mcp\",\n auth=OAuth(\n client_metadata_url=\"https://myapp.example.com/oauth/client.json\",\n ),\n) as client:\n await client.ping()\n```\n\nThe `OAuth` helper now supports deferred binding — `mcp_url` is optional when using `OAuth` with `Client(auth=...)`, since the transport provides the server URL automatically.\n\n**CLI tools for document management:**\n\n```bash\n# Generate a CIMD document\nfastmcp auth cimd create --name \"My App\" \\\n --redirect-uri \"http://localhost:*/callback\" \\\n --client-id \"https://myapp.example.com/oauth/client.json\" \\\n --output client.json\n\n# Validate a hosted document\nfastmcp auth cimd validate https://myapp.example.com/oauth/client.json\n```\n\n**Server-side support:**\n\nCIMD 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.\n\nKey details:\n- CIMD URLs must be HTTPS with a non-root path\n- `token_endpoint_auth_method` limited to `none` or `private_key_jwt` (no shared secrets)\n- `redirect_uris` in CIMD documents support wildcard port patterns (`http://localhost:*/callback`)\n- Servers fetch and cache documents with standard HTTP caching (ETag, Last-Modified, Cache-Control)\n- CIMD is a protocol-level feature — any auth provider implementing the spec can support it\n\nDocumentation: [CIMD Authentication](/clients/auth/cimd), [OAuth Proxy CIMD config](/servers/auth/oauth-proxy#cimd-support)\n\n### Pre-Registered OAuth Clients\n\nThe `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.\n\n```python\nfrom fastmcp import Client\nfrom fastmcp.client.auth import OAuth\n\nasync with Client(\n \"https://mcp-server.example.com/mcp\",\n auth=OAuth(\n client_id=\"my-registered-app\",\n client_secret=\"my-secret\",\n scopes=[\"read\", \"write\"],\n ),\n) as client:\n await client.ping()\n```\n\nThe 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`.\n\nDocumentation: [Pre-Registered Clients](/clients/auth/oauth#pre-registered-clients)\n\n### CLI: `fastmcp generate-cli`\n\n`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.\n\n```bash\n# Generate from any server spec\nfastmcp generate-cli weather\nfastmcp generate-cli http://localhost:8000/mcp\nfastmcp generate-cli server.py my_weather_cli.py\n\n# Use the generated script\npython my_weather_cli.py call-tool get_forecast --city London --days 3\npython my_weather_cli.py list-tools\npython my_weather_cli.py read-resource docs://readme\n```\n\nThe 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`.\n\nDocumentation: [Generate CLI](/cli/generate-cli)\n\n### CLI: Goose Integration\n\nNew `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.\n\n```bash\nfastmcp install goose server.py\nfastmcp install goose server.py --with pandas --python 3.11\n```\n\nAlso adds a full integration guide at [Goose Integration](/integrations/goose).\n\n### ResponseLimitingMiddleware\n\nNew 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.\n\n```python\nfrom fastmcp.server.middleware.response_limiting import ResponseLimitingMiddleware\n\n# Limit all tool responses to 500KB\nmcp.add_middleware(ResponseLimitingMiddleware(max_size=500_000))\n\n# Limit only specific tools, raise errors instead of truncating\nmcp.add_middleware(ResponseLimitingMiddleware(\n max_size=100_000,\n tools=[\"search\", \"fetch_data\"],\n raise_on_unstructured=True,\n))\n```\n\nKey features:\n- Configurable size limit (default 1MB)\n- Tool-specific filtering via `tools` parameter\n- Size metadata added to result's `meta` field for monitoring\n- Configurable `raise_on_structured` and `raise_on_unstructured` behavior\n\nDocumentation: [Middleware](/servers/middleware)\n\n### Background Task Context (SEP-1686)\n\n`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`.\n\n```python\n@mcp.tool(task=True)\nasync def interactive_task(ctx: Context) -> str:\n # Works transparently in both foreground and background task modes\n result = await ctx.elicit(\"Please provide additional input\", str)\n\n if isinstance(result, AcceptedElicitation):\n return f\"You provided: {result.data}\"\n else:\n return \"Elicitation was declined or cancelled\"\n```\n\n`ctx.is_background_task` and `ctx.task_id` are available for tools that need to branch on execution mode.\n\n### `require_auth` Removed\n\nThe `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.\n\n### MCP Apps (SDK Compatibility)\n\nSupport 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.\n\n**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.\n\n**Registering tools with app metadata:**\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.apps import AppConfig, ResourceCSP, ResourcePermissions\n\nmcp = FastMCP(\"My Server\")\n\n# Register the HTML bundle as a ui:// resource with CSP\n@mcp.resource(\n \"ui://my-app/view.html\",\n app=AppConfig(\n csp=ResourceCSP(resource_domains=[\"https://unpkg.com\"]),\n permissions=ResourcePermissions(clipboard_write={}),\n ),\n)\ndef app_html() -> str:\n from pathlib import Path\n return Path(\"./dist/index.html\").read_text()\n\n# Tool with UI — clients render an iframe alongside the result\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\"))\nasync def list_users() -> list[dict]:\n return [{\"id\": \"1\", \"name\": \"Alice\"}]\n\n# App-only tool — visible to the UI but hidden from the model\n@mcp.tool(app=AppConfig(resource_uri=\"ui://my-app/view.html\", visibility=[\"app\"]))\nasync def delete_user(id: str) -> dict:\n return {\"deleted\": True}\n```\n\nThe `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.\n\n**`ui://` resources** automatically get the correct MIME type (`text/html;profile=mcp-app`) unless you override it explicitly.\n\n**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()`:\n\n```python\nfrom fastmcp import Context\nfrom fastmcp.server.apps import AppConfig, UI_EXTENSION_ID\n\n@mcp.tool(app=AppConfig(resource_uri=\"ui://dashboard\"))\nasync def dashboard(ctx: Context) -> dict:\n data = compute_dashboard()\n if ctx.client_supports_extension(UI_EXTENSION_ID):\n return data\n return {\"summary\": format_text(data)}\n```\n\n**Key details:**\n- `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.\n- `csp` accepts a `ResourceCSP` model with structured domain lists: `connect_domains`, `resource_domains`, `frame_domains`, `base_uri_domains`\n- `permissions` accepts a `ResourcePermissions` model: `camera`, `microphone`, `geolocation`, `clipboard_write` (each set to `{}` to request)\n- `AppConfig` uses `extra=\"allow\"` for forward compatibility with future spec additions\n- Models use Pydantic aliases for wire format (`resourceUri`, `prefersBorder`, `connectDomains`, `clipboardWrite`)\n- Resource metadata (including CSP/permissions) is propagated to `resources/read` response content items so hosts can read it when rendering the iframe\n- `ctx.client_supports_extension(id)` is a general-purpose method — works for any extension, not just MCP Apps\n- `structuredContent` in tool results already works via `ToolResult` — MCP Apps clients use this to pass data into the iframe\n- The server does not strip `_meta.ui` for non-UI clients; per the spec, visibility enforcement is the host's responsibility\n\n**Future phases** will add a component DSL for building UIs declaratively, an in-repo renderer, and a `FastMCPApp` class.\n\nImplementation: `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).\n\n---\n\n## 3.0.0beta1\n\n### Provider-Based Architecture\n\nv3.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.\n\n**Core abstraction** (`src/fastmcp/server/providers/base.py`):\n```python\nclass Provider:\n async def list_tools(self) -> Sequence[Tool]: ...\n async def get_tool(self, name: str) -> Tool | None: ...\n async def list_resources(self) -> Sequence[Resource]: ...\n async def get_resource(self, uri: str) -> Resource | None: ...\n async def list_resource_templates(self) -> Sequence[ResourceTemplate]: ...\n async def get_resource_template(self, uri: str) -> ResourceTemplate | None: ...\n async def list_prompts(self) -> Sequence[Prompt]: ...\n async def get_prompt(self, name: str) -> Prompt | None: ...\n```\n\nProviders support:\n- **Lifecycle management**: `async def lifespan()` for setup/teardown\n- **Visibility control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode\n- **Transform stacking**: `provider.add_transform(Namespace(...))`, `provider.add_transform(ToolTransform(...))`\n\n### LocalProvider\n\n`LocalProvider` (`src/fastmcp/server/providers/local_provider.py`) manages components registered via decorators. Can be used standalone and attached to multiple servers:\n\n```python\nfrom fastmcp.server.providers import LocalProvider\n\nprovider = LocalProvider()\n\n@provider.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n# Attach to multiple servers\nserver1 = FastMCP(\"Server1\", providers=[provider])\nserver2 = FastMCP(\"Server2\", providers=[provider])\n```\n\n### ProxyProvider\n\n`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.\n\n```python\nfrom fastmcp.server import create_proxy\n\n# Create proxy to remote server\nserver = create_proxy(\"http://remote-server/mcp\")\n```\n\n### OpenAPIProvider\n\n`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.\n\n```python\nfrom fastmcp.server.providers.openapi import OpenAPIProvider\nimport httpx\n\nclient = httpx.AsyncClient(base_url=\"https://api.example.com\")\nprovider = OpenAPIProvider(openapi_spec=spec, client=client)\n\nmcp = FastMCP(\"API Server\", providers=[provider])\n```\n\nFeatures:\n- Automatic route-to-component mapping (GET → resource, POST/PUT/DELETE → tool)\n- Custom route mappings via `route_maps` or `route_map_fn`\n- Component customization via `mcp_component_fn`\n- Name collision detection and handling\n\n### FastMCPProvider\n\n`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.\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.providers import FastMCPProvider\nfrom fastmcp.server.transforms import Namespace\n\nmain = FastMCP(\"Main\")\nsub = FastMCP(\"Sub\")\n\n@sub.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n# Mount with namespace\nprovider = FastMCPProvider(sub)\nprovider.add_transform(Namespace(\"sub\"))\nmain.add_provider(provider)\n# Tool accessible as \"sub_greet\"\n```\n\n### Transforms\n\nTransforms 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.\n\n**Built-in transforms** (`src/fastmcp/server/transforms/`):\n\n- `Namespace` - adds prefixes to names (`tool` → `api_tool`) and path segments to URIs (`data://x` → `data://api/x`)\n- `ToolTransform` - modifies tool schemas (rename, description, tags, argument transforms)\n- `Visibility` - sets visibility state on components by key or tag (backs `enable()`/`disable()` API)\n- `VersionFilter` - filters components by version range (`version_gte`, `version_lt`)\n- `ResourcesAsTools` - exposes resources as tools for tool-only clients\n- `PromptsAsTools` - exposes prompts as tools for tool-only clients\n\n```python\nfrom fastmcp.server.transforms import Namespace, ToolTransform\nfrom fastmcp.tools.tool_transform import ToolTransformConfig\n\nprovider = SomeProvider()\nprovider.add_transform(Namespace(\"api\"))\nprovider.add_transform(ToolTransform({\n \"api_verbose_tool_name\": ToolTransformConfig(name=\"short\")\n}))\n\n# Stacking composes transformations\n# \"foo\" → \"api_foo\" (namespace) → \"short\" (rename)\n```\n\n**Custom transforms** subclass `Transform` and override needed methods:\n\n```python\nfrom collections.abc import Sequence\nfrom fastmcp.server.transforms import Transform, ListToolsNext, GetToolNext\nfrom fastmcp.tools import Tool\n\nclass TagFilter(Transform):\n def __init__(self, required_tags: set[str]):\n self.required_tags = required_tags\n\n async def list_tools(self, call_next: ListToolsNext) -> Sequence[Tool]:\n tools = await call_next() # Get tools from downstream\n return [t for t in tools if t.tags & self.required_tags]\n\n async def get_tool(self, name: str, call_next: GetToolNext) -> Tool | None:\n tool = await call_next(name)\n return tool if tool and tool.tags & self.required_tags else None\n```\n\nTransforms apply at two levels:\n- **Provider-level**: `provider.add_transform()` - affects only that provider's components\n- **Server-level**: `server.add_transform()` - affects all components from all providers\n\nDocumentation: `docs/servers/transforms/transforms.mdx`, `docs/servers/visibility.mdx`\n\n### ResourcesAsTools and PromptsAsTools\n\nThese 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.\n\n**ResourcesAsTools** generates `list_resources` and `read_resource` tools:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.transforms import ResourcesAsTools\n\nmcp = FastMCP(\"Server\")\n\n@mcp.resource(\"data://config\")\ndef get_config() -> dict:\n return {\"setting\": \"value\"}\n\nmcp.add_transform(ResourcesAsTools(mcp))\n# Now has list_resources and read_resource tools\n```\n\nThe `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.\n\n**PromptsAsTools** generates `list_prompts` and `get_prompt` tools:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.transforms import PromptsAsTools\n\nmcp = FastMCP(\"Server\")\n\n@mcp.prompt\ndef analyze_code(code: str, language: str = \"python\") -> str:\n return f\"Analyze this {language} code:\\n{code}\"\n\nmcp.add_transform(PromptsAsTools(mcp))\n# Now has list_prompts and get_prompt tools\n```\n\nThe `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.\n\nBoth transforms:\n- Capture a provider reference at construction for deferred querying\n- Route through `FastMCP.read_resource()` / `FastMCP.render_prompt()` when the provider is FastMCP, ensuring middleware chains execute\n- Fall back to direct provider methods for plain providers\n- Return JSON for easy parsing by tool-only clients\n\nDocumentation: `docs/servers/transforms/resources-as-tools.mdx`, `docs/servers/transforms/prompts-as-tools.mdx`\n\n---\n\n### Session-Scoped State\n\nv3.0 changes context state from request-scoped to session-scoped. State now persists across multiple tool calls within the same MCP session.\n\n```python\n@mcp.tool\nasync def increment_counter(ctx: Context) -> int:\n count = await ctx.get_state(\"counter\") or 0\n await ctx.set_state(\"counter\", count + 1)\n return count + 1\n```\n\nState 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:\n\n```python\nfrom key_value.aio.stores.redis import RedisStore\n\n# Use Redis for distributed deployments\nmcp = FastMCP(\"server\", session_state_store=RedisStore(...))\n```\n\n**Key details:**\n- Methods are now async: `await ctx.get_state()`, `await ctx.set_state()`, `await ctx.delete_state()`\n- State expires after 1 day (TTL) to prevent unbounded memory growth\n- Works during `on_initialize` middleware when using the same session object\n- For distributed HTTP, session identity comes from the `mcp-session-id` header\n\nDocumentation: `docs/servers/context.mdx`\n\n---\n\n### Visibility System\n\nComponents 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.\n\n```python\nmcp = FastMCP(\"Server\")\n\n# Disable by name and component type\nmcp.disable(names={\"dangerous_tool\"}, components=[\"tool\"])\n\n# Disable by tag\nmcp.disable(tags={\"admin\"})\n\n# Disable by version\nmcp.disable(names={\"old_tool\"}, version=\"1.0\", components=[\"tool\"])\n\n# Allowlist mode - only show components with these tags\nmcp.enable(tags={\"public\"}, only=True)\n\n# Enable overrides earlier disable (later transform wins)\nmcp.disable(tags={\"internal\"})\nmcp.enable(names={\"safe_tool\"}) # safe_tool is visible despite internal tag\n```\n\nWorks at both server and provider level. Supports:\n- **Blocklist mode** (default): All components visible except explicitly disabled\n- **Allowlist mode** (`only=True`): Only explicitly enabled components visible\n- **Tag-based filtering**: Enable/disable groups of components by tag\n- **Override semantics**: Later transforms override earlier marks (enable after disable = enabled)\n- **Transform ordering**: Visibility transforms are injected at the point you call them, so component state is known\n\n#### Per-Session Visibility\n\nServer-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)):\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.context import Context\n\nmcp = FastMCP(\"Server\")\n\n@mcp.tool(tags={\"premium\"})\ndef premium_analysis(data: str) -> str:\n return f\"Premium analysis of: {data}\"\n\n@mcp.tool\nasync def unlock_premium(ctx: Context) -> str:\n \"\"\"Unlock premium features for this session only.\"\"\"\n await ctx.enable_components(tags={\"premium\"})\n return \"Premium features unlocked\"\n\n@mcp.tool\nasync def reset_features(ctx: Context) -> str:\n \"\"\"Reset to default feature set.\"\"\"\n await ctx.reset_visibility()\n return \"Features reset to defaults\"\n\n# Globally disabled - sessions unlock individually\nmcp.disable(tags={\"premium\"})\n```\n\nSession visibility methods:\n- `await ctx.enable_components(...)`: Enable components for this session\n- `await ctx.disable_components(...)`: Disable components for this session\n- `await ctx.reset_visibility()`: Clear session rules, return to global defaults\n\nSession rules override global transforms. FastMCP automatically sends `ToolListChangedNotification` (and resource/prompt equivalents) to affected sessions when visibility changes.\n\nDocumentation: `docs/servers/visibility.mdx`\n\n---\n\n### Component Versioning\n\nv3.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.\n\n**Declaring versions:**\n\n```python\n@mcp.tool(version=\"1.0\")\ndef add(x: int, y: int) -> int:\n return x + y\n\n@mcp.tool(version=\"2.0\")\ndef add(x: int, y: int, z: int = 0) -> int:\n return x + y + z\n\n# Only v2.0 is exposed to clients via list_tools()\n# Calling \"add\" invokes the v2.0 implementation\n```\n\n**Version comparison:**\n- Uses PEP 440 semantic versioning (1.10 > 1.9 > 1.2)\n- Falls back to string comparison for non-PEP 440 versions (dates like `2025-01-15` work)\n- Unversioned components sort lower than any versioned component\n- The `v` prefix is normalized (`v1.0` equals `1.0`)\n\n**Version visibility in meta:**\n\nList operations expose all available versions in the component's `meta` field:\n\n```python\ntools = await client.list_tools()\n# Each tool's meta includes:\n# - meta[\"fastmcp\"][\"version\"]: the version of this component (\"2.0\")\n# - meta[\"fastmcp\"][\"versions\"]: all available versions [\"2.0\", \"1.0\"]\n```\n\n**Retrieving and calling specific versions:**\n\n```python\n# Get the highest version (default)\ntool = await server.get_tool(\"add\")\n\n# Get a specific version\ntool_v1 = await server.get_tool(\"add\", version=\"1.0\")\n\n# Call a specific version\nresult = await server.call_tool(\"add\", {\"x\": 1, \"y\": 2}, version=\"1.0\")\n```\n\n**Client version requests:**\n\nThe FastMCP client supports version selection:\n\n```python\nasync with Client(server) as client:\n # Call specific tool version\n result = await client.call_tool(\"add\", {\"x\": 1, \"y\": 2}, version=\"1.0\")\n\n # Get specific prompt version\n prompt = await client.get_prompt(\"my_prompt\", {\"text\": \"...\"}, version=\"2.0\")\n```\n\nFor generic MCP clients, pass version via `_meta` in arguments:\n\n```json\n{\n \"x\": 1,\n \"y\": 2,\n \"_meta\": {\n \"fastmcp\": {\n \"version\": \"1.0\"\n }\n }\n}\n```\n\n**VersionFilter transform:**\n\nThe `VersionFilter` transform enables serving different API versions from a single codebase:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.providers import LocalProvider\nfrom fastmcp.server.transforms import VersionFilter\n\n# Define components on a shared provider\ncomponents = LocalProvider()\n\n@components.tool(version=\"1.0\")\ndef calculate(x: int, y: int) -> int:\n return x + y\n\n@components.tool(version=\"2.0\")\ndef calculate(x: int, y: int, z: int = 0) -> int:\n return x + y + z\n\n# Create servers that share the provider with different filters\napi_v1 = FastMCP(\"API v1\", providers=[components])\napi_v1.add_transform(VersionFilter(version_lt=\"2.0\"))\n\napi_v2 = FastMCP(\"API v2\", providers=[components])\napi_v2.add_transform(VersionFilter(version_gte=\"2.0\"))\n```\n\nParameters mirror comparison operators:\n- `version_gte`: Versions >= this value pass through\n- `version_lt`: Versions < this value pass through\n\n**Key format:**\n\nComponent keys now include a version suffix using `@` as a delimiter:\n- Versioned: `tool:add@1.0`, `resource:data://config@2.0`\n- Unversioned: `tool:add@`, `resource:data://config@`\n\nThe `@` is always present (even for unversioned components) to enable unambiguous parsing of URIs that may contain `@`.\n\n---\n\n### Type-Safe Canonical Results\n\nv3.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)).\n\n#### ToolResult\n\n`ToolResult` (`src/fastmcp/tools/tool.py:79`) provides structured tool responses:\n\n```python\nfrom fastmcp.tools import ToolResult\n\n@mcp.tool\ndef process(data: str) -> ToolResult:\n return ToolResult(\n content=[TextContent(type=\"text\", text=\"Done\")],\n structured_content={\"status\": \"success\", \"count\": 42},\n meta={\"processing_time_ms\": 150}\n )\n```\n\nFields:\n- `content`: List of MCP ContentBlocks (text, images, etc.)\n- `structured_content`: Dict matching tool's output schema\n- `meta`: Runtime metadata passed to MCP as `_meta`\n\n#### ResourceResult\n\n`ResourceResult` (`src/fastmcp/resources/resource.py:117`) provides structured resource responses:\n\n```python\nfrom fastmcp.resources import ResourceResult, ResourceContent\n\n@mcp.resource(\"data://items\")\ndef get_items() -> ResourceResult:\n return ResourceResult(\n contents=[\n ResourceContent({\"key\": \"value\"}), # auto-serialized to JSON\n ResourceContent(b\"binary data\"),\n ],\n meta={\"count\": 2}\n )\n```\n\nAccepts strings, bytes, or `list[ResourceContent]` for flexible content handling.\n\n#### PromptResult\n\n`PromptResult` (`src/fastmcp/prompts/prompt.py:109`) provides structured prompt responses:\n\n```python\nfrom fastmcp.prompts import PromptResult, Message\n\n@mcp.prompt\ndef conversation() -> PromptResult:\n return PromptResult(\n messages=[\n Message(\"What's the weather?\"),\n Message(\"It's sunny today.\", role=\"assistant\"),\n ],\n meta={\"generated_at\": \"2024-01-01\"}\n )\n```\n\n---\n\n### Background Tasks (SEP-1686)\n\nv3.0 implements MCP SEP-1686 for background task execution via Docket integration.\n\n**Configuration** (`src/fastmcp/server/tasks/config.py`):\n\n```python\nfrom fastmcp.server.tasks import TaskConfig\n\n@mcp.tool(task=TaskConfig(mode=\"required\"))\nasync def long_running_task():\n # Must be executed as background task\n ...\n\n@mcp.tool(task=TaskConfig(mode=\"optional\"))\nasync def flexible_task():\n # Supports both sync and task execution\n ...\n\n@mcp.tool(task=True) # Shorthand for mode=\"optional\"\nasync def simple_task():\n ...\n```\n\nTask modes:\n- `\"forbidden\"`: Component does not support task execution (default)\n- `\"optional\"`: Supports both synchronous and task execution\n- `\"required\"`: Must be executed as background task\n\nRequires Docket server for task scheduling and result polling.\n\n---\n\n### Decorators Return Functions\n\nv3.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.\n\n**v3 behavior (default):**\n```python\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n# greet is still your function - call it directly\ngreet(\"World\") # \"Hello, World!\"\n```\n\n**Why this matters:**\n- Functions stay callable - useful for testing and reuse\n- Instance methods just work: `mcp.add_tool(obj.method)`\n- Matches how Flask, FastAPI, and Typer decorators behave\n\n**For v2 compatibility:**\n\n```python\nimport fastmcp\n\n# v2 behavior: decorators return FunctionTool/FunctionResource/FunctionPrompt objects\nfastmcp.settings.decorator_mode = \"object\"\n```\n\nEnvironment variable: `FASTMCP_DECORATOR_MODE=object`\n\n---\n\n### CLI Auto-Reload\n\nThe `--reload` flag enables file watching with automatic server restarts for development ([#2816](https://github.com/PrefectHQ/fastmcp/pull/2816)).\n\n```bash\n# Watch for changes and restart\nfastmcp run server.py --reload\n\n# Watch specific directories\nfastmcp run server.py --reload --reload-dir ./src --reload-dir ./lib\n\n# Works with any transport\nfastmcp run server.py --reload --transport http --port 8080\n```\n\nImplementation (`src/fastmcp/cli/run.py`):\n- Uses `watchfiles` for efficient file monitoring\n- Runs server as subprocess for clean restarts\n- Stateless mode for seamless reconnection after restart\n- stdio: Full MCP features including elicitation\n- HTTP: Limited bidirectional features during reload\n\nAlso available with `fastmcp dev inspector`:\n```bash\nfastmcp dev inspector server.py # Includes --reload by default\n```\n\n---\n\n### Component Authorization\n\nv3.0 introduces callable-based authorization for tools, resources, and prompts ([#2855](https://github.com/PrefectHQ/fastmcp/pull/2855)).\n\n**Component-level auth**:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.auth import require_scopes\n\nmcp = FastMCP()\n\n@mcp.tool(auth=require_scopes(\"write\"))\ndef protected_tool(): ...\n\n@mcp.resource(\"data://secret\", auth=require_scopes(\"read\"))\ndef secret_data(): ...\n\n@mcp.prompt(auth=require_scopes(\"admin\"))\ndef admin_prompt(): ...\n```\n\n**Server-wide auth via middleware**:\n\n```python\nfrom fastmcp.server.middleware import AuthMiddleware\nfrom fastmcp.server.auth import require_scopes, restrict_tag\n\n# Require specific scope for all components\nmcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes(\"api\"))])\n\n# Tag-based restrictions\nmcp = FastMCP(middleware=[\n AuthMiddleware(auth=restrict_tag(\"admin\", scopes=[\"admin\"]))\n])\n```\n\nBuilt-in checks:\n- `require_scopes(*scopes)`: Requires specific OAuth scopes\n- `restrict_tag(tag, scopes)`: Requires scopes only for tagged components\n\nCustom checks receive `AuthContext` with `token` and `component`:\n\n```python\ndef custom_check(ctx: AuthContext) -> bool:\n return ctx.token is not None and \"admin\" in ctx.token.scopes\n```\n\nSTDIO transport bypasses all auth checks (no OAuth concept).\n\n---\n\n### FileSystemProvider\n\nv3.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.\n\n**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.\n\n**Usage** ([#2823](https://github.com/PrefectHQ/fastmcp/pull/2823)):\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.providers import FileSystemProvider\n\n# Scans mcp/ directory for decorated functions\nmcp = FastMCP(\"server\", providers=[FileSystemProvider(\"mcp/\")])\n```\n\n**Tool files are self-contained**:\n\n```python\n# mcp/tools/greet.py\nfrom fastmcp.tools import tool\n\n@tool\ndef greet(name: str) -> str:\n \"\"\"Greet someone by name.\"\"\"\n return f\"Hello, {name}!\"\n```\n\nFeatures:\n- **Standalone decorators**: `@tool`, `@resource`, `@prompt` from `fastmcp.tools`, `fastmcp.resources`, `fastmcp.prompts` ([#2832](https://github.com/PrefectHQ/fastmcp/pull/2832))\n- **Reload mode**: `FileSystemProvider(\"mcp/\", reload=True)` re-scans on every request for development\n- **Package support**: Directories with `__init__.py` support relative imports\n- **Warning deduplication**: Broken imports warn once per file modification\n\nDocumentation: [FileSystemProvider](/servers/providers/filesystem)\n\n---\n\n### SkillsProvider\n\nv3.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.\n\n**Usage**:\n\n```python\nfrom pathlib import Path\nfrom fastmcp import FastMCP\nfrom fastmcp.server.providers.skills import SkillsDirectoryProvider\n\nmcp = FastMCP(\"Skills Server\")\nmcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / \".claude\" / \"skills\"))\n```\n\nEach subdirectory with a `SKILL.md` file becomes a discoverable skill. Clients see:\n- `skill://{name}/SKILL.md` - Main instruction file\n- `skill://{name}/_manifest` - JSON listing of all files with sizes and hashes\n- `skill://{name}/{path}` - Supporting files (via template or resources)\n\n**Two-layer architecture**:\n- `SkillProvider` - Handles a single skill folder\n- `SkillsDirectoryProvider` - Scans directories, creates a `SkillProvider` per valid skill\n\n**Vendor providers** with locked default paths:\n\n| Provider | Directory |\n|----------|-----------|\n| `ClaudeSkillsProvider` | `~/.claude/skills/` |\n| `CursorSkillsProvider` | `~/.cursor/skills/` |\n| `VSCodeSkillsProvider` | `~/.copilot/skills/` |\n| `CodexSkillsProvider` | `/etc/codex/skills/`, `~/.codex/skills/` |\n| `GeminiSkillsProvider` | `~/.gemini/skills/` |\n| `GooseSkillsProvider` | `~/.config/agents/skills/` |\n| `CopilotSkillsProvider` | `~/.copilot/skills/` |\n| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |\n\n**Progressive disclosure**: By default, supporting files are hidden from `list_resources()` and accessed via template. Set `supporting_files=\"resources\"` for full enumeration.\n\nDocumentation: [Skills Provider](/servers/providers/skills)\n\n---\n\n### OpenTelemetry Tracing\n\nv3.0 adds OpenTelemetry instrumentation for observability into server and client operations ([#2869](https://github.com/PrefectHQ/fastmcp/pull/2869)).\n\n**Server spans**: Created for tool calls, resource reads, and prompt renders with attributes including component key, provider type, session ID, and auth context.\n\n**Client spans**: Wrap outgoing calls with W3C trace context propagation via request meta.\n\n```python\n# Tracing is passive - configure an OTel SDK to export spans\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\n\nprovider = TracerProvider()\nprovider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# Use fastmcp normally - spans export to your configured backend\n```\n\nComponents 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.).\n\nDocumentation: [Telemetry](/servers/telemetry)\n\n---\n\n### Pagination\n\nv3.0 adds pagination support for list operations when servers expose many components ([#2903](https://github.com/PrefectHQ/fastmcp/pull/2903)).\n\n```python\nfrom fastmcp import FastMCP\n\n# Enable pagination with 50 items per page\nserver = FastMCP(\"ComponentRegistry\", list_page_size=50)\n```\n\nWhen `list_page_size` is set, `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` paginate responses with `nextCursor` for subsequent pages.\n\n**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:\n\n```python\nasync with Client(server) as client:\n result = await client.list_tools_mcp()\n while result.nextCursor:\n result = await client.list_tools_mcp(cursor=result.nextCursor)\n```\n\nDocumentation: [Pagination](/servers/pagination)\n\n---\n\n### Composable Lifespans\n\nLifespans can be combined with the `|` operator for modular setup/teardown ([#2828](https://github.com/PrefectHQ/fastmcp/pull/2828)):\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.lifespan import lifespan\n\n@lifespan\nasync def db_lifespan(server):\n db = await connect_db()\n try:\n yield {\"db\": db}\n finally:\n await db.close()\n\n@lifespan\nasync def cache_lifespan(server):\n cache = await connect_cache()\n try:\n yield {\"cache\": cache}\n finally:\n await cache.close()\n\nmcp = FastMCP(\"server\", lifespan=db_lifespan | cache_lifespan)\n```\n\nBoth enter lifespans in order and exit in reverse (LIFO). Context dicts are merged.\n\nAlso adds `combine_lifespans()` utility for FastAPI integration:\n\n```python\nfrom fastmcp.utilities.lifespan import combine_lifespans\n\napp = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))\n```\n\nDocumentation: [Lifespan](/servers/lifespan)\n\n---\n\n### Tool Timeout\n\nTools can limit foreground execution time with a `timeout` parameter ([#2872](https://github.com/PrefectHQ/fastmcp/pull/2872)):\n\n```python\n@mcp.tool(timeout=30.0)\nasync def fetch_data(url: str) -> dict:\n \"\"\"Fetch with 30-second timeout.\"\"\"\n ...\n```\n\nWhen 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.\n\nNote: This timeout applies to foreground execution only. Background tasks (`task=True`) execute in Docket workers where this timeout isn't enforced.\n\n---\n\n### PingMiddleware\n\nSends periodic server-to-client pings to keep long-lived connections alive ([#2838](https://github.com/PrefectHQ/fastmcp/pull/2838)):\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.server.middleware import PingMiddleware\n\nmcp = FastMCP(\"server\")\nmcp.add_middleware(PingMiddleware(interval_ms=5000))\n```\n\nThe 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.\n\n---\n\n### Context.transport Property\n\nTools can detect which transport is active ([#2850](https://github.com/PrefectHQ/fastmcp/pull/2850)):\n\n```python\nfrom fastmcp import FastMCP, Context\n\nmcp = FastMCP(\"example\")\n\n@mcp.tool\ndef my_tool(ctx: Context) -> str:\n if ctx.transport == \"stdio\":\n return \"short response\"\n return \"detailed response with more context\"\n```\n\nReturns `Literal[\"stdio\", \"sse\", \"streamable-http\"]` when running, or `None` outside a server context.\n\n---\n\n### Automatic Threadpool for Sync Functions\n\nSynchronous 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)):\n\n```python\nimport time\n\n@mcp.tool\ndef slow_tool():\n time.sleep(10) # No longer blocks other requests\n return \"done\"\n```\n\nThree 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.\n\n---\n\n### CLI Update Notifications\n\nThe CLI notifies users when a newer FastMCP version is available on PyPI ([#2840](https://github.com/PrefectHQ/fastmcp/pull/2840)).\n\n**Setting**: `FASTMCP_CHECK_FOR_UPDATES`\n- `\"stable\"` - Check for stable releases (default)\n- `\"prerelease\"` - Include alpha/beta/rc versions\n- `\"off\"` - Disable\n\n12-hour cache, 2-second timeout, fails silently on network errors.\n\n---\n\n### Deprecated Features\n\nThese emit deprecation warnings but continue to work.\n\n#### Mount Prefix Parameter\n\nThe `prefix` parameter for `mount()` renamed to `namespace`:\n\n```python\n# Deprecated\nmain.mount(subserver, prefix=\"api\")\n\n# New\nmain.mount(subserver, namespace=\"api\")\n```\n\n#### Tag Filtering, Tool Serializer, Tool Transformations Init Parameters\n\nThese 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.\n\n---\n\n### Breaking Changes\n\n#### WSTransport Removed\n\nThe deprecated `WSTransport` client transport has been removed ([#2826](https://github.com/PrefectHQ/fastmcp/pull/2826)). Use `StreamableHttpTransport` instead.\n\n#### Decorators Return Functions\n\nDecorators (`@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.\n\n```python\n# v2.x\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\nisinstance(greet, FunctionTool) # True\n\n# v3.0\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\nisinstance(greet, FunctionTool) # False\ncallable(greet) # True - it's still your function\ngreet(\"World\") # \"Hello, World!\"\n```\n\nSet `FASTMCP_DECORATOR_MODE=object` or `fastmcp.settings.decorator_mode = \"object\"` for v2 behavior.\n\n#### Component Enable/Disable Moved to Server/Provider\n\nThe `enabled` field and `enable()`/`disable()` methods removed from component objects:\n\n```python\n# v2.x\ntool = await server.get_tool(\"my_tool\")\ntool.disable()\n\n# v3.0\nserver.disable(names={\"my_tool\"}, components=[\"tool\"])\n```\n\n#### Component Lookup Methods\n\nServer lookup and listing methods have updated signatures:\n\n- Parameter names: `get_tool(name=...)`, `get_resource(uri=...)`, etc. (was `key`)\n- Plural listing methods renamed: `get_tools()` → `list_tools()`, `get_resources()` → `list_resources()`, etc.\n- Return types: `list_tools()`, `list_resources()`, etc. return lists instead of dicts\n\n```python\n# v2.x\ntools = await server.get_tools()\ntool = tools[\"my_tool\"]\n\n# v3.0\ntools = await server.list_tools()\ntool = next((t for t in tools if t.name == \"my_tool\"), None)\n```\n\n#### Prompt Return Types\n\nPrompt functions now use `Message` instead of `mcp.types.PromptMessage`:\n\n```python\n# v2.x\nfrom mcp.types import PromptMessage, TextContent\n\n@mcp.prompt\ndef my_prompt() -> PromptMessage:\n return PromptMessage(role=\"user\", content=TextContent(type=\"text\", text=\"Hello\"))\n\n# v3.0\nfrom fastmcp.prompts import Message\n\n@mcp.prompt\ndef my_prompt() -> Message:\n return Message(\"Hello\") # role defaults to \"user\"\n```\n\n#### Auth Provider Environment Variables Removed\n\nAuth providers no longer auto-load from environment variables ([#2752](https://github.com/PrefectHQ/fastmcp/pull/2752)):\n\n```python\n# v2.x - auto-loaded from FASTMCP_SERVER_AUTH_GITHUB_*\nauth = GitHubProvider()\n\n# v3.0 - explicit configuration\nimport os\nauth = GitHubProvider(\n client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n)\n```\n\nSee `docs/development/v3-notes/auth-provider-env-vars.mdx` for rationale.\n\n#### Server Banner Environment Variable\n\n`FASTMCP_SHOW_CLI_BANNER` → `FASTMCP_SHOW_SERVER_BANNER` ([#2771](https://github.com/PrefectHQ/fastmcp/pull/2771))\n\nNow applies to all server startup methods, not just the CLI.\n\n#### Context State Methods Are Async\n\n`ctx.set_state()` and `ctx.get_state()` are now async and session-scoped:\n\n```python\n# v2.x\nctx.set_state(\"key\", \"value\")\nvalue = ctx.get_state(\"key\")\n\n# v3.0\nawait ctx.set_state(\"key\", \"value\")\nvalue = await ctx.get_state(\"key\")\n```\n\nState now persists across requests within a session. See \"Session-Scoped State\" above.\n" }, { "path": "docs/docs.json", "content": "{\n \"$schema\": \"https://mintlify.com/docs.json\",\n \"appearance\": {\n \"default\": \"system\",\n \"strict\": false\n },\n \"background\": {\n \"color\": {\n \"dark\": \"#222831\",\n \"light\": \"#EEEEEE\"\n },\n \"decoration\": \"gradient\"\n },\n \"banner\": {\n \"content\": \"Deploy FastMCP servers for free on [Prefect Horizon](https://www.prefect.io/horizon)\"\n },\n \"colors\": {\n \"dark\": \"#f72585\",\n \"light\": \"#4cc9f0\",\n \"primary\": \"#2d00f7\"\n },\n \"contextual\": {\n \"options\": [\n \"copy\",\n \"view\"\n ]\n },\n \"description\": \"The fast, Pythonic way to build MCP servers and clients.\",\n \"errors\": {\n \"404\": {\n \"description\": \"You\\u2019ve wandered outside the context.\",\n \"redirect\": false,\n \"title\": \"Don't panic.\"\n }\n },\n \"favicon\": {\n \"dark\": \"/assets/brand/favicon-dark.svg\",\n \"light\": \"/assets/brand/favicon-light.svg\"\n },\n \"footer\": {\n \"socials\": {\n \"discord\": \"https://discord.gg/uu8dJCgttd\",\n \"github\": \"https://github.com/PrefectHQ/fastmcp\",\n \"website\": \"https://www.prefect.io\",\n \"x\": \"https://x.com/fastmcp\"\n }\n },\n \"integrations\": {\n \"ga4\": {\n \"measurementId\": \"G-64R5W1TJXG\"\n }\n },\n \"interaction\": {\n \"drilldown\": false\n },\n \"logo\": {\n \"dark\": \"/assets/brand/wordmark-white.png\",\n \"light\": \"/assets/brand/wordmark.png\"\n },\n \"name\": \"FastMCP\",\n \"navbar\": {\n \"links\": [\n {\n \"href\": \"https://discord.gg/uu8dJCgttd\",\n \"icon\": \"discord\",\n \"label\": \"\"\n },\n {\n \"href\": \"https://prefect.io/horizon\",\n \"icon\": \"cloud\",\n \"label\": \"Prefect Horizon\"\n }\n ],\n \"primary\": {\n \"href\": \"https://github.com/PrefectHQ/fastmcp\",\n \"type\": \"github\"\n }\n },\n \"navigation\": {\n \"versions\": [\n {\n \"dropdowns\": [\n {\n \"dropdown\": \"Documentation\",\n \"groups\": [\n {\n \"group\": \"Get Started\",\n \"pages\": [\n \"getting-started/welcome\",\n \"getting-started/installation\",\n \"getting-started/quickstart\"\n ]\n },\n {\n \"group\": \"Servers\",\n \"pages\": [\n \"servers/server\",\n {\n \"collapsed\": true,\n \"group\": \"Core Components\",\n \"icon\": \"toolbox\",\n \"pages\": [\n \"servers/tools\",\n \"servers/resources\",\n \"servers/prompts\",\n \"servers/context\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"Features\",\n \"icon\": \"stars\",\n \"pages\": [\n \"servers/tasks\",\n \"servers/composition\",\n \"servers/dependency-injection\",\n \"servers/elicitation\",\n \"servers/icons\",\n \"servers/lifespan\",\n \"servers/logging\",\n \"servers/middleware\",\n \"servers/pagination\",\n \"servers/progress\",\n \"servers/sampling\",\n \"servers/storage-backends\",\n \"servers/telemetry\",\n \"servers/testing\",\n \"servers/versioning\"\n ],\n \"tag\": \"UPDATED\"\n },\n {\n \"collapsed\": true,\n \"group\": \"Providers\",\n \"icon\": \"layer-group\",\n \"pages\": [\n \"servers/providers/overview\",\n \"servers/providers/local\",\n \"servers/providers/filesystem\",\n \"servers/providers/proxy\",\n \"servers/providers/skills\",\n \"servers/providers/custom\"\n ],\n \"tag\": \"NEW\"\n },\n {\n \"collapsed\": true,\n \"group\": \"Transforms\",\n \"icon\": \"wand-magic-sparkles\",\n \"pages\": [\n \"servers/transforms/transforms\",\n \"servers/transforms/namespace\",\n \"servers/transforms/tool-transformation\",\n \"servers/visibility\",\n \"servers/transforms/code-mode\",\n \"servers/transforms/tool-search\",\n \"servers/transforms/resources-as-tools\",\n \"servers/transforms/prompts-as-tools\"\n ],\n \"tag\": \"NEW\"\n },\n {\n \"collapsed\": true,\n \"group\": \"Authentication\",\n \"icon\": \"key\",\n \"pages\": [\n \"servers/auth/authentication\",\n \"servers/auth/token-verification\",\n \"servers/auth/remote-oauth\",\n \"servers/auth/oauth-proxy\",\n \"servers/auth/oidc-proxy\",\n \"servers/auth/full-oauth-server\",\n \"servers/auth/multi-auth\"\n ],\n \"tag\": \"UPDATED\"\n },\n \"servers/authorization\",\n {\n \"collapsed\": true,\n \"group\": \"Deployment\",\n \"icon\": \"rocket\",\n \"pages\": [\n \"deployment/running-server\",\n \"deployment/http\",\n \"deployment/prefect-horizon\",\n \"deployment/server-configuration\"\n ]\n }\n ]\n },\n {\n \"group\": \"Apps\",\n \"pages\": [\n \"apps/overview\",\n \"apps/prefab\",\n \"apps/patterns\",\n \"apps/development\",\n \"apps/low-level\"\n ]\n },\n {\n \"group\": \"Clients\",\n \"pages\": [\n \"clients/client\",\n \"clients/transports\",\n {\n \"collapsed\": true,\n \"group\": \"Core Operations\",\n \"icon\": \"toolbox\",\n \"pages\": [\n \"clients/tools\",\n \"clients/resources\",\n \"clients/prompts\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"Handlers\",\n \"icon\": \"hand\",\n \"pages\": [\n \"clients/notifications\",\n \"clients/sampling\",\n \"clients/elicitation\",\n \"clients/tasks\",\n \"clients/progress\",\n \"clients/logging\",\n \"clients/roots\"\n ],\n \"tag\": \"UPDATED\"\n },\n {\n \"collapsed\": true,\n \"group\": \"Authentication\",\n \"icon\": \"key\",\n \"pages\": [\n \"clients/auth/oauth\",\n \"clients/auth/cimd\",\n \"clients/auth/bearer\"\n ],\n \"tag\": \"UPDATED\"\n }\n ]\n },\n {\n \"group\": \"Integrations\",\n \"pages\": [\n {\n \"collapsed\": true,\n \"group\": \"Auth\",\n \"icon\": \"key\",\n \"pages\": [\n \"integrations/auth0\",\n \"integrations/authkit\",\n \"integrations/aws-cognito\",\n \"integrations/azure\",\n \"integrations/descope\",\n \"integrations/discord\",\n \"integrations/eunomia-authorization\",\n \"integrations/github\",\n \"integrations/google\",\n \"integrations/oci\",\n \"integrations/permit\",\n \"integrations/propelauth\",\n \"integrations/scalekit\",\n \"integrations/supabase\",\n \"integrations/workos\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"Web Frameworks\",\n \"icon\": \"code\",\n \"pages\": [\n \"integrations/fastapi\",\n \"integrations/openapi\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"AI Assistants\",\n \"icon\": \"robot\",\n \"pages\": [\n \"integrations/chatgpt\",\n \"integrations/claude-code\",\n \"integrations/claude-desktop\",\n \"integrations/cursor\",\n \"integrations/gemini-cli\",\n \"integrations/goose\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"AI SDKs\",\n \"icon\": \"microchip\",\n \"pages\": [\n \"integrations/anthropic\",\n \"integrations/gemini\",\n \"integrations/openai\"\n ]\n },\n \"integrations/mcp-json-configuration\"\n ]\n },\n {\n \"group\": \"CLI\",\n \"pages\": [\n \"cli/overview\",\n \"cli/running\",\n \"cli/install-mcp\",\n \"cli/inspecting\",\n \"cli/client\",\n \"cli/generate-cli\",\n \"cli/auth\"\n ]\n },\n {\n \"group\": \"More\",\n \"pages\": [\n \"more/settings\",\n {\n \"collapsed\": true,\n \"group\": \"Upgrading\",\n \"icon\": \"up\",\n \"pages\": [\n \"getting-started/upgrading/from-fastmcp-2\",\n \"getting-started/upgrading/from-mcp-sdk\",\n \"getting-started/upgrading/from-low-level-sdk\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"Development\",\n \"icon\": \"code\",\n \"pages\": [\n \"development/contributing\",\n \"development/tests\",\n \"development/releases\",\n \"patterns/contrib\"\n ]\n },\n {\n \"collapsed\": true,\n \"group\": \"What's New\",\n \"icon\": \"sparkles\",\n \"pages\": [\n \"updates\",\n \"changelog\"\n ]\n }\n ]\n }\n ],\n \"icon\": \"book\"\n },\n {\n \"anchors\": [\n {\n \"anchor\": \"Python SDK\",\n \"icon\": \"python\",\n \"pages\": [\n \"python-sdk/fastmcp-decorators\",\n \"python-sdk/fastmcp-dependencies\",\n \"python-sdk/fastmcp-exceptions\",\n \"python-sdk/fastmcp-mcp_config\",\n \"python-sdk/fastmcp-settings\",\n \"python-sdk/fastmcp-telemetry\",\n {\n \"group\": \"fastmcp.cli\",\n \"pages\": [\n \"python-sdk/fastmcp-cli-__init__\",\n \"python-sdk/fastmcp-cli-apps_dev\",\n \"python-sdk/fastmcp-cli-auth\",\n \"python-sdk/fastmcp-cli-cimd\",\n \"python-sdk/fastmcp-cli-cli\",\n \"python-sdk/fastmcp-cli-client\",\n \"python-sdk/fastmcp-cli-discovery\",\n \"python-sdk/fastmcp-cli-generate\",\n {\n \"group\": \"install\",\n \"pages\": [\n \"python-sdk/fastmcp-cli-install-__init__\",\n \"python-sdk/fastmcp-cli-install-claude_code\",\n \"python-sdk/fastmcp-cli-install-claude_desktop\",\n \"python-sdk/fastmcp-cli-install-cursor\",\n \"python-sdk/fastmcp-cli-install-gemini_cli\",\n \"python-sdk/fastmcp-cli-install-goose\",\n \"python-sdk/fastmcp-cli-install-mcp_json\",\n \"python-sdk/fastmcp-cli-install-shared\",\n \"python-sdk/fastmcp-cli-install-stdio\"\n ]\n },\n \"python-sdk/fastmcp-cli-run\",\n \"python-sdk/fastmcp-cli-tasks\"\n ]\n },\n {\n \"group\": \"fastmcp.client\",\n \"pages\": [\n \"python-sdk/fastmcp-client-__init__\",\n {\n \"group\": \"auth\",\n \"pages\": [\n \"python-sdk/fastmcp-client-auth-__init__\",\n \"python-sdk/fastmcp-client-auth-bearer\",\n \"python-sdk/fastmcp-client-auth-oauth\"\n ]\n },\n \"python-sdk/fastmcp-client-client\",\n \"python-sdk/fastmcp-client-elicitation\",\n \"python-sdk/fastmcp-client-logging\",\n \"python-sdk/fastmcp-client-messages\",\n {\n \"group\": \"mixins\",\n \"pages\": [\n \"python-sdk/fastmcp-client-mixins-__init__\",\n \"python-sdk/fastmcp-client-mixins-prompts\",\n \"python-sdk/fastmcp-client-mixins-resources\",\n \"python-sdk/fastmcp-client-mixins-task_management\",\n \"python-sdk/fastmcp-client-mixins-tools\"\n ]\n },\n \"python-sdk/fastmcp-client-oauth_callback\",\n \"python-sdk/fastmcp-client-progress\",\n \"python-sdk/fastmcp-client-roots\",\n {\n \"group\": \"sampling\",\n \"pages\": [\n \"python-sdk/fastmcp-client-sampling-__init__\",\n {\n \"group\": \"handlers\",\n \"pages\": [\n \"python-sdk/fastmcp-client-sampling-handlers-__init__\",\n \"python-sdk/fastmcp-client-sampling-handlers-anthropic\",\n \"python-sdk/fastmcp-client-sampling-handlers-google_genai\",\n \"python-sdk/fastmcp-client-sampling-handlers-openai\"\n ]\n }\n ]\n },\n \"python-sdk/fastmcp-client-tasks\",\n \"python-sdk/fastmcp-client-telemetry\",\n {\n \"group\": \"transports\",\n \"pages\": [\n \"python-sdk/fastmcp-client-transports-__init__\",\n \"python-sdk/fastmcp-client-transports-base\",\n \"python-sdk/fastmcp-client-transports-config\",\n \"python-sdk/fastmcp-client-transports-http\",\n \"python-sdk/fastmcp-client-transports-inference\",\n \"python-sdk/fastmcp-client-transports-memory\",\n \"python-sdk/fastmcp-client-transports-sse\",\n \"python-sdk/fastmcp-client-transports-stdio\"\n ]\n }\n ]\n },\n {\n \"group\": \"fastmcp.experimental\",\n \"pages\": [\n \"python-sdk/fastmcp-experimental-__init__\",\n {\n \"group\": \"sampling\",\n \"pages\": [\n \"python-sdk/fastmcp-experimental-sampling-__init__\",\n \"python-sdk/fastmcp-experimental-sampling-handlers\"\n ]\n },\n {\n \"group\": \"transforms\",\n \"pages\": [\n \"python-sdk/fastmcp-experimental-transforms-__init__\",\n \"python-sdk/fastmcp-experimental-transforms-code_mode\"\n ]\n }\n ]\n },\n {\n \"group\": \"fastmcp.prompts\",\n \"pages\": [\n \"python-sdk/fastmcp-prompts-__init__\",\n \"python-sdk/fastmcp-prompts-base\",\n \"python-sdk/fastmcp-prompts-function_prompt\"\n ]\n },\n {\n \"group\": \"fastmcp.resources\",\n \"pages\": [\n \"python-sdk/fastmcp-resources-__init__\",\n \"python-sdk/fastmcp-resources-base\",\n \"python-sdk/fastmcp-resources-function_resource\",\n \"python-sdk/fastmcp-resources-template\",\n \"python-sdk/fastmcp-resources-types\"\n ]\n },\n {\n \"group\": \"fastmcp.server\",\n \"pages\": [\n \"python-sdk/fastmcp-server-__init__\",\n \"python-sdk/fastmcp-server-app\",\n \"python-sdk/fastmcp-server-apps\",\n {\n \"group\": \"auth\",\n \"pages\": [\n \"python-sdk/fastmcp-server-auth-__init__\",\n \"python-sdk/fastmcp-server-auth-auth\",\n \"python-sdk/fastmcp-server-auth-authorization\",\n \"python-sdk/fastmcp-server-auth-cimd\",\n \"python-sdk/fastmcp-server-auth-jwt_issuer\",\n \"python-sdk/fastmcp-server-auth-middleware\",\n {\n \"group\": \"oauth_proxy\",\n \"pages\": [\n \"python-sdk/fastmcp-server-auth-oauth_proxy-__init__\",\n \"python-sdk/fastmcp-server-auth-oauth_proxy-consent\",\n \"python-sdk/fastmcp-server-auth-oauth_proxy-models\",\n \"python-sdk/fastmcp-server-auth-oauth_proxy-proxy\",\n \"python-sdk/fastmcp-server-auth-oauth_proxy-ui\"\n ]\n },\n \"python-sdk/fastmcp-server-auth-oidc_proxy\",\n {\n \"group\": \"providers\",\n \"pages\": [\n \"python-sdk/fastmcp-server-auth-providers-__init__\",\n \"python-sdk/fastmcp-server-auth-providers-auth0\",\n \"python-sdk/fastmcp-server-auth-providers-aws\",\n \"python-sdk/fastmcp-server-auth-providers-azure\",\n \"python-sdk/fastmcp-server-auth-providers-debug\",\n \"python-sdk/fastmcp-server-auth-providers-descope\",\n \"python-sdk/fastmcp-server-auth-providers-discord\",\n \"python-sdk/fastmcp-server-auth-providers-github\",\n \"python-sdk/fastmcp-server-auth-providers-google\",\n \"python-sdk/fastmcp-server-auth-providers-in_memory\",\n \"python-sdk/fastmcp-server-auth-providers-introspection\",\n \"python-sdk/fastmcp-server-auth-providers-jwt\",\n \"python-sdk/fastmcp-server-auth-providers-oci\",\n \"python-sdk/fastmcp-server-auth-providers-propelauth\",\n \"python-sdk/fastmcp-server-auth-providers-scalekit\",\n \"python-sdk/fastmcp-server-auth-providers-supabase\",\n \"python-sdk/fastmcp-server-auth-providers-workos\"\n ]\n },\n \"python-sdk/fastmcp-server-auth-redirect_validation\",\n \"python-sdk/fastmcp-server-auth-ssrf\"\n ]\n },\n \"python-sdk/fastmcp-server-context\",\n \"python-sdk/fastmcp-server-dependencies\",\n \"python-sdk/fastmcp-server-elicitation\",\n \"python-sdk/fastmcp-server-event_store\",\n \"python-sdk/fastmcp-server-http\",\n \"python-sdk/fastmcp-server-lifespan\",\n \"python-sdk/fastmcp-server-low_level\",\n {\n \"group\": \"middleware\",\n \"pages\": [\n \"python-sdk/fastmcp-server-middleware-__init__\",\n \"python-sdk/fastmcp-server-middleware-authorization\",\n \"python-sdk/fastmcp-server-middleware-caching\",\n \"python-sdk/fastmcp-server-middleware-dereference\",\n \"python-sdk/fastmcp-server-middleware-error_handling\",\n \"python-sdk/fastmcp-server-middleware-logging\",\n \"python-sdk/fastmcp-server-middleware-middleware\",\n \"python-sdk/fastmcp-server-middleware-ping\",\n \"python-sdk/fastmcp-server-middleware-rate_limiting\",\n \"python-sdk/fastmcp-server-middleware-response_limiting\",\n \"python-sdk/fastmcp-server-middleware-timing\",\n \"python-sdk/fastmcp-server-middleware-tool_injection\"\n ]\n },\n {\n \"group\": \"mixins\",\n \"pages\": [\n \"python-sdk/fastmcp-server-mixins-__init__\",\n \"python-sdk/fastmcp-server-mixins-lifespan\",\n \"python-sdk/fastmcp-server-mixins-mcp_operations\",\n \"python-sdk/fastmcp-server-mixins-transport\"\n ]\n },\n {\n \"group\": \"openapi\",\n \"pages\": [\n \"python-sdk/fastmcp-server-openapi-__init__\",\n \"python-sdk/fastmcp-server-openapi-components\",\n \"python-sdk/fastmcp-server-openapi-routing\",\n \"python-sdk/fastmcp-server-openapi-server\"\n ]\n },\n {\n \"group\": \"providers\",\n \"pages\": [\n \"python-sdk/fastmcp-server-providers-__init__\",\n \"python-sdk/fastmcp-server-providers-aggregate\",\n \"python-sdk/fastmcp-server-providers-base\",\n \"python-sdk/fastmcp-server-providers-fastmcp_provider\",\n \"python-sdk/fastmcp-server-providers-filesystem\",\n \"python-sdk/fastmcp-server-providers-filesystem_discovery\",\n {\n \"group\": \"local_provider\",\n \"pages\": [\n \"python-sdk/fastmcp-server-providers-local_provider-__init__\",\n {\n \"group\": \"decorators\",\n \"pages\": [\n \"python-sdk/fastmcp-server-providers-local_provider-decorators-__init__\",\n \"python-sdk/fastmcp-server-providers-local_provider-decorators-prompts\",\n \"python-sdk/fastmcp-server-providers-local_provider-decorators-resources\",\n \"python-sdk/fastmcp-server-providers-local_provider-decorators-tools\"\n ]\n },\n \"python-sdk/fastmcp-server-providers-local_provider-local_provider\"\n ]\n },\n {\n \"group\": \"openapi\",\n \"pages\": [\n \"python-sdk/fastmcp-server-providers-openapi-__init__\",\n \"python-sdk/fastmcp-server-providers-openapi-components\",\n \"python-sdk/fastmcp-server-providers-openapi-provider\",\n \"python-sdk/fastmcp-server-providers-openapi-routing\"\n ]\n },\n \"python-sdk/fastmcp-server-providers-proxy\",\n {\n \"group\": \"skills\",\n \"pages\": [\n \"python-sdk/fastmcp-server-providers-skills-__init__\",\n \"python-sdk/fastmcp-server-providers-skills-claude_provider\",\n \"python-sdk/fastmcp-server-providers-skills-directory_provider\",\n \"python-sdk/fastmcp-server-providers-skills-skill_provider\",\n \"python-sdk/fastmcp-server-providers-skills-vendor_providers\"\n ]\n },\n \"python-sdk/fastmcp-server-providers-wrapped_provider\"\n ]\n },\n \"python-sdk/fastmcp-server-proxy\",\n {\n \"group\": \"sampling\",\n \"pages\": [\n \"python-sdk/fastmcp-server-sampling-__init__\",\n \"python-sdk/fastmcp-server-sampling-run\",\n \"python-sdk/fastmcp-server-sampling-sampling_tool\"\n ]\n },\n \"python-sdk/fastmcp-server-server\",\n {\n \"group\": \"tasks\",\n \"pages\": [\n \"python-sdk/fastmcp-server-tasks-__init__\",\n \"python-sdk/fastmcp-server-tasks-capabilities\",\n \"python-sdk/fastmcp-server-tasks-config\",\n \"python-sdk/fastmcp-server-tasks-elicitation\",\n \"python-sdk/fastmcp-server-tasks-handlers\",\n \"python-sdk/fastmcp-server-tasks-keys\",\n \"python-sdk/fastmcp-server-tasks-notifications\",\n \"python-sdk/fastmcp-server-tasks-requests\",\n \"python-sdk/fastmcp-server-tasks-routing\",\n \"python-sdk/fastmcp-server-tasks-subscriptions\"\n ]\n },\n \"python-sdk/fastmcp-server-telemetry\",\n {\n \"group\": \"transforms\",\n \"pages\": [\n \"python-sdk/fastmcp-server-transforms-__init__\",\n \"python-sdk/fastmcp-server-transforms-catalog\",\n \"python-sdk/fastmcp-server-transforms-namespace\",\n \"python-sdk/fastmcp-server-transforms-prompts_as_tools\",\n \"python-sdk/fastmcp-server-transforms-resources_as_tools\",\n {\n \"group\": \"search\",\n \"pages\": [\n \"python-sdk/fastmcp-server-transforms-search-__init__\",\n \"python-sdk/fastmcp-server-transforms-search-base\",\n \"python-sdk/fastmcp-server-transforms-search-bm25\",\n \"python-sdk/fastmcp-server-transforms-search-regex\"\n ]\n },\n \"python-sdk/fastmcp-server-transforms-tool_transform\",\n \"python-sdk/fastmcp-server-transforms-version_filter\",\n \"python-sdk/fastmcp-server-transforms-visibility\"\n ]\n }\n ]\n },\n {\n \"group\": \"fastmcp.tools\",\n \"pages\": [\n \"python-sdk/fastmcp-tools-__init__\",\n \"python-sdk/fastmcp-tools-base\",\n \"python-sdk/fastmcp-tools-function_parsing\",\n \"python-sdk/fastmcp-tools-function_tool\",\n \"python-sdk/fastmcp-tools-tool_transform\"\n ]\n },\n {\n \"group\": \"fastmcp.utilities\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-__init__\",\n \"python-sdk/fastmcp-utilities-async_utils\",\n \"python-sdk/fastmcp-utilities-auth\",\n \"python-sdk/fastmcp-utilities-cli\",\n \"python-sdk/fastmcp-utilities-components\",\n \"python-sdk/fastmcp-utilities-exceptions\",\n \"python-sdk/fastmcp-utilities-http\",\n \"python-sdk/fastmcp-utilities-inspect\",\n \"python-sdk/fastmcp-utilities-json_schema\",\n \"python-sdk/fastmcp-utilities-json_schema_type\",\n \"python-sdk/fastmcp-utilities-lifespan\",\n \"python-sdk/fastmcp-utilities-logging\",\n {\n \"group\": \"mcp_server_config\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-mcp_server_config-__init__\",\n {\n \"group\": \"v1\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-__init__\",\n {\n \"group\": \"environments\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-__init__\",\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base\",\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv\"\n ]\n },\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config\",\n {\n \"group\": \"sources\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-__init__\",\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base\",\n \"python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem\"\n ]\n }\n ]\n }\n ]\n },\n {\n \"group\": \"openapi\",\n \"pages\": [\n \"python-sdk/fastmcp-utilities-openapi-__init__\",\n \"python-sdk/fastmcp-utilities-openapi-director\",\n \"python-sdk/fastmcp-utilities-openapi-formatters\",\n \"python-sdk/fastmcp-utilities-openapi-json_schema_converter\",\n \"python-sdk/fastmcp-utilities-openapi-models\",\n \"python-sdk/fastmcp-utilities-openapi-parser\",\n \"python-sdk/fastmcp-utilities-openapi-schemas\"\n ]\n },\n \"python-sdk/fastmcp-utilities-pagination\",\n \"python-sdk/fastmcp-utilities-skills\",\n \"python-sdk/fastmcp-utilities-tests\",\n \"python-sdk/fastmcp-utilities-timeout\",\n \"python-sdk/fastmcp-utilities-token_cache\",\n \"python-sdk/fastmcp-utilities-types\",\n \"python-sdk/fastmcp-utilities-ui\",\n \"python-sdk/fastmcp-utilities-version_check\",\n \"python-sdk/fastmcp-utilities-versions\"\n ]\n }\n ]\n }\n ],\n \"dropdown\": \"SDK Reference\",\n \"icon\": \"code\"\n }\n ],\n \"version\": \"v3\"\n },\n {\n \"dropdowns\": [\n {\n \"dropdown\": \"Documentation\",\n \"groups\": [\n {\n \"group\": \"Get Started\",\n \"pages\": [\n \"v2/getting-started/welcome\",\n \"v2/getting-started/installation\",\n \"v2/getting-started/quickstart\",\n \"v2/updates\"\n ]\n },\n {\n \"group\": \"Servers\",\n \"pages\": [\n \"v2/servers/server\",\n {\n \"group\": \"Core Components\",\n \"icon\": \"toolbox\",\n \"pages\": [\n \"v2/servers/tools\",\n \"v2/servers/resources\",\n \"v2/servers/prompts\"\n ]\n },\n {\n \"group\": \"Advanced Features\",\n \"icon\": \"stars\",\n \"pages\": [\n \"v2/servers/composition\",\n \"v2/servers/context\",\n \"v2/servers/elicitation\",\n \"v2/servers/icons\",\n \"v2/servers/logging\",\n \"v2/servers/middleware\",\n \"v2/servers/progress\",\n \"v2/servers/proxy\",\n \"v2/servers/sampling\",\n \"v2/servers/storage-backends\",\n \"v2/servers/tasks\"\n ]\n },\n {\n \"group\": \"Authentication\",\n \"icon\": \"shield-check\",\n \"pages\": [\n \"v2/servers/auth/authentication\",\n \"v2/servers/auth/token-verification\",\n \"v2/servers/auth/remote-oauth\",\n \"v2/servers/auth/oauth-proxy\",\n \"v2/servers/auth/oidc-proxy\",\n \"v2/servers/auth/full-oauth-server\"\n ]\n },\n {\n \"group\": \"Deployment\",\n \"icon\": \"rocket\",\n \"pages\": [\n \"v2/deployment/running-server\",\n \"v2/deployment/http\",\n \"deployment/prefect-horizon\",\n \"v2/deployment/server-configuration\"\n ]\n }\n ]\n },\n {\n \"group\": \"Clients\",\n \"pages\": [\n {\n \"group\": \"Essentials\",\n \"icon\": \"cube\",\n \"pages\": [\n \"v2/clients/client\",\n \"v2/clients/transports\"\n ]\n },\n {\n \"group\": \"Core Operations\",\n \"icon\": \"handshake\",\n \"pages\": [\n \"v2/clients/tools\",\n \"v2/clients/resources\",\n \"v2/clients/prompts\"\n ]\n },\n {\n \"group\": \"Advanced Features\",\n \"icon\": \"stars\",\n \"pages\": [\n \"v2/clients/elicitation\",\n \"v2/clients/logging\",\n \"v2/clients/progress\",\n \"v2/clients/sampling\",\n \"v2/clients/tasks\",\n \"v2/clients/messages\",\n \"v2/clients/roots\"\n ]\n },\n {\n \"group\": \"Authentication\",\n \"icon\": \"user-shield\",\n \"pages\": [\n \"v2/clients/auth/oauth\",\n \"v2/clients/auth/bearer\"\n ]\n }\n ]\n },\n {\n \"group\": \"Integrations\",\n \"pages\": [\n {\n \"group\": \"Authentication\",\n \"icon\": \"key\",\n \"pages\": [\n \"v2/integrations/auth0\",\n \"v2/integrations/authkit\",\n \"v2/integrations/aws-cognito\",\n \"v2/integrations/azure\",\n \"v2/integrations/descope\",\n \"v2/integrations/discord\",\n \"v2/integrations/github\",\n \"v2/integrations/google\",\n \"v2/integrations/oci\",\n \"v2/integrations/scalekit\",\n \"v2/integrations/supabase\",\n \"v2/integrations/workos\"\n ]\n },\n {\n \"group\": \"Authorization\",\n \"icon\": \"shield-check\",\n \"pages\": [\n \"v2/integrations/eunomia-authorization\",\n \"v2/integrations/permit\"\n ]\n },\n {\n \"group\": \"AI Assistants\",\n \"icon\": \"robot\",\n \"pages\": [\n \"v2/integrations/chatgpt\",\n \"v2/integrations/claude-code\",\n \"v2/integrations/claude-desktop\",\n \"v2/integrations/cursor\",\n \"v2/integrations/gemini-cli\",\n \"v2/integrations/mcp-json-configuration\"\n ]\n },\n {\n \"group\": \"AI SDKs\",\n \"icon\": \"code\",\n \"pages\": [\n \"v2/integrations/anthropic\",\n \"v2/integrations/gemini\",\n \"v2/integrations/openai\"\n ]\n },\n {\n \"group\": \"API Integration\",\n \"icon\": \"globe\",\n \"pages\": [\n \"v2/integrations/fastapi\",\n \"v2/integrations/openapi\"\n ]\n }\n ]\n },\n {\n \"group\": \"Patterns\",\n \"pages\": [\n \"v2/patterns/tool-transformation\",\n \"v2/patterns/decorating-methods\",\n \"v2/patterns/cli\",\n \"v2/patterns/contrib\",\n \"v2/patterns/testing\"\n ]\n },\n {\n \"group\": \"Development\",\n \"pages\": [\n \"v2/development/contributing\",\n \"v2/development/tests\",\n \"v2/development/releases\",\n \"v2/development/upgrade-guide\",\n \"v2/changelog\"\n ]\n }\n ],\n \"icon\": \"book\"\n }\n ],\n \"version\": \"v2.14.5\"\n }\n ]\n },\n \"redirects\": [\n {\n \"destination\": \"/cli/overview\",\n \"source\": \"/patterns/cli\"\n },\n {\n \"destination\": \"/servers/testing\",\n \"source\": \"/patterns/testing\"\n },\n {\n \"destination\": \"/cli/client\",\n \"source\": \"/clients/cli\"\n },\n {\n \"destination\": \"/cli/generate-cli\",\n \"source\": \"/clients/generate-cli\"\n },\n {\n \"destination\": \"/deployment/prefect-horizon\",\n \"source\": \"/deployment/fastmcp-cloud\"\n },\n {\n \"destination\": \"/deployment/prefect-horizon\",\n \"source\": \"/v2/deployment/fastmcp-cloud\"\n },\n {\n \"destination\": \"/v2/clients/messages\",\n \"source\": \"/clients/messages\"\n },\n {\n \"destination\": \"/v2/patterns/decorating-methods\",\n \"source\": \"/patterns/decorating-methods\"\n },\n {\n \"destination\": \"/servers/providers/proxy\",\n \"source\": \"/patterns/proxy\"\n },\n {\n \"destination\": \"/servers/composition\",\n \"source\": \"/patterns/composition\"\n },\n {\n \"destination\": \"/servers/providers/proxy\",\n \"source\": \"/servers/proxy\"\n },\n {\n \"destination\": \"/servers/composition\",\n \"source\": \"/servers/providers/mounting\"\n },\n {\n \"destination\": \"/servers/transforms/transforms\",\n \"source\": \"/servers/providers/namespacing\"\n },\n {\n \"destination\": \"/servers/transforms/transforms\",\n \"source\": \"/patterns/tool-transformation\"\n },\n {\n \"destination\": \"/getting-started/upgrading/from-fastmcp-2\",\n \"source\": \"/development/upgrade-guide\"\n },\n {\n \"destination\": \"/getting-started/upgrading/from-mcp-sdk\",\n \"source\": \"/getting-started/upgrading-from-sdk\"\n },\n {\n \"destination\": \"/getting-started/upgrading/from-low-level-sdk\",\n \"source\": \"/getting-started/low-level-sdk\"\n }\n ],\n \"search\": {\n \"prompt\": \"Search the docs...\"\n },\n \"styling\": {\n \"codeblocks\": {\n \"theme\": {\n \"dark\": \"dark-plus\",\n \"light\": \"snazzy-light\"\n }\n }\n },\n \"theme\": \"almond\",\n \"thumbnails\": {\n \"appearance\": \"light\",\n \"background\": \"/assets/brand/thumbnail-background-4.jpeg\"\n }\n}" }, { "path": "docs/getting-started/installation.mdx", "content": "---\ntitle: Installation\ndescription: Install FastMCP and verify your setup\nicon: arrow-down-to-line\n---\n## Install FastMCP\n\nWe recommend using [uv](https://docs.astral.sh/uv/getting-started/installation/) to install and manage FastMCP.\n\n```bash\npip install fastmcp\n```\n\nOr with uv:\n\n```bash\nuv add fastmcp\n```\n\n### Optional Dependencies\n\nFastMCP provides optional extras for specific features. For example, to install the background tasks extra:\n\n```bash\npip install \"fastmcp[tasks]\"\n```\n\nSee [Background Tasks](/servers/tasks) for details on the task system.\n\n### Verify Installation\n\nTo verify that FastMCP is installed correctly, you can run the following command:\n\n```bash\nfastmcp version\n```\n\nYou should see output like the following:\n\n```bash\n$ fastmcp version\n\nFastMCP version: 3.0.0\nMCP version: 1.25.0\nPython version: 3.12.2\nPlatform: macOS-15.3.1-arm64-arm-64bit\nFastMCP root path: ~/Developer/fastmcp\n```\n\n### Dependency Licensing\n\n\nFastMCP 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.\n\nIf this is a concern, you can install Cyclopts v5 alpha which removes this dependency:\n\n```bash\npip install \"cyclopts>=5.0.0a1\"\n```\n\nAlternatively, wait for the stable v5 release. See [this issue](https://github.com/BrianPugh/cyclopts/issues/672) for details.\n\n## Upgrading\n\n### From FastMCP 2.0\n\nSee the [Upgrade Guide](/getting-started/upgrading/from-fastmcp-2) for a complete list of breaking changes and migration steps.\n\n### From the MCP SDK\n\n#### From FastMCP 1.0\n\nIf 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.\n\n#### From the Low-Level Server API\n\nIf 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.\n\n## Versioning Policy\n\nFastMCP 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.\n\nFor production use, always pin to exact versions:\n```\nfastmcp==3.0.0 # Good\nfastmcp>=3.0.0 # Bad - may install breaking changes\n```\n\nSee the full [versioning and release policy](/development/releases#versioning-policy) for details on our public API, deprecation practices, and breaking change philosophy.\n\n## Contributing to FastMCP\n\nInterested in contributing to FastMCP? See the [Contributing Guide](/development/contributing) for details on:\n- Setting up your development environment\n- Running tests and pre-commit hooks\n- Submitting issues and pull requests\n- Code standards and review process\n" }, { "path": "docs/getting-started/quickstart.mdx", "content": "---\ntitle: Quickstart\nicon: rocket-launch\n---\n\nWelcome! This guide will help you quickly set up FastMCP, run your first MCP server, and deploy a server to Prefect Horizon.\n\nIf you haven't already installed FastMCP, follow the [installation instructions](/getting-started/installation).\n\n## Create a FastMCP Server\n\nA FastMCP server is a collection of tools, resources, and other MCP components. To create a server, start by instantiating the `FastMCP` class. \n\nCreate a new file called `my_server.py` and add the following code:\n\n```python my_server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My MCP Server\")\n```\n\n\nThat's it! You've created a FastMCP server, albeit a very boring one. Let's add a tool to make it more interesting.\n\n\n## Add a Tool\n\nTo add a tool that returns a simple greeting, write a function and decorate it with `@mcp.tool` to register it with the server:\n\n```python my_server.py {5-7}\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My MCP Server\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n```\n\n\n## Run the Server\n\nThe 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:\n\n\n\n```python my_server.py (stdio) {9, 10}\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My MCP Server\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n```python my_server.py (HTTP) {9, 10}\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"My MCP Server\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\", port=8000)\n```\n\n\n\nThis 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.\n\n\nWhy do we need the `if __name__ == \"__main__\":` block?\n\nThe `__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.\n\n\n### Using the FastMCP CLI\n\nYou 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.\n\nFor example, to run this server with the default stdio transport (no matter how you called `mcp.run()`), you can use the following command:\n```bash\nfastmcp run my_server.py:mcp\n```\n\nTo run this server with the HTTP transport, you can use the following command:\n```bash\nfastmcp run my_server.py:mcp --transport http --port 8000\n```\n\n## Call Your Server\n\nOnce 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:\n\n```python my_client.py\nimport asyncio\nfrom fastmcp import Client\n\nclient = Client(\"http://localhost:8000/mcp\")\n\nasync def call_tool(name: str):\n async with client:\n result = await client.call_tool(\"greet\", {\"name\": name})\n print(result)\n\nasyncio.run(call_tool(\"Ford\"))\n```\n\nNote that:\n- FastMCP clients are asynchronous, so we need to use `asyncio.run` to run the client\n- We must enter a client context (`async with client:`) before using the client\n- You can make multiple client calls within the same context\n\n## Deploy to Prefect Horizon\n\n[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.\n\n\nHorizon is **free for personal projects** and offers enterprise governance for teams.\n\n\nTo deploy your server, you'll need a [GitHub account](https://github.com). Once you have one, you can deploy your server in three steps:\n\n1. Push your `my_server.py` file to a GitHub repository\n2. Sign in to [Prefect Horizon](https://horizon.prefect.io) with your GitHub account\n3. Create a new project from your repository and enter `my_server.py:mcp` as the server entrypoint\n\nThat'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.\n\nFor more details, see the [Prefect Horizon guide](/deployment/prefect-horizon).\n" }, { "path": "docs/getting-started/upgrading/from-fastmcp-2.mdx", "content": "---\ntitle: Upgrading from FastMCP 2\nsidebarTitle: \"From FastMCP 2\"\ndescription: Migration instructions for upgrading between FastMCP versions\nicon: up\n---\n\nThis guide covers breaking changes and migration steps when upgrading FastMCP.\n\n## v3.0.0\n\nFor 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.\n\n### Install\n\nSince you already have `fastmcp` installed, you need to explicitly request the new version — `pip install fastmcp` won't upgrade an existing installation:\n\n```bash\npip install --upgrade fastmcp\n# or\nuv add --upgrade fastmcp\n```\n\nIf you pin versions in a requirements file or `pyproject.toml`, update your pin to `fastmcp>=3.0.0,<4`.\n\n\n**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:\n\n```bash\ngit remote set-url origin https://github.com/PrefectHQ/fastmcp.git\n```\n\nIf you reference the repository URL in dependency specifications (e.g., `git+https://github.com/jlowin/fastmcp.git`), update those to the new location.\n\n\n\nYou 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.\n\nBREAKING CHANGES (will crash at import or runtime):\n\n1. CONSTRUCTOR KWARGS REMOVED: FastMCP() no longer accepts these kwargs (raises TypeError):\n - Transport settings: host, port, log_level, debug, sse_path, streamable_http_path, json_response, stateless_http\n Fix: pass to run() or run_http_async() instead, e.g. mcp.run(transport=\"http\", host=\"0.0.0.0\", port=8080)\n - message_path: set via environment variable FASTMCP_MESSAGE_PATH only (not a run() kwarg)\n - Duplicate handling: on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts\n Fix: use unified on_duplicate= parameter\n - Tool settings: tool_serializer, include_tags, exclude_tags, tool_transformations\n Fix: use ToolResult returns, server.enable()/disable(), server.add_transform()\n\n2. COMPONENT METHODS REMOVED:\n - tool.enable()/disable() raises NotImplementedError\n Fix: server.disable(names={\"tool_name\"}, components={\"tool\"}) or server.disable(tags={\"tag\"})\n - get_tools()/get_resources()/get_prompts()/get_resource_templates() removed\n Fix: use list_tools()/list_resources()/list_prompts()/list_resource_templates() — these return lists, not dicts\n\n3. ASYNC STATE: ctx.set_state() and ctx.get_state() are now async (must be awaited).\n State values must be JSON-serializable unless serializable=False is passed.\n Each FastMCP instance has its own state store, so serializable state set by parent middleware isn't visible to mounted tools by default.\n Fix: pass the same session_state_store to both servers, or use serializable=False (request-scoped state is always shared).\n\n4. PROMPTS: mcp.types.PromptMessage replaced by fastmcp.prompts.Message.\n Before: PromptMessage(role=\"user\", content=TextContent(type=\"text\", text=\"Hello\"))\n After: Message(\"Hello\") # role defaults to \"user\", accepts plain strings\n Also: if prompts return raw dicts like `{\"role\": \"user\", \"content\": \"...\"}`, these must become Message objects.\n v2 silently coerced dicts; v3 requires typed Message objects or plain strings.\n\n5. AUTH PROVIDERS: No longer auto-load from env vars. Pass client_id, client_secret explicitly via os.environ.\n\n6. WSTRANSPORT: Removed. Use StreamableHttpTransport.\n\n7. OPENAPI: timeout parameter removed from OpenAPIProvider. Set timeout on the httpx.AsyncClient instead.\n\n8. METADATA: Namespace changed from \"_fastmcp\" to \"fastmcp\" in tool.meta. The include_fastmcp_meta parameter is removed (always included).\n\n9. ENV VAR: FASTMCP_SHOW_CLI_BANNER renamed to FASTMCP_SHOW_SERVER_BANNER.\n\n10. 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.\n Fix: set FASTMCP_DECORATOR_MODE=object for v2 compat (itself deprecated).\n\n11. 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]'.\n\n12. REPO MOVE: GitHub repository moved from jlowin/fastmcp to PrefectHQ/fastmcp. Update git remotes and dependency URLs that reference the old location.\n\n13. 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]\".\n\nDEPRECATIONS (still work but emit warnings):\n\n- mount(prefix=\"x\") -> mount(namespace=\"x\")\n- import_server(sub) -> mount(sub)\n- FastMCP.as_proxy(url) -> from fastmcp.server import create_proxy; create_proxy(url)\n- from fastmcp.server.proxy -> from fastmcp.server.providers.proxy\n- from fastmcp.server.openapi import FastMCPOpenAPI -> from fastmcp.server.providers.openapi import OpenAPIProvider; use FastMCP(\"name\", providers=[OpenAPIProvider(...)])\n- mcp.add_tool_transformation(name, cfg) -> from fastmcp.server.transforms import ToolTransform; mcp.add_transform(ToolTransform(...))\n\nFor each issue found, show the original line, explain why it breaks, and provide the corrected code.\n\n\n### Breaking Changes\n\n**Transport and server settings removed from constructor**\n\nIn 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.\n\n```python\n# Before\nmcp = FastMCP(\"server\", host=\"0.0.0.0\", port=8080)\nmcp.run()\n\n# After\nmcp = FastMCP(\"server\")\nmcp.run(transport=\"http\", host=\"0.0.0.0\", port=8080)\n```\n\nThe full list of removed kwargs and their replacements:\n\n- `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`)\n- `message_path` — set via environment variable `FASTMCP_MESSAGE_PATH` only (not a `run()` kwarg)\n- `on_duplicate_tools`, `on_duplicate_resources`, `on_duplicate_prompts` — consolidated into a single `on_duplicate=` parameter\n- `tool_serializer` — return [`ToolResult`](/servers/tools#custom-serialization) from your tools instead\n- `include_tags` / `exclude_tags` — use `server.enable(tags=..., only=True)` / `server.disable(tags=...)` after construction\n- `tool_transformations` — use `server.add_transform(ToolTransform(...))` after construction\n\n**OAuth storage backend changed (diskcache CVE)**\n\nThe 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)).\n\nIf 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.\n\nIf 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:\n\n\nKeeping `DiskStore` requires `pip install 'py-key-value-aio[disk]'`, which re-introduces the vulnerable `diskcache` package into your dependency tree.\n\n\n**Component enable()/disable() moved to server**\n\nIn 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:\n\n```python\n# Before\ntool = await server.get_tool(\"my_tool\")\ntool.disable()\n\n# After\nserver.disable(names={\"my_tool\"}, components={\"tool\"})\n```\n\nCalling `.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.\n\n**Listing methods renamed and return lists**\n\nThe `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:\n\n```python\n# Before\ntools = await server.get_tools()\ntool = tools[\"my_tool\"]\n\n# After\ntools = await server.list_tools()\ntool = next((t for t in tools if t.name == \"my_tool\"), None)\n```\n\n**Prompts use Message class**\n\nPrompt 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:\n\n```python\n# Before\nfrom mcp.types import PromptMessage, TextContent\n\n@mcp.prompt\ndef my_prompt() -> PromptMessage:\n return PromptMessage(role=\"user\", content=TextContent(type=\"text\", text=\"Hello\"))\n\n# After\nfrom fastmcp.prompts import Message\n\n@mcp.prompt\ndef my_prompt() -> Message:\n return Message(\"Hello\")\n```\n\nIf 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):\n\n```python\n# Before (v2 accepted this)\n@mcp.prompt\ndef my_prompt():\n return [\n {\"role\": \"user\", \"content\": \"Hello\"},\n {\"role\": \"assistant\", \"content\": \"How can I help?\"},\n ]\n\n# After\nfrom fastmcp.prompts import Message\n\n@mcp.prompt\ndef my_prompt() -> list[Message]:\n return [\n Message(\"Hello\"),\n Message(\"How can I help?\", role=\"assistant\"),\n ]\n```\n\n**Context state methods are async**\n\n`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:\n\n```python\n# Before\nctx.set_state(\"key\", \"value\")\nvalue = ctx.get_state(\"key\")\n\n# After\nawait ctx.set_state(\"key\", \"value\")\nvalue = await ctx.get_state(\"key\")\n```\n\nState 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:\n\n```python\nawait ctx.set_state(\"client\", my_http_client, serializable=False)\n```\n\n**Mounted servers have isolated state stores**\n\nEach `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:\n\n```python\nfrom fastmcp import FastMCP\nfrom key_value.aio.stores.memory import MemoryStore\n\nstore = MemoryStore()\nparent = FastMCP(\"Parent\", session_state_store=store)\nchild = FastMCP(\"Child\", session_state_store=store)\nparent.mount(child, namespace=\"child\")\n```\n\n**Auth provider environment variables removed**\n\nIn 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:\n\n```python\n# Before (v2) — client_id and client_secret loaded automatically\n# from FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID, etc.\nauth = GitHubProvider()\n\n# After (v3) — pass values explicitly\nimport os\nfrom fastmcp.server.auth.providers.github import GitHubProvider\n\nauth = GitHubProvider(\n client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n)\n```\n\n**WSTransport removed**\n\nThe deprecated WebSocket client transport has been removed. Use `StreamableHttpTransport` instead:\n\n```python\n# Before\nfrom fastmcp.client.transports import WSTransport\ntransport = WSTransport(\"ws://localhost:8000/ws\")\n\n# After\nfrom fastmcp.client.transports import StreamableHttpTransport\ntransport = StreamableHttpTransport(\"http://localhost:8000/mcp\")\n```\n\n**OpenAPI `timeout` parameter removed**\n\n`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:\n\n```python\n# Before\nprovider = OpenAPIProvider(spec, client, timeout=60)\n\n# After\nclient = httpx.AsyncClient(base_url=\"https://api.example.com\", timeout=60)\nprovider = OpenAPIProvider(spec, client)\n```\n\n**Metadata namespace renamed**\n\nThe FastMCP metadata key in component `meta` dicts changed from `_fastmcp` to `fastmcp`. If you read metadata from tool or resource objects, update the key:\n\n```python\n# Before\ntags = tool.meta.get(\"_fastmcp\", {}).get(\"tags\", [])\n\n# After\ntags = tool.meta.get(\"fastmcp\", {}).get(\"tags\", [])\n```\n\nMetadata 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.\n\n**Server banner environment variable renamed**\n\n`FASTMCP_SHOW_CLI_BANNER` is now `FASTMCP_SHOW_SERVER_BANNER`.\n\n**Decorators return functions**\n\nIn 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:\n\n```python\n@mcp.tool\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\ngreet(\"World\") # Works! Returns \"Hello, World!\"\n```\n\nIf 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.\n\n**Background tasks require optional dependency**\n\nFastMCP's background task system (SEP-1686) is now behind an optional extra. If your server uses background tasks, install with:\n\n```bash\npip install \"fastmcp[tasks]\"\n```\n\nWithout the extra, configuring a tool with `task=True` or `TaskConfig` will raise an import error at runtime. See [Background Tasks](/servers/tasks) for details.\n\n### Deprecated Features\n\nThese still work but emit warnings. Update when convenient.\n\n**mount() prefix → namespace**\n\n```python\n# Deprecated\nmain.mount(subserver, prefix=\"api\")\n\n# New\nmain.mount(subserver, namespace=\"api\")\n```\n\n**import_server() → mount()**\n\n```python\n# Deprecated\nmain.import_server(subserver)\n\n# New\nmain.mount(subserver)\n```\n\n**Module import paths for proxy and OpenAPI**\n\nThe proxy and OpenAPI modules have moved under `providers` to reflect v3's provider-based architecture:\n\n```python\n# Deprecated\nfrom fastmcp.server.proxy import FastMCPProxy\nfrom fastmcp.server.openapi import FastMCPOpenAPI\n\n# New\nfrom fastmcp.server.providers.proxy import FastMCPProxy\nfrom fastmcp.server.providers.openapi import OpenAPIProvider\n```\n\n`FastMCPOpenAPI` itself is deprecated — use `FastMCP` with an `OpenAPIProvider` instead:\n\n```python\n# Deprecated\nfrom fastmcp.server.openapi import FastMCPOpenAPI\nserver = FastMCPOpenAPI(spec, client)\n\n# New\nfrom fastmcp import FastMCP\nfrom fastmcp.server.providers.openapi import OpenAPIProvider\nserver = FastMCP(\"my_api\", providers=[OpenAPIProvider(spec, client)])\n```\n\n**add_tool_transformation() → add_transform()**\n\n```python\n# Deprecated\nmcp.add_tool_transformation(\"name\", config)\n\n# New\nfrom fastmcp.server.transforms import ToolTransform\nmcp.add_transform(ToolTransform({\"name\": config}))\n```\n\n**FastMCP.as_proxy() → create_proxy()**\n\n```python\n# Deprecated\nproxy = FastMCP.as_proxy(\"http://example.com/mcp\")\n\n# New\nfrom fastmcp.server import create_proxy\nproxy = create_proxy(\"http://example.com/mcp\")\n```\n\n## v2.14.0\n\n### OpenAPI Parser Promotion\n\nThe experimental OpenAPI parser is now standard. Update imports:\n\n```python\n# Before\nfrom fastmcp.experimental.server.openapi import FastMCPOpenAPI\n\n# After\nfrom fastmcp.server.openapi import FastMCPOpenAPI\n```\n\n### Removed Deprecated Features\n\n- `BearerAuthProvider` → use `JWTVerifier`\n- `Context.get_http_request()` → use `get_http_request()` from dependencies\n- `from fastmcp import Image` → use `from fastmcp.utilities.types import Image`\n- `FastMCP(dependencies=[...])` → use `fastmcp.json` configuration\n- `FastMCPProxy(client=...)` → use `client_factory=lambda: ...`\n- `output_schema=False` → use `output_schema=None`\n\n## v2.13.0\n\n### OAuth Token Key Management\n\nThe OAuth proxy now issues its own JWT tokens. For production, provide explicit keys:\n\n```python\nauth = GitHubProvider(\n client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n base_url=\"https://your-server.com\",\n jwt_signing_key=os.environ[\"JWT_SIGNING_KEY\"],\n client_storage=RedisStore(host=\"redis.example.com\"),\n)\n```\n\nSee [OAuth Token Security](/deployment/http#oauth-token-security) for details.\n" }, { "path": "docs/getting-started/upgrading/from-low-level-sdk.mdx", "content": "---\ntitle: Upgrading from the MCP Low-Level SDK\nsidebarTitle: \"From MCP Low-Level SDK\"\ndescription: Upgrade your MCP server from the low-level Python SDK's Server class to FastMCP\nicon: up\n---\n\nIf 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.\n\nThe 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.\n\n\nThis guide covers upgrading from **v1** of the `mcp` package. We'll provide a separate guide when v2 ships.\n\n\n\nAlready 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.\n\n\n\nYou 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.\n\nUPGRADE RULES:\n\n1. IMPORTS: Replace all `mcp.*` imports with FastMCP equivalents.\n - `from mcp.server import Server` or `from mcp.server.lowlevel.server import Server` → `from fastmcp import FastMCP`\n - `import mcp.types as types` → remove (not needed for most code)\n - `from mcp.server.stdio import stdio_server` → remove (handled by mcp.run())\n - `from mcp.server.sse import SseServerTransport` → remove (handled by mcp.run())\n\n2. SERVER: Replace `Server(\"name\")` with `FastMCP(\"name\")`.\n\n3. TOOLS: Replace the list_tools + call_tool handler pair with individual @mcp.tool decorators.\n - Delete the `@server.list_tools()` handler entirely\n - Delete the `@server.call_tool()` handler entirely\n - For each tool that was listed in list_tools and dispatched in call_tool, create a new function:\n - Decorate it with `@mcp.tool`\n - Use the tool name as the function name (or pass name= to the decorator)\n - Use the docstring for the description (or pass description= to the decorator)\n - Convert the inputSchema JSON Schema into typed Python parameters (e.g., `{\"type\": \"integer\"}` → `int`, `{\"type\": \"string\"}` → `str`, `{\"type\": \"array\", \"items\": {\"type\": \"string\"}}` → `list[str]`)\n - Return plain Python values (`str`, `int`, `dict`, etc.) instead of `list[types.TextContent(...)]`\n - If the tool returned `types.ImageContent` or `types.EmbeddedResource`, use `from fastmcp.utilities.types import Image` or return the appropriate type\n\n4. RESOURCES: Replace the list_resources + list_resource_templates + read_resource handler trio with individual @mcp.resource decorators.\n - Delete all three handlers\n - For each static resource, create a function decorated with `@mcp.resource(\"uri://...\")`\n - For each resource template, use `@mcp.resource(\"uri://{param}/path\")` with `{param}` in the URI and a matching function parameter\n - Return str for text content, bytes for binary content\n - Set `mime_type=` in the decorator if needed\n\n5. PROMPTS: Replace the list_prompts + get_prompt handler pair with individual @mcp.prompt decorators.\n - Delete both handlers\n - For each prompt, create a function decorated with `@mcp.prompt`\n - Convert PromptArgument definitions into typed function parameters\n - Return str for simple single-message prompts (auto-wrapped as user message)\n - Return `list[Message]` for multi-message prompts: `from fastmcp.prompts import Message`\n - `Message(\"text\")` defaults to `role=\"user\"`; use `Message(\"text\", role=\"assistant\")` for assistant messages\n\n6. TRANSPORT: Replace all transport boilerplate with mcp.run().\n - `async with stdio_server() as (r, w): await server.run(r, w, ...)` → `mcp.run()` (`stdio` is the default)\n - SSE/Starlette setup → `mcp.run(transport=\"sse\", host=\"...\", port=...)`\n - Streamable HTTP setup → `mcp.run(transport=\"http\", host=\"...\", port=...)`\n - Delete asyncio.run(main()) boilerplate — use `if __name__ == \"__main__\": mcp.run()`\n\n7. CONTEXT: Replace `server.request_context` with FastMCP's Context parameter.\n - Add `from fastmcp import Context` and add a `ctx: Context` parameter to any tool that needs it\n - `server.request_context.session.send_log_message(...)` → `await ctx.info(\"message\")` or `await ctx.warning(\"message\")`\n - Progress reporting → `await ctx.report_progress(current, total)`\n\nFor each change, show the original code, explain what it did, and provide the FastMCP equivalent.\n\n\n## Install\n\n```bash\npip install --upgrade fastmcp\n# or\nuv add fastmcp\n```\n\nFastMCP includes the `mcp` package as a transitive dependency, so you don't lose access to anything.\n\n## Server and Transport\n\nThe `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.\n\n\n\n```python Before\nimport asyncio\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\n\nserver = Server(\"my-server\")\n\n# ... register handlers ...\n\nasync def main():\n async with stdio_server() as (read_stream, write_stream):\n await server.run(\n read_stream,\n write_stream,\n server.create_initialization_options(),\n )\n\nasyncio.run(main())\n```\n\n```python After\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n# ... register tools, resources, prompts ...\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n\n\nNeed HTTP instead of stdio? With the `Server` class, you'd wire up Starlette routes and `SseServerTransport` or `StreamableHTTPSessionManager`. With FastMCP:\n\n```python\nmcp.run(transport=\"http\", host=\"0.0.0.0\", port=8000)\n```\n\n## Tools\n\nThis 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.\n\n\n\n```python Before\nimport mcp.types as types\nfrom mcp.server import Server\n\nserver = Server(\"math\")\n\n@server.list_tools()\nasync def list_tools() -> list[types.Tool]:\n return [\n types.Tool(\n name=\"add\",\n description=\"Add two numbers\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\"type\": \"number\"},\n \"b\": {\"type\": \"number\"},\n },\n \"required\": [\"a\", \"b\"],\n },\n ),\n types.Tool(\n name=\"multiply\",\n description=\"Multiply two numbers\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\"type\": \"number\"},\n \"b\": {\"type\": \"number\"},\n },\n \"required\": [\"a\", \"b\"],\n },\n ),\n ]\n\n@server.call_tool()\nasync def call_tool(\n name: str, arguments: dict\n) -> list[types.TextContent]:\n if name == \"add\":\n result = arguments[\"a\"] + arguments[\"b\"]\n return [types.TextContent(type=\"text\", text=str(result))]\n elif name == \"multiply\":\n result = arguments[\"a\"] * arguments[\"b\"]\n return [types.TextContent(type=\"text\", text=str(result))]\n raise ValueError(f\"Unknown tool: {name}\")\n```\n\n```python After\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"math\")\n\n@mcp.tool\ndef add(a: float, b: float) -> float:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\n@mcp.tool\ndef multiply(a: float, b: float) -> float:\n \"\"\"Multiply two numbers\"\"\"\n return a * b\n```\n\n\n\nEach `@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.\n\n### Type Mapping\n\nWhen converting your `inputSchema` to Python type hints:\n\n| JSON Schema | Python Type |\n|---|---|\n| `{\"type\": \"string\"}` | `str` |\n| `{\"type\": \"number\"}` | `float` |\n| `{\"type\": \"integer\"}` | `int` |\n| `{\"type\": \"boolean\"}` | `bool` |\n| `{\"type\": \"array\", \"items\": {\"type\": \"string\"}}` | `list[str]` |\n| `{\"type\": \"object\"}` | `dict` |\n| Optional property (not in `required`) | `param: str \\| None = None` |\n\n### Return Values\n\nWith 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.\n\nFor images or other non-text content, FastMCP provides helpers:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.utilities.types import Image\n\nmcp = FastMCP(\"media\")\n\n@mcp.tool\ndef create_chart(data: list[float]) -> Image:\n \"\"\"Generate a chart from data.\"\"\"\n png_bytes = generate_chart(data) # your logic\n return Image(data=png_bytes, format=\"png\")\n```\n\n## Resources\n\nThe `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.\n\n\n\n```python Before\nimport json\nimport mcp.types as types\nfrom mcp.server import Server\nfrom pydantic import AnyUrl\n\nserver = Server(\"data\")\n\n@server.list_resources()\nasync def list_resources() -> list[types.Resource]:\n return [\n types.Resource(\n uri=AnyUrl(\"config://app\"),\n name=\"app_config\",\n description=\"Application configuration\",\n mimeType=\"application/json\",\n ),\n types.Resource(\n uri=AnyUrl(\"config://features\"),\n name=\"feature_flags\",\n description=\"Active feature flags\",\n mimeType=\"application/json\",\n ),\n ]\n\n@server.list_resource_templates()\nasync def list_resource_templates() -> list[types.ResourceTemplate]:\n return [\n types.ResourceTemplate(\n uriTemplate=\"users://{user_id}/profile\",\n name=\"user_profile\",\n description=\"User profile by ID\",\n ),\n types.ResourceTemplate(\n uriTemplate=\"projects://{project_id}/status\",\n name=\"project_status\",\n description=\"Project status by ID\",\n ),\n ]\n\n@server.read_resource()\nasync def read_resource(uri: AnyUrl) -> str:\n uri_str = str(uri)\n if uri_str == \"config://app\":\n return json.dumps({\"debug\": False, \"version\": \"1.0\"})\n if uri_str == \"config://features\":\n return json.dumps({\"dark_mode\": True, \"beta\": False})\n if uri_str.startswith(\"users://\"):\n user_id = uri_str.split(\"/\")[2]\n return json.dumps({\"id\": user_id, \"name\": f\"User {user_id}\"})\n if uri_str.startswith(\"projects://\"):\n project_id = uri_str.split(\"/\")[2]\n return json.dumps({\"id\": project_id, \"status\": \"active\"})\n raise ValueError(f\"Unknown resource: {uri}\")\n```\n\n```python After\nimport json\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"data\")\n\n@mcp.resource(\"config://app\", mime_type=\"application/json\")\ndef app_config() -> str:\n \"\"\"Application configuration\"\"\"\n return json.dumps({\"debug\": False, \"version\": \"1.0\"})\n\n@mcp.resource(\"config://features\", mime_type=\"application/json\")\ndef feature_flags() -> str:\n \"\"\"Active feature flags\"\"\"\n return json.dumps({\"dark_mode\": True, \"beta\": False})\n\n@mcp.resource(\"users://{user_id}/profile\")\ndef user_profile(user_id: str) -> str:\n \"\"\"User profile by ID\"\"\"\n return json.dumps({\"id\": user_id, \"name\": f\"User {user_id}\"})\n\n@mcp.resource(\"projects://{project_id}/status\")\ndef project_status(project_id: str) -> str:\n \"\"\"Project status by ID\"\"\"\n return json.dumps({\"id\": project_id, \"status\": \"active\"})\n```\n\n\n\nStatic 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.\n\n## Prompts\n\nSame pattern: the `Server` class uses `list_prompts()` and `get_prompt()` with manual routing. FastMCP uses one decorator per prompt.\n\n\n\n```python Before\nimport mcp.types as types\nfrom mcp.server import Server\n\nserver = Server(\"prompts\")\n\n@server.list_prompts()\nasync def list_prompts() -> list[types.Prompt]:\n return [\n types.Prompt(\n name=\"review_code\",\n description=\"Review code for issues\",\n arguments=[\n types.PromptArgument(\n name=\"code\",\n description=\"The code to review\",\n required=True,\n ),\n types.PromptArgument(\n name=\"language\",\n description=\"Programming language\",\n required=False,\n ),\n ],\n )\n ]\n\n@server.get_prompt()\nasync def get_prompt(\n name: str, arguments: dict[str, str] | None\n) -> types.GetPromptResult:\n if name == \"review_code\":\n code = (arguments or {}).get(\"code\", \"\")\n language = (arguments or {}).get(\"language\", \"\")\n lang_note = f\" (written in {language})\" if language else \"\"\n return types.GetPromptResult(\n description=\"Code review prompt\",\n messages=[\n types.PromptMessage(\n role=\"user\",\n content=types.TextContent(\n type=\"text\",\n text=f\"Please review this code{lang_note}:\\n\\n{code}\",\n ),\n )\n ],\n )\n raise ValueError(f\"Unknown prompt: {name}\")\n```\n\n```python After\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"prompts\")\n\n@mcp.prompt\ndef review_code(code: str, language: str | None = None) -> str:\n \"\"\"Review code for issues\"\"\"\n lang_note = f\" (written in {language})\" if language else \"\"\n return f\"Please review this code{lang_note}:\\n\\n{code}\"\n```\n\n\n\nReturning a `str` from a prompt function automatically wraps it as a user message. For multi-turn prompts, return a `list[Message]`:\n\n```python\nfrom fastmcp import FastMCP\nfrom fastmcp.prompts import Message\n\nmcp = FastMCP(\"prompts\")\n\n@mcp.prompt\ndef debug_session(error: str) -> list[Message]:\n \"\"\"Start a debugging conversation\"\"\"\n return [\n Message(f\"I'm seeing this error:\\n\\n{error}\"),\n Message(\"I'll help you debug that. Can you share the relevant code?\", role=\"assistant\"),\n ]\n```\n\n## Request Context\n\nThe `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.\n\n\n\n```python Before\nimport mcp.types as types\nfrom mcp.server import Server\n\nserver = Server(\"worker\")\n\n@server.call_tool()\nasync def call_tool(name: str, arguments: dict):\n if name == \"process_data\":\n ctx = server.request_context\n await ctx.session.send_log_message(\n level=\"info\", data=\"Starting processing...\"\n )\n # ... do work ...\n await ctx.session.send_log_message(\n level=\"info\", data=\"Done!\"\n )\n return [types.TextContent(type=\"text\", text=\"Processed\")]\n```\n\n```python After\nfrom fastmcp import FastMCP, Context\n\nmcp = FastMCP(\"worker\")\n\n@mcp.tool\nasync def process_data(ctx: Context) -> str:\n \"\"\"Process data with progress logging\"\"\"\n await ctx.info(\"Starting processing...\")\n # ... do work ...\n await ctx.info(\"Done!\")\n return \"Processed\"\n```\n\n\n\nThe `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.\n\n## Complete Example\n\nA full server upgrade, showing how all the pieces fit together:\n\n\n\n```python Before expandable\nimport asyncio\nimport json\nimport mcp.types as types\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\nfrom pydantic import AnyUrl\n\nserver = Server(\"demo\")\n\n@server.list_tools()\nasync def list_tools() -> list[types.Tool]:\n return [\n types.Tool(\n name=\"greet\",\n description=\"Greet someone by name\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n },\n \"required\": [\"name\"],\n },\n )\n ]\n\n@server.call_tool()\nasync def call_tool(name: str, arguments: dict) -> list[types.TextContent]:\n if name == \"greet\":\n return [types.TextContent(type=\"text\", text=f\"Hello, {arguments['name']}!\")]\n raise ValueError(f\"Unknown tool: {name}\")\n\n@server.list_resources()\nasync def list_resources() -> list[types.Resource]:\n return [\n types.Resource(\n uri=AnyUrl(\"info://version\"),\n name=\"version\",\n description=\"Server version\",\n )\n ]\n\n@server.read_resource()\nasync def read_resource(uri: AnyUrl) -> str:\n if str(uri) == \"info://version\":\n return json.dumps({\"version\": \"1.0.0\"})\n raise ValueError(f\"Unknown resource: {uri}\")\n\n@server.list_prompts()\nasync def list_prompts() -> list[types.Prompt]:\n return [\n types.Prompt(\n name=\"summarize\",\n description=\"Summarize text\",\n arguments=[\n types.PromptArgument(name=\"text\", required=True)\n ],\n )\n ]\n\n@server.get_prompt()\nasync def get_prompt(\n name: str, arguments: dict[str, str] | None\n) -> types.GetPromptResult:\n if name == \"summarize\":\n return types.GetPromptResult(\n description=\"Summarize text\",\n messages=[\n types.PromptMessage(\n role=\"user\",\n content=types.TextContent(\n type=\"text\",\n text=f\"Summarize:\\n\\n{(arguments or {}).get('text', '')}\",\n ),\n )\n ],\n )\n raise ValueError(f\"Unknown prompt: {name}\")\n\nasync def main():\n async with stdio_server() as (read_stream, write_stream):\n await server.run(\n read_stream, write_stream,\n server.create_initialization_options(),\n )\n\nasyncio.run(main())\n```\n\n```python After\nimport json\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"demo\")\n\n@mcp.tool\ndef greet(name: str) -> str:\n \"\"\"Greet someone by name\"\"\"\n return f\"Hello, {name}!\"\n\n@mcp.resource(\"info://version\")\ndef version() -> str:\n \"\"\"Server version\"\"\"\n return json.dumps({\"version\": \"1.0.0\"})\n\n@mcp.prompt\ndef summarize(text: str) -> str:\n \"\"\"Summarize text\"\"\"\n return f\"Summarize:\\n\\n{text}\"\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n\n\n## What's Next\n\nOnce you've upgraded, you have access to everything FastMCP provides beyond the basics:\n\n- **[Server composition](/servers/composition)** — Mount sub-servers to build modular applications\n- **[Middleware](/servers/middleware)** — Add logging, rate limiting, error handling, and caching\n- **[Proxy servers](/servers/providers/proxy)** — Create a proxy to any existing MCP server\n- **[OpenAPI integration](/integrations/openapi)** — Generate an MCP server from an OpenAPI spec\n- **[Authentication](/servers/auth/authentication)** — Built-in OAuth and token verification\n- **[Testing](/servers/testing)** — Test your server directly in Python without running a subprocess\n\nExplore the full documentation at [gofastmcp.com](https://gofastmcp.com).\n" }, { "path": "docs/getting-started/upgrading/from-mcp-sdk.mdx", "content": "---\ntitle: Upgrading from the MCP SDK\nsidebarTitle: \"From MCP SDK\"\ndescription: Upgrade from FastMCP in the MCP Python SDK to the standalone FastMCP framework\nicon: up\n---\n\nIf 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.**\n\n```python\n# Before\nfrom mcp.server.fastmcp import FastMCP\n\n# After\nfrom fastmcp import FastMCP\n```\n\nThat'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.\n\n\n**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.\n\n\n## Install\n\n```bash\npip install --upgrade fastmcp\n# or\nuv add fastmcp\n```\n\nFastMCP 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.\n\n\nYou 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.\n\nSTEP 1 — IMPORT (required for all servers):\nChange \"from mcp.server.fastmcp import FastMCP\" to \"from fastmcp import FastMCP\".\n\nSTEP 2 — CONSTRUCTOR KWARGS (only if FastMCP() receives transport settings):\nFastMCP() no longer accepts: host, port, log_level, debug, sse_path, streamable_http_path, json_response, stateless_http.\nFix: pass these to run() instead.\nBefore: `mcp = FastMCP(\"server\", host=\"0.0.0.0\", port=8080); mcp.run()`\nAfter: `mcp = FastMCP(\"server\"); mcp.run(transport=\"http\", host=\"0.0.0.0\", port=8080)`\n\nSTEP 3 — PROMPTS (only if using PromptMessage directly or returning dicts):\nmcp.types.PromptMessage is replaced by fastmcp.prompts.Message.\nBefore: `PromptMessage(role=\"user\", content=TextContent(type=\"text\", text=\"Hello\"))`\nAfter: `Message(\"Hello\")` — role defaults to \"user\", accepts plain strings.\nAlso: if prompts return raw dicts like `{\"role\": \"user\", \"content\": \"...\"}`, these must become Message objects or plain strings.\nThe MCP SDK's FastMCP 1.0 silently coerced dicts; standalone FastMCP requires typed returns.\n\nSTEP 4 — OTHER MCP IMPORTS (only if importing from mcp.* directly):\nDirect 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:\n- mcp.types.TextContent for tool returns → just return plain Python values (str, int, dict, etc.)\n- mcp.types.ImageContent → fastmcp.utilities.types.Image\n- from mcp.server.stdio import stdio_server → not needed, mcp.run() handles transport\n\nSTEP 5 — DECORATORS (only if treating decorated functions as objects):\n@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).\n\nFor each issue found, show the original line, explain what changed, and provide the corrected code.\n\n\n## What Might Need Updating\n\nMost servers need nothing beyond the import change. Skim the sections below to see if any apply.\n\n### Constructor Settings\n\nIf 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:\n\n```python\n# Before\nmcp = FastMCP(\"my-server\", host=\"0.0.0.0\", port=8080)\nmcp.run()\n\n# After\nmcp = FastMCP(\"my-server\")\nmcp.run(transport=\"http\", host=\"0.0.0.0\", port=8080)\n```\n\nIf you pass the old kwargs, you'll get a clear `TypeError` with a migration hint.\n\n### Prompts\n\nIf 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.\n\n```python\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"prompts\")\n\n@mcp.prompt\ndef review(code: str) -> str:\n \"\"\"Review code for issues\"\"\"\n return f\"Please review this code:\\n\\n{code}\"\n```\n\nFor multi-turn prompts:\n\n```python\nfrom fastmcp.prompts import Message\n\n@mcp.prompt\ndef debug(error: str) -> list[Message]:\n \"\"\"Start a debugging session\"\"\"\n return [\n Message(f\"I'm seeing this error:\\n\\n{error}\"),\n Message(\"I'll help debug that. Can you share the relevant code?\", role=\"assistant\"),\n ]\n```\n\n### Other `mcp.*` Imports\n\nIf 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.\n\nWhere FastMCP provides its own API for the same thing, it's worth switching over:\n\n| mcp Package | FastMCP Equivalent |\n|---|---|\n| `mcp.types.TextContent(type=\"text\", text=str(x))` | Just return `x` from your tool |\n| `mcp.types.ImageContent(...)` | `from fastmcp.utilities.types import Image` |\n| `mcp.types.PromptMessage(...)` | `from fastmcp.prompts import Message` |\n| `from mcp.server.stdio import stdio_server` | Not needed — `mcp.run()` handles transport |\n\nFor anything without a FastMCP equivalent (e.g., specific protocol types you use directly), the `mcp.*` import is fine to keep.\n\n### Decorated Functions\n\nIn 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:\n\n```python\n@mcp.tool\ndef greet(name: str) -> str:\n \"\"\"Greet someone\"\"\"\n return f\"Hello, {name}!\"\n\n# This works now — the function is still a regular function\nassert greet(\"World\") == \"Hello, World!\"\n```\n\nIf 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).\n\n## Verify the Upgrade\n\n```bash\n# Install\npip install --upgrade fastmcp\n\n# Check version\nfastmcp version\n\n# Run your server\npython my_server.py\n```\n\nYou can also inspect your server's registered components with the FastMCP CLI:\n\n```bash\nfastmcp inspect my_server.py\n```\n\n## Looking Ahead\n\nThe 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.\n" }, { "path": "docs/getting-started/welcome.mdx", "content": "---\ntitle: \"Welcome to FastMCP\"\nsidebarTitle: \"Welcome!\"\ndescription: The fast, Pythonic way to build MCP servers, clients, and applications.\nicon: hand-wave\nmode: center\n---\n{/* \n