Repository: tadata-org/fastapi_mcp
Branch: main
Commit: e5cad13cabfc
Files: 80
Total size: 280.4 KB
Directory structure:
gitextract_ks2z9rdn/
├── .coveragerc
├── .cursorignore
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ ├── documentation.md
│ │ └── feature_request.md
│ ├── codecov.yml
│ ├── dependabot.yml
│ ├── pull_request_template.md
│ └── workflows/
│ ├── ci.yml
│ └── release.yml
├── .gitignore
├── .pre-commit-config.yaml
├── .python-version
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── MANIFEST.in
├── README.md
├── README_zh-CN.md
├── docs/
│ ├── advanced/
│ │ ├── asgi.mdx
│ │ ├── auth.mdx
│ │ ├── deploy.mdx
│ │ ├── refresh.mdx
│ │ └── transport.mdx
│ ├── configurations/
│ │ ├── customization.mdx
│ │ └── tool-naming.mdx
│ ├── docs.json
│ └── getting-started/
│ ├── FAQ.mdx
│ ├── best-practices.mdx
│ ├── installation.mdx
│ ├── quickstart.mdx
│ └── welcome.mdx
├── examples/
│ ├── 01_basic_usage_example.py
│ ├── 02_full_schema_description_example.py
│ ├── 03_custom_exposed_endpoints_example.py
│ ├── 04_separate_server_example.py
│ ├── 05_reregister_tools_example.py
│ ├── 06_custom_mcp_router_example.py
│ ├── 07_configure_http_timeout_example.py
│ ├── 08_auth_example_token_passthrough.py
│ ├── 09_auth_example_auth0.py
│ ├── README.md
│ ├── __init__.py
│ └── shared/
│ ├── __init__.py
│ ├── apps/
│ │ ├── __init__.py
│ │ └── items.py
│ ├── auth.py
│ └── setup.py
├── fastapi_mcp/
│ ├── __init__.py
│ ├── auth/
│ │ ├── __init__.py
│ │ └── proxy.py
│ ├── openapi/
│ │ ├── __init__.py
│ │ ├── convert.py
│ │ └── utils.py
│ ├── server.py
│ ├── transport/
│ │ ├── __init__.py
│ │ ├── http.py
│ │ └── sse.py
│ ├── types.py
│ └── utils/
│ └── __init__.py
├── mypy.ini
├── pyproject.toml
├── pytest.ini
└── tests/
├── __init__.py
├── conftest.py
├── fixtures/
│ ├── complex_app.py
│ ├── conftest.py
│ ├── example_data.py
│ ├── simple_app.py
│ └── types.py
├── test_basic_functionality.py
├── test_configuration.py
├── test_http_real_transport.py
├── test_mcp_complex_app.py
├── test_mcp_execute_api_tool.py
├── test_mcp_simple_app.py
├── test_openapi_conversion.py
├── test_sse_mock_transport.py
├── test_sse_real_transport.py
└── test_types_validation.py
================================================
FILE CONTENTS
================================================
================================================
FILE: .coveragerc
================================================
[run]
omit =
examples/*
tests/*
concurrency = multiprocessing
parallel = true
sigterm = true
data_file = .coverage
source = fastapi_mcp
[report]
show_missing = true
[paths]
source =
fastapi_mcp/
================================================
FILE: .cursorignore
================================================
# Repomix output
!repomix-output.txt
!repomix-output.xml
================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.md
================================================
---
name: Bug report
about: Create a report to help us improve
title: "[BUG]"
labels: bug
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior, including example code.
**System Info**
Please specify the relevant information of your work environment.
================================================
FILE: .github/ISSUE_TEMPLATE/documentation.md
================================================
---
name: Documentation
about: Report an issue related to the fastapi-mcp documentation/examples
title: ''
labels: documentation
assignees: ''
---
================================================
FILE: .github/ISSUE_TEMPLATE/feature_request.md
================================================
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: enhancement
assignees: ''
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or screenshots about the feature request here.
================================================
FILE: .github/codecov.yml
================================================
coverage:
status:
project:
default:
base: pr
target: auto
threshold: 0.5%
informational: false
only_pulls: true
================================================
FILE: .github/dependabot.yml
================================================
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 10
labels:
- "dependencies"
- "github-actions"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 10
labels:
- "dependencies"
- "python"
================================================
FILE: .github/pull_request_template.md
================================================
## Describe your changes
## Issue ticket number and link (if applicable)
## Screenshots of the feature / bugfix
## Checklist before requesting a review
- [ ] Added relevant tests
- [ ] Run ruff & mypy
- [ ] All tests pass
================================================
FILE: .github/workflows/ci.yml
================================================
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
ruff:
name: Ruff
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v5
with:
version: "0.6.12"
enable-cache: true
cache-dependency-glob: "uv.lock"
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version-file: ".python-version"
- name: Install dependencies
run: uv sync --all-extras --dev
- name: Lint with Ruff
run: uv run ruff check .
mypy:
name: MyPy
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v5
with:
version: "0.6.12"
enable-cache: true
cache-dependency-glob: "uv.lock"
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version-file: ".python-version"
- name: Install dependencies
run: uv sync --all-extras --dev
- name: Type check with MyPy
run: uv run mypy .
test:
name: Test Python ${{ matrix.python-version }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v5
with:
version: "0.6.12"
python-version: ${{ matrix.python-version }}
enable-cache: true
cache-dependency-glob: "uv.lock"
- name: Install dependencies
run: uv sync --all-extras --dev
- name: Run tests
run: uv run pytest --cov=fastapi_mcp --cov-report=xml
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v5
with:
token: ${{ secrets.CODECOV_TOKEN }}
fail_ci_if_error: false
================================================
FILE: .github/workflows/release.yml
================================================
name: Release
on:
release:
types: [created]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install uv
uses: astral-sh/setup-uv@v5
with:
version: "0.6.12"
enable-cache: true
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version-file: ".python-version"
- name: Install build dependencies
run: |
uv sync --all-extras --dev
uv pip install build twine
- name: Build and publish
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
run: |
uv run python -m build
uv run twine check dist/*
uv run twine upload dist/*
================================================
FILE: .gitignore
================================================
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file.
.idea/
*.iml
*.iws
*.ipr
*.iws
.idea_modules/
# VSCode
.vscode/
# Ruff linter
.ruff_cache/
# Mac/OSX
.DS_Store
# Windows
Thumbs.db
ehthumbs.db
Desktop.ini
# Repomix output
repomix-output.txt
repomix-output.xml
================================================
FILE: .pre-commit-config.yaml
================================================
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: trailing-whitespace
exclude: \.(md|mdx)$
- id: check-yaml
- id: check-added-large-files
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.10
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
================================================
FILE: .python-version
================================================
3.12
================================================
FILE: CHANGELOG.md
================================================
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.4.0]
🚀 **FastAPI-MCP now supports Streamable HTTP transport.**
HTTP transport is now the recommended approach, following the specification that positions HTTP as the standard while maintaining SSE for backwards compatibility.
### ⚠️ Breaking Changes
- **`mount()` method is deprecated** and will be removed in a future version. Use `mount_http()` for HTTP transport (recommended) or `mount_sse()` for SSE transport.
### Added
- 🎉 **Streamable HTTP Transport Support** - New `mount_http()` method implementing the MCP Streamable HTTP specification
- 🎉 **Stateful Session Management** - For both HTTP and SSE transports
## [0.3.7]
### Fixed
- 🐛 Fix a bug with OAuth default_scope (#123)
## [0.3.6]
Skipped 0.3.5 due to a broken release attempt.
### Added
- 🚀 Add configurable HTTP header forwarding (#181)
### Fixed
- 🐛 Fix a bug with handling FastAPI `root_path` parameter (#163)
## [0.3.4]
### Fixed
- 🐛 Update the `mcp` dependency to `1.8.1`. Fixes [Issue #134](https://github.com/tadata-org/fastapi_mcp/issues/134) that was caused after a breaking change in mcp sdk 1.8.0.
## [0.3.3]
Fixes the broken release from 0.3.2.
### Fixed
- 🐛 Fix critical bug in openapi conversion (missing `param_desc` definition) (#107, #99)
- 🐛 Fix non-ascii support (#66)
## [0.3.2] - Broken
This is a broken release and should not be used.
### Fixed
- 🐛 Fix a bug preventing simple setup of [basic token passthrough](docs/03_authentication_and_authorization.md#basic-token-passthrough)
## [0.3.1]
🚀 FastApiMCP now supports MCP Authorization!
You can now add MCP-compliant OAuth configuration in a FastAPI-native way, using your existing FastAPI `Depends()` that we all know and love.
### Added
- 🎉 Support for Authentication / Authorization compliant to [MCP 2025-03-26 Specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization), using OAuth 2.1. (#10)
- 🎉 Support passing http headers to tool calls (#82)
## [0.3.0]
🚀 FastApiMCP now works with ASGI-transport by default.
This means the `base_url` argument is redundant, and thus has been removed.
You can still set up an explicit base URL using the `http_client` argument, and injecting your own `httpx.AsyncClient` if necessary.
### Removed
- ⚠️ Breaking Change: Removed `base_url` argument since it's not used anymore by the MCP transport.
### Fixed
- 🐛 Fix short timeout issue (#71), increasing the default timeout to 10
## [0.2.0]
### Changed
- Complete refactor from function-based API to a new class-based API with `FastApiMCP`
- Explicit separation between MCP instance creation and mounting with `mcp = FastApiMCP(app)` followed by `mcp.mount()`
- FastAPI-native approach for transport providing more flexible routing options
- Updated minimum MCP dependency to v1.6.0
### Added
- Support for deploying MCP servers separately from API service
- Support for "refreshing" with `setup_server()` when dynamically adding FastAPI routes. Fixes [Issue #19](https://github.com/tadata-org/fastapi_mcp/issues/19)
- Endpoint filtering capabilities through new parameters:
- `include_operations`: Expose only specific operations by their operation IDs
- `exclude_operations`: Expose all operations except those with specified operation IDs
- `include_tags`: Expose only operations with specific tags
- `exclude_tags`: Expose all operations except those with specific tags
### Fixed
- FastAPI-native approach for transport. Fixes [Issue #28](https://github.com/tadata-org/fastapi_mcp/issues/28)
- Numerous bugs in OpenAPI schema to tool conversion, addressing [Issue #40](https://github.com/tadata-org/fastapi_mcp/issues/40) and [Issue #45](https://github.com/tadata-org/fastapi_mcp/issues/45)
### Removed
- Function-based API (`add_mcp_server`, `create_mcp_server`, etc.)
- Custom tool support via `@mcp.tool()` decorator
## [0.1.8]
### Fixed
- Remove unneeded dependency.
## [0.1.7]
### Fixed
- [Issue #34](https://github.com/tadata-org/fastapi_mcp/issues/34): Fix syntax error.
## [0.1.6]
### Fixed
- [Issue #23](https://github.com/tadata-org/fastapi_mcp/issues/23): Hide handle_mcp_connection tool.
## [0.1.5]
### Fixed
- [Issue #25](https://github.com/tadata-org/fastapi_mcp/issues/25): Dynamically creating tools function so tools are useable.
## [0.1.4]
### Fixed
- [Issue #8](https://github.com/tadata-org/fastapi_mcp/issues/8): Converted tools unuseable due to wrong passing of arguments.
## [0.1.3]
### Fixed
- Dependency resolution issue with `mcp` package and `pydantic-settings`
## [0.1.2]
### Changed
- Complete refactor: transformed from a code generator to a direct integration library
- Replaced the CLI-based approach with a direct API for adding MCP servers to FastAPI applications
- Integrated MCP servers now mount directly to FastAPI apps at runtime instead of generating separate code
- Simplified the API with a single `add_mcp_server` function for quick integration
- Removed code generation entirely in favor of runtime integration
### Added
- Main `add_mcp_server` function for simple MCP server integration
- Support for adding custom MCP tools alongside API-derived tools
- Improved test suite
- Manage with uv
### Removed
- CLI interface and all associated commands (generate, run, install, etc.)
- Code generation functionality
## [0.1.1] - 2024-07-03
### Fixed
- Added support for PEP 604 union type syntax (e.g., `str | None`) in FastAPI endpoints
- Improved type handling in model field generation for newer Python versions (3.10+)
- Fixed compatibility issues with modern type annotations in path parameters, query parameters, and Pydantic models
## [0.1.0] - 2024-03-08
### Added
- Initial release of FastAPI-MCP
- Core functionality for converting FastAPI applications to MCP servers
- CLI tool for generating, running, and installing MCP servers
- Automatic discovery of FastAPI endpoints
- Type-safe conversion from FastAPI endpoints to MCP tools
- Documentation preservation from FastAPI to MCP
- Claude integration for easy installation and use
- API integration that automatically makes HTTP requests to FastAPI endpoints
- Examples directory with sample FastAPI application
- Basic test suite
================================================
FILE: CONTRIBUTING.md
================================================
# Contributing to FastAPI-MCP
First off, thank you for considering contributing to FastAPI-MCP!
## Development Setup
1. Make sure you have Python 3.10+ installed
2. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager
3. Fork the repository
4. Clone your fork
```bash
git clone https://github.com/YOUR-USERNAME/fastapi_mcp.git
cd fastapi-mcp
# Add the upstream remote
git remote add upstream https://github.com/tadata-org/fastapi_mcp.git
```
5. Set up the development environment:
```bash
uv sync
```
That's it! The `uv sync` command will automatically create and use a virtual environment.
6. Install pre-commit hooks:
```bash
uv run pre-commit install
uv run pre-commit run
```
Pre-commit hooks will automatically run checks (like ruff, formatting, etc.) when you make a commit, ensuring your code follows our style guidelines.
### Running Commands
You have two options for running commands:
1. **With the virtual environment activated**:
```bash
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Then run commands directly
pytest
mypy .
ruff check .
```
2. **Without activating the virtual environment**:
```bash
# Use uv run prefix for all commands
uv run pytest
uv run mypy .
uv run ruff check .
```
Both approaches work - use whichever is more convenient for you.
> **Note:** For simplicity, commands in this guide are mostly written **without** the `uv run` prefix. If you haven't activated your virtual environment, remember to prepend `uv run` to all python-related commands and tools.
### Adding Dependencies
When adding new dependencies to the library:
1. **Runtime dependencies** - packages needed to run the application:
```bash
uv add new-package
```
2. **Development dependencies** - packages needed for development, testing, or CI:
```bash
uv add --group dev new-package
```
After adding dependencies, make sure to:
1. Test that everything works with the new package
2. Commit both `pyproject.toml` and `uv.lock` files:
```bash
git add pyproject.toml uv.lock
git commit -m "Add new-package dependency"
```
## Development Process
1. Fork the repository and set the upstream remote
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run type checking (`mypy .`)
5. Run the tests (`pytest`)
6. Format your code (`ruff check .` and `ruff format .`). Not needed if pre-commit is installed, as it will run it for you.
7. Commit your changes (`git commit -m 'Add some amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request. Make sure the Pull Request's base branch is [the original repository's](https://github.com/tadata-org/fastapi_mcp/) `main` branch.
## Code Style
We use the following tools to ensure code quality:
- **ruff** for linting and formatting
- **mypy** for type checking
Please make sure your code passes all checks before submitting a pull request:
```bash
# Check code formatting and style
ruff check .
ruff format .
# Check types
mypy .
```
## Testing
We use pytest for testing. Please write tests for any new features and ensure all tests pass:
```bash
# Run all tests
pytest
```
## Pull Request Process
1. Ensure your code follows the style guidelines of the project
2. Update the README.md with details of changes if applicable
3. The versioning scheme we use is [SemVer](http://semver.org/)
4. Include a descriptive commit message
5. Your pull request will be merged once it's reviewed and approved
## Code of Conduct
Please note we have a code of conduct, please follow it in all your interactions with the project.
- Be respectful and inclusive
- Be collaborative
- When disagreeing, try to understand why
- A diverse community is a strong community
## Questions?
Don't hesitate to open an issue if you have any questions about contributing to FastAPI-MCP.
================================================
FILE: LICENSE
================================================
MIT License
Copyright (c) 2024 Tadata Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: MANIFEST.in
================================================
include LICENSE
include README.md
include INSTALL.md
include pyproject.toml
include setup.py
recursive-include examples *.py *.md
recursive-include tests *.py
global-exclude *.py[cod] __pycache__ *.so *.dylib .DS_Store
================================================
FILE: README.md
================================================
FastAPI-MCP
Expose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!
[](https://pypi.org/project/fastapi-mcp/)
[](https://pypi.org/project/fastapi-mcp/)
[](#)
[](https://github.com/tadata-org/fastapi_mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/tadata-org/fastapi_mcp)
## Features
- **Authentication** built in, using your existing FastAPI dependencies!
- **FastAPI-native:** Not just another OpenAPI -> MCP converter
- **Zero/Minimal configuration** required - just point it at your FastAPI app and it works
- **Preserving schemas** of your request models and response models
- **Preserve documentation** of all your endpoints, just as it is in Swagger
- **Flexible deployment** - Mount your MCP server to the same app, or deploy separately
- **ASGI transport** - Uses FastAPI's ASGI interface directly for efficient communication
## Hosted Solution
If you prefer a managed hosted solution check out [tadata.com](https://tadata.com).
## Installation
We recommend using [uv](https://docs.astral.sh/uv/), a fast Python package installer:
```bash
uv add fastapi-mcp
```
Alternatively, you can install with pip:
```bash
pip install fastapi-mcp
```
## Basic Usage
The simplest way to use FastAPI-MCP is to add an MCP server directly to your FastAPI application:
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
# Mount the MCP server directly to your FastAPI app
mcp.mount()
```
That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`.
## Documentation, Examples and Advanced Usage
FastAPI-MCP provides [comprehensive documentation](https://fastapi-mcp.tadata.com/). Additionaly, check out the [examples directory](examples) for code samples demonstrating these features in action.
## FastAPI-first Approach
FastAPI-MCP is designed as a native extension of FastAPI, not just a converter that generates MCP tools from your API. This approach offers several key advantages:
- **Native dependencies**: Secure your MCP endpoints using familiar FastAPI `Depends()` for authentication and authorization
- **ASGI transport**: Communicates directly with your FastAPI app using its ASGI interface, eliminating the need for HTTP calls from the MCP to your API
- **Unified infrastructure**: Your FastAPI app doesn't need to run separately from the MCP server (though [separate deployment](https://fastapi-mcp.tadata.com/advanced/deploy#deploying-separately-from-original-fastapi-app) is also supported)
This design philosophy ensures minimum friction when adding MCP capabilities to your existing FastAPI services.
## Development and Contributing
Thank you for considering contributing to FastAPI-MCP! We encourage the community to post Issues and create Pull Requests.
Before you get started, please see our [Contribution Guide](CONTRIBUTING.md).
## Community
Join [MCParty Slack community](https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg) to connect with other MCP enthusiasts, ask questions, and share your experiences with FastAPI-MCP.
## Requirements
- Python 3.10+ (Recommended 3.12)
- uv
## License
MIT License. Copyright (c) 2025 Tadata Inc.
================================================
FILE: README_zh-CN.md
================================================
FastAPI-MCP
一个零配置工具，用于自动将 FastAPI 端点公开为模型上下文协议（MCP）工具。
[](https://pypi.org/project/fastapi-mcp/)
[](https://pypi.org/project/fastapi-mcp/)
[](#)
[](https://github.com/tadata-org/fastapi_mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/tadata-org/fastapi_mcp)
> 注意：最新版本请参阅 [README.md](README.md).
## 特点
- **直接集成** - 直接将 MCP 服务器挂载到您的 FastAPI 应用
- **零配置** - 只需指向您的 FastAPI 应用即可工作
- **自动发现** - 所有 FastAPI 端点并转换为 MCP 工具
- **保留模式** - 保留您的请求模型和响应模型的模式
- **保留文档** - 保留所有端点的文档，就像在 Swagger 中一样
- **灵活部署** - 将 MCP 服务器挂载到同一应用，或单独部署
- **ASGI 传输** - 默认使用 FastAPI 的 ASGI 接口直接通信，提高效率
## 安装
我们推荐使用 [uv](https://docs.astral.sh/uv/)，一个快速的 Python 包安装器：
```bash
uv add fastapi-mcp
```
或者，您可以使用 pip 安装：
```bash
pip install fastapi-mcp
```
## 基本用法
使用 FastAPI-MCP 的最简单方法是直接将 MCP 服务器添加到您的 FastAPI 应用中：
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
# 直接将 MCP 服务器挂载到您的 FastAPI 应用
mcp.mount()
```
就是这样！您的自动生成的 MCP 服务器现在可以在 `https://app.base.url/mcp` 访问。
## 工具命名
FastAPI-MCP 使用 FastAPI 路由中的`operation_id`作为 MCP 工具的名称。如果您不指定`operation_id`，FastAPI 会自动生成一个，但这些名称可能比较晦涩。
比较以下两个端点定义：
```python
# 自动生成的 operation_id（类似于 "read_user_users__user_id__get"）
@app.get("/users/{user_id}")
async def read_user(user_id: int):
return {"user_id": user_id}
# 显式 operation_id（工具将被命名为 "get_user_info"）
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
return {"user_id": user_id}
```
为了获得更清晰、更直观的工具名称，我们建议在 FastAPI 路由定义中添加显式的`operation_id`参数。
要了解更多信息，请阅读 FastAPI 官方文档中关于 [路径操作的高级配置](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/) 的部分。
## 高级用法
FastAPI-MCP 提供了多种方式来自定义和控制 MCP 服务器的创建和配置。以下是一些高级用法模式：
### 自定义模式描述
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
name="我的 API MCP",
describe_all_responses=True, # 在工具描述中包含所有可能的响应模式
describe_full_response_schema=True # 在工具描述中包含完整的 JSON 模式
)
mcp.mount()
```
### 自定义公开的端点
您可以使用 Open API 操作 ID 或标签来控制哪些 FastAPI 端点暴露为 MCP 工具：
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
# 仅包含特定操作
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_user"]
)
# 排除特定操作
mcp = FastApiMCP(
app,
exclude_operations=["delete_user"]
)
# 仅包含具有特定标签的操作
mcp = FastApiMCP(
app,
include_tags=["users", "public"]
)
# 排除具有特定标签的操作
mcp = FastApiMCP(
app,
exclude_tags=["admin", "internal"]
)
# 结合操作 ID 和标签（包含模式）
mcp = FastApiMCP(
app,
include_operations=["user_login"],
include_tags=["public"]
)
mcp.mount()
```
关于过滤的注意事项：
- 您不能同时使用`include_operations`和`exclude_operations`
- 您不能同时使用`include_tags`和`exclude_tags`
- 您可以将操作过滤与标签过滤结合使用（例如，使用`include_operations`和`include_tags`）
- 当结合过滤器时，将采取贪婪方法。匹配任一标准的端点都将被包含
### 与原始 FastAPI 应用分开部署
您不限于在创建 MCP 的同一个 FastAPI 应用上提供 MCP 服务。
您可以从一个 FastAPI 应用创建 MCP 服务器，并将其挂载到另一个应用上：
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 您的 API 应用
api_app = FastAPI()
# ... 在 api_app 上定义您的 API 端点 ...
# 一个单独的 MCP 服务器应用
mcp_app = FastAPI()
# 从 API 应用创建 MCP 服务器
mcp = FastApiMCP(api_app)
# 将 MCP 服务器挂载到单独的应用
mcp.mount(mcp_app)
# 现在您可以分别运行两个应用：
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000
```
### 在 MCP 服务器创建后添加端点
如果您在创建 MCP 服务器后向 FastAPI 应用添加端点，您需要刷新服务器以包含它们：
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
# ... 定义初始端点 ...
# 创建 MCP 服务器
mcp = FastApiMCP(app)
mcp.mount()
# 在 MCP 服务器创建后添加新端点
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
return {"message": "Hello, world!"}
# 刷新 MCP 服务器以包含新端点
mcp.setup_server()
```
### 与 FastAPI 应用的通信
FastAPI-MCP 默认使用 ASGI 传输，这意味着它直接与您的 FastAPI 应用通信，而不需要发送 HTTP 请求。这样更高效，也不需要基础 URL。
如果您需要指定自定义基础 URL 或使用不同的传输方法，您可以提供自己的 `httpx.AsyncClient`：
```python
import httpx
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
# 使用带有特定基础 URL 的自定义 HTTP 客户端
custom_client = httpx.AsyncClient(
base_url="https://api.example.com",
timeout=30.0
)
mcp = FastApiMCP(
app,
http_client=custom_client
)
mcp.mount()
```
## 示例
请参阅 [examples](examples) 目录以获取完整示例。
## 使用 SSE 连接到 MCP 服务器
一旦您的集成了 MCP 的 FastAPI 应用运行，您可以使用任何支持 SSE 的 MCP 客户端连接到它，例如 Cursor：
1. 运行您的应用。
2. 在 Cursor -> 设置 -> MCP 中，使用您的 MCP 服务器端点的URL（例如，`http://localhost:8000/mcp`）作为 sse。
3. Cursor 将自动发现所有可用的工具和资源。
## 使用 [mcp-proxy stdio](https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#1-stdio-to-sse) 连接到 MCP 服务器
如果您的 MCP 客户端不支持 SSE，例如 Claude Desktop：
1. 运行您的应用。
2. 安装 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#installing-via-pypi)，例如：`uv tool install mcp-proxy`。
3. 在 Claude Desktop 的 MCP 配置文件（`claude_desktop_config.json`）中添加：
在 Windows 上：
```json
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
```
在 MacOS 上：
```json
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "/Full/Path/To/Your/Executable/mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
```
通过在终端运行`which mcp-proxy`来找到 mcp-proxy 的路径。
4. Claude Desktop 将自动发现所有可用的工具和资源
## 开发和贡献
感谢您考虑为 FastAPI-MCP 做出贡献！我们鼓励社区发布问题和拉取请求。
在开始之前，请参阅我们的 [贡献指南](CONTRIBUTING.md)。
## 社区
加入 [MCParty Slack 社区](https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg)，与其他 MCP 爱好者联系，提问，并分享您使用 FastAPI-MCP 的经验。
## 要求
- Python 3.10+（推荐3.12）
- uv
## 许可证
MIT License. Copyright (c) 2024 Tadata Inc.
================================================
FILE: docs/advanced/asgi.mdx
================================================
---
title: Transport
description: How to communicate with the FastAPI app
icon: microchip
---
FastAPI-MCP uses ASGI transport by default, which means it communicates directly with your FastAPI app without making HTTP requests. This is more efficient and doesn't require a base URL.
It's not even necessary that the FastAPI server will run.
If you need to specify a custom base URL or use a different transport method, you can provide your own `httpx.AsyncClient`:
```python {7-10, 14}
import httpx
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
custom_client = httpx.AsyncClient(
base_url="https://api.example.com",
timeout=30.0
)
mcp = FastApiMCP(
app,
http_client=custom_client
)
mcp.mount()
```
================================================
FILE: docs/advanced/auth.mdx
================================================
---
title: Authentication & Authorization
icon: key
---
FastAPI-MCP supports authentication and authorization using your existing FastAPI dependencies.
It also supports the full OAuth 2 flow, compliant with [MCP Spec 2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization).
It's worth noting that most MCP clients currently do not support the latest MCP spec, so for our examples we might use a bridge client such as `npx mcp-remote`. We recommend you use it as well, and we'll show our examples using it.
## Basic Token Passthrough
If you just want to be able to pass a valid authorization header, without supporting a full authentication flow, you don't need to do anything special.
You just need to make sure your MCP client is sending it:
```json {8-9, 13}
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
]
},
"env": {
"AUTH_HEADER": "Bearer "
}
}
}
```
This is enough to pass the authorization header to your FastAPI endpoints.
Optionally, if you want your MCP server to reject requests without an authorization header, you can add a dependency:
```python {1-2, 7-9}
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig
mcp = FastApiMCP(
app,
name="Protected MCP",
auth_config=AuthConfig(
dependencies=[Depends(verify_auth)],
),
)
mcp.mount_http()
```
For a complete working example of authorization header, check out the [Token Passthrough Example](https://github.com/tadata-org/fastapi_mcp/blob/main/examples/08_auth_example_token_passthrough.py) in the examples folder.
## OAuth Flow
FastAPI-MCP supports the full OAuth 2 flow, compliant with [MCP Spec 2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization).
It would look something like this:
```python {7-16}
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig
mcp = FastApiMCP(
app,
name="MCP With OAuth",
auth_config=AuthConfig(
issuer=f"https://auth.example.com/",
authorize_url=f"https://auth.example.com/authorize",
oauth_metadata_url=f"https://auth.example.com/.well-known/oauth-authorization-server",
audience="my-audience",
client_id="my-client-id",
client_secret="my-client-secret",
dependencies=[Depends(verify_auth)],
setup_proxies=True,
),
)
mcp.mount_http()
```
And you can call it like:
```json
{
"mcpServers": {
"fastapi-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp",
"8080" // Optional port number. Necessary if you want your OAuth to work and you don't have dynamic client registration.
]
}
}
}
```
You can use it with any OAuth provider that supports the OAuth 2 spec. See explanation on [AuthConfig](#authconfig-explained) for more details.
## Custom OAuth Metadata
If you already have a properly configured OAuth server that works with MCP clients, or if you want full control over the metadata, you can provide your own OAuth metadata directly:
```python {9, 22}
from fastapi import Depends
from fastapi_mcp import FastApiMCP, AuthConfig
mcp = FastApiMCP(
app,
name="MCP With Custom OAuth",
auth_config=AuthConfig(
# Provide your own complete OAuth metadata
custom_oauth_metadata={
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"registration_endpoint": "https://auth.example.com/register",
"scopes_supported": ["openid", "profile", "email"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code"],
"token_endpoint_auth_methods_supported": ["none"],
"code_challenge_methods_supported": ["S256"]
},
# Your auth checking dependency
dependencies=[Depends(verify_auth)],
),
)
mcp.mount_http()
```
This approach gives you complete control over the OAuth metadata and is useful when:
- You have a fully MCP-compliant OAuth server already configured
- You need to customize the OAuth flow beyond what the proxy approach offers
- You're using a custom or specialized OAuth implementation
For this to work, you have to make sure mcp-remote is running [on a fixed port](#add-a-fixed-port-to-mcp-remote), for example `8080`, and then configure the callback URL to `http://127.0.0.1:8080/oauth/callback` in your OAuth provider.
## Working Example with Auth0
For a complete working example of OAuth integration with Auth0, check out the [Auth0 Example](https://github.com/tadata-org/fastapi_mcp/blob/main/examples/09_auth_example_auth0.py) in the examples folder. This example demonstrates the simple case of using Auth0 as an OAuth provider, with a working example of the OAuth flow.
For it to work, you need an .env file in the root of the project with the following variables:
```
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
```
You also need to make sure to configure callback URLs properly in your Auth0 dashboard.
## AuthConfig Explained
### `setup_proxies=True`
Most OAuth providers need some adaptation to work with MCP clients. This is where `setup_proxies=True` comes in - it creates proxy endpoints that make your OAuth provider compatible with MCP clients:
```python
mcp = FastApiMCP(
app,
auth_config=AuthConfig(
# Your OAuth provider information
issuer="https://auth.example.com",
authorize_url="https://auth.example.com/authorize",
oauth_metadata_url="https://auth.example.com/.well-known/oauth-authorization-server",
# Credentials registered with your OAuth provider
client_id="your-client-id",
client_secret="your-client-secret",
# Recommended, since some clients don't specify them
audience="your-api-audience",
default_scope="openid profile email",
# Your auth checking dependency
dependencies=[Depends(verify_auth)],
# Create compatibility proxies - usually needed!
setup_proxies=True,
),
)
```
You also need to make sure to configure callback URLs properly in your OAuth provider. With mcp-remote for example, you have to [use a fixed port](#add-a-fixed-port-to-mcp-remote).
### Why Use Proxies?
Proxies solve several problems:
1. **Missing registration endpoints**:
The MCP spec expects OAuth providers to support [dynamic client registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591), but many don't.
Furthermore, dynamic client registration is probably overkill for most use cases.
The `setup_fake_dynamic_registration` option (True by default) creates a compatible endpoint that just returns a static client ID and secret.
2. **Scope handling**:
Some MCP clients don't properly request scopes, so our proxy adds the necessary scopes for you.
3. **Audience requirements**:
Some OAuth providers require an audience parameter that MCP clients don't always provide. The proxy adds this automatically.
### Add a fixed port to mcp-remote
```json
{
"mcpServers": {
"example": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp",
"8080"
]
}
}
}
```
Normally, mcp-remote will start on a random port, making it impossible to configure the OAuth provider's callback URL properly.
You have to make sure mcp-remote is running on a fixed port, for example `8080`, and then configure the callback URL to `http://127.0.0.1:8080/oauth/callback` in your OAuth provider.
================================================
FILE: docs/advanced/deploy.mdx
================================================
---
title: Deploying the Server
icon: play
---
## Deploying separately from original FastAPI app
You are not limited to serving the MCP on the same FastAPI app from which it was created.
You can create an MCP server from one FastAPI app, and mount it to a different app:
```python {9, 15, }
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# Your API app
api_app = FastAPI()
# ... define your API endpoints on api_app ...
# A separate app for the MCP server
mcp_app = FastAPI()
# Create MCP server from the API app
mcp = FastApiMCP(api_app)
# Mount the MCP server to the separate app
mcp.mount_http(mcp_app)
```
Then, you can run both apps separately:
```bash
uvicorn main:api_app --host api-host --port 8001
uvicorn main:mcp_app --host mcp-host --port 8000
```
================================================
FILE: docs/advanced/refresh.mdx
================================================
---
title: Refreshing the Server
description: Adding endpoints after MCP server creation
icon: arrows-rotate
---
If you add endpoints to your FastAPI app after creating the MCP server, you'll need to refresh the server to include them:
```python {9-12, 15}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount_http()
# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
return {"message": "Hello, world!"}
# Refresh the MCP server to include the new endpoint
mcp.setup_server()
```
================================================
FILE: docs/advanced/transport.mdx
================================================
---
title: MCP Transport
description: Understanding MCP transport methods and how to choose between them
icon: car
---
FastAPI-MCP supports two MCP transport methods for client-server communication: **HTTP transport** (recommended) and **SSE transport** (backwards compatibility).
## HTTP Transport (Recommended)
HTTP transport is the **recommended** transport method as it implements the latest MCP Streamable HTTP specification. It provides better session management, more robust connection handling, and aligns with standard HTTP practices.
### Using HTTP Transport
```python {7}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
# Mount using HTTP transport (recommended)
mcp.mount_http()
```
## SSE Transport (Backwards Compatibility)
SSE (Server-Sent Events) transport is maintained for backwards compatibility with older MCP implementations.
### Using SSE Transport
```python {7}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
# Mount using SSE transport (backwards compatibility)
mcp.mount_sse()
```
## Advanced Configuration
Both transport methods support the same FastAPI integration features like custom routing and authentication:
```python
from fastapi import FastAPI, APIRouter
from fastapi_mcp import FastApiMCP
app = FastAPI()
router = APIRouter(prefix="/api/v1")
mcp = FastApiMCP(app)
# Mount to custom path with HTTP transport
mcp.mount_http(router, mount_path="/my-http")
# Or with SSE transport
mcp.mount_sse(router, mount_path="/my-sse")
```
## Client Connection Examples
### HTTP Transport Client Connection
For HTTP transport, MCP clients connect directly to the HTTP endpoint:
```json
{
"mcpServers": {
"fastapi-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### SSE Transport Client Connection
For SSE transport, MCP clients use the same URL but communicate via Server-Sent Events:
```json
{
"mcpServers": {
"fastapi-mcp": {
"url": "http://localhost:8000/sse"
}
}
}
```
================================================
FILE: docs/configurations/customization.mdx
================================================
---
title: Customization
icon: pen
---
## Server metadata
You can define the MCP server name and description by modifying:
```python {8-9}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
name="My API MCP",
description="Very cool MCP server",
)
mcp.mount_http()
```
## Tool and schema descriptions
When creating the MCP server you can include all possible response schemas in tool descriptions by changing the flag `describe_all_responses`, or include full JSON schema in tool descriptions by changing `describe_full_response_schema`:
```python {10-11}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
name="My API MCP",
description="Very cool MCP server",
describe_all_responses=True,
describe_full_response_schema=True
)
mcp.mount_http()
```
## Customizing Exposed Endpoints
You can control which FastAPI endpoints are exposed as MCP tools using Open API operation IDs or tags to:
- Only include specific operations
- Exclude specific operations
- Only include operations with specific tags
- Exclude operations with specific tags
- Combine operation IDs and tags
### Code samples
The relevant arguments for these configurations are `include_operations`, `exclude_operations`, `include_tags`, `exclude_tags` and can be used as follows:
```python Include Operations {8}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_user"]
)
mcp.mount_http()
```
```python Exclude Operations {8}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
exclude_operations=["delete_user"]
)
mcp.mount_http()
```
```python Include Tags {8}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
include_tags=["users", "public"]
)
mcp.mount_http()
```
```python Exclude Tags {8}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
exclude_tags=["admin", "internal"]
)
mcp.mount_http()
```
```python Combined (include mode) {8-9}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
include_operations=["user_login"],
include_tags=["public"]
)
mcp.mount_http()
```
### Notes on filtering
- You cannot use both `include_operations` and `exclude_operations` at the same time
- You cannot use both `include_tags` and `exclude_tags` at the same time
- You can combine operation filtering with tag filtering (e.g., use `include_operations` with `include_tags`)
- When combining filters, a greedy approach will be taken. Endpoints matching either criteria will be included
================================================
FILE: docs/configurations/tool-naming.mdx
================================================
---
title: Tool Naming
icon: input-text
---
FastAPI-MCP uses the `operation_id` from your FastAPI routes as the MCP tool names. When you don't specify an `operation_id`, FastAPI auto-generates one, but these can be cryptic.
Compare these two endpoint definitions:
```python {2, 7}
# Auto-generated operation_id (something like "read_user_users__user_id__get")
@app.get("/users/{user_id}")
async def read_user(user_id: int):
return {"user_id": user_id}
# Explicit operation_id (tool will be named "get_user_info")
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
return {"user_id": user_id}
```
For clearer, more intuitive tool names, we recommend adding explicit `operation_id` parameters to your FastAPI route definitions.
To find out more, read FastAPI's official docs about [advanced config of path operations.](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/)
================================================
FILE: docs/docs.json
================================================
{
"$schema": "https://mintlify.com/docs.json",
"name": "FastAPI MCP",
"background": {
"color": {
"dark": "#222831",
"light": "#EEEEEE"
},
"decoration": "windows"
},
"colors": {
"primary": "#6d45dc",
"light": "#9f8ded",
"dark": "#6a42d7"
},
"description": "Convert your FastAPI app into a MCP server with zero configuration",
"favicon": "media/favicon.png",
"navigation": {
"groups": [
{
"group": "Getting Started",
"pages": [
"getting-started/welcome",
"getting-started/installation",
"getting-started/quickstart",
"getting-started/FAQ",
"getting-started/best-practices"
]
},
{
"group": "Configurations",
"pages": ["configurations/tool-naming", "configurations/customization"]
},
{
"group": "Advanced Usage",
"pages": [
"advanced/auth",
"advanced/deploy",
"advanced/refresh",
"advanced/asgi",
"advanced/transport"
]
}
],
"global": {
"anchors": [
{
"anchor": "Documentation",
"href": "https://fastapi-mcp.tadata.com/",
"icon": "book-open-cover"
},
{
"anchor": "Community",
"href": "https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg",
"icon": "slack"
},
{
"anchor": "Blog",
"href": "https://medium.com/@miki_45906",
"icon": "newspaper"
}
]
}
},
"logo": {
"light": "/media/dark_logo.png",
"dark": "/media/light_logo.png",
"href": "https://tadata.com/"
},
"navbar": {
"primary": {
"href": "https://github.com/tadata-org/fastapi_mcp",
"type": "github"
}
},
"footer": {
"socials": {
"x": "https://x.com/makhlevich",
"github": "https://github.com/tadata-org/fastapi_mcp",
"website": "https://tadata.com/"
}
},
"theme": "mint"
}
================================================
FILE: docs/getting-started/FAQ.mdx
================================================
---
title: FAQ
description: Frequently Asked Questions
icon: question
---
## Usage
### How do I configure HTTP request timeouts?
By default, HTTP requests timeout after 5 seconds. If you have API endpoints that take longer to respond, you can configure a custom timeout by injecting your own httpx client.
For a working example, see [Configure HTTP Timeout Example](https://github.com/tadata-org/fastapi_mcp/blob/main/examples/07_configure_http_timeout_example.py).
### Why are my tools not showing up in the MCP inspector?
If you add endpoints after creating and mounting the MCP server, they won't be automatically registered as tools. You need to either:
1. Move the MCP creation after all your endpoint definitions
2. Call `mcp.setup_server()` after adding new endpoints to re-register all tools
For a working example, see [Reregister Tools Example](https://github.com/tadata-org/fastapi_mcp/blob/main/examples/05_reregister_tools_example.py).
### Can I add custom tools other than FastAPI endpoints?
Currently, FastApiMCP only supports tools that are derived from FastAPI endpoints. If you need to add custom tools that don't correspond to API endpoints, you can:
1. Create a FastAPI endpoint that wraps your custom functionality
2. Contribute to the project by implementing custom tool support
Follow the discussion in [issue #75](https://github.com/tadata-org/fastapi_mcp/issues/75) for updates on this feature request.
If you have specific use cases for custom tools, please share them in the issue to help guide the implementation.
### How do I test my FastApiMCP server is working?
To verify your FastApiMCP server is working properly, you can use the MCP Inspector tool. Here's how:
1. Start your FastAPI application
2. Open a new terminal and run the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector
```
3. Connect to your MCP server by entering the mount path URL (default: `http://127.0.0.1:8000/mcp`)
4. Navigate to the `Tools` section and click `List Tools` to see all available endpoints
5. Test an endpoint by:
- Selecting a tool from the list
- Filling in any required parameters
- Clicking `Run Tool` to execute
6. Check your server logs for additional debugging information if needed
This will help confirm that your MCP server is properly configured and your endpoints are accessible.
## Development
### Can I contribute to the project?
Yes! Please read our [CONTRIBUTING.md](https://github.com/tadata-org/fastapi_mcp/blob/main/CONTRIBUTING.md) file for detailed guidelines on how to contribute to the project and where to start.
## Support
### Where can I get help?
- Check the documentation
- Open an issue on GitHub
- Join our community chat [MCParty Slack community](https://join.slack.com/t/themcparty/shared_invite/zt-30yxr1zdi-2FG~XjBA0xIgYSYuKe7~Xg)
================================================
FILE: docs/getting-started/best-practices.mdx
================================================
---
title: Best Practices
icon: thumbs-up
---
This guide outlines best practices for converting standard APIs into Model Context Protocol (MCP) tools for use with AI agents. Proper tool design helps ensure LLMs can understand and safely use your APIs.
By following these best practices, you can build safer, more intuitive MCP tools that enhance the capabilities of LLM agents.
## Tool Selection
- **Be selective:**
Avoid exposing every endpoint as a tool. LLM clients perform better with a limited number of well-defined tools, and providers often impose tool limits.
- **Prioritize safety:**
Do **not** expose `PUT` or `DELETE` endpoints unless absolutely necessary. LLMs are non-deterministic and could unintentionally alter or damage systems or databases.
- **Focus on data retrieval:**
Prefer `GET` endpoints that return data safely and predictably.
- **Emphasize meaningful workflows:**
Expose endpoints that reflect clear, goal-oriented tasks. Tools with focused actions are easier for agents to understand and use effectively.
## Tool Naming
- **Use short, descriptive names:**
Helps LLMs select and use the right tool. Know that some MCP clients restrict tool name length.
- **Follow naming constraints:**
- Must start with a letter
- Can include only letters, numbers, and underscores
- Avoid hyphens (e.g., AWS Nova does **not** support them)
- Use either `camelCase` or `snake_case` consistently across all tools
- **Ensure uniqueness:**
Each tool name should be unique and clearly indicate its function.
## Documentation
- **Describe every tool meaningfully:**
Provide a clear and concise summary of what each tool does.
- **Include usage examples and parameter descriptions:**
These help LLMs understand how to use the tool correctly.
- **Standardize documentation across tools:**
Keep formatting and structure consistent to maintain quality and readability.
================================================
FILE: docs/getting-started/installation.mdx
================================================
---
title: Installation
icon: arrow-down-to-line
---
## Install FastAPI-MCP
We recommend using [uv](https://docs.astral.sh/uv/), a fast Python package installer:
```bash
uv add fastapi-mcp
```
Alternatively, you can install with `pip` or `uv pip`:
```bash uv
uv pip install fastapi-mcp
```
```bash pip
pip install fastapi-mcp
```
================================================
FILE: docs/getting-started/quickstart.mdx
================================================
---
title: Quickstart
icon: rocket
---
This guide will help you quickly run your first MCP server using FastAPI-MCP.
If you haven't already installed FastAPI-MCP, follow the [installation instructions](/getting-started/installation).
## Creating a basic MCP server
To create a basic MCP server, import or create a FastAPI app, wrap it with the `FastApiMCP` class and mount the MCP to your existing application:
```python {2, 8, 11}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# Create (or import) a FastAPI app
app = FastAPI()
# Create an MCP server based on this app
mcp = FastApiMCP(app)
# Mount the MCP server directly to your app
mcp.mount_http()
```
For more usage examples, see [Examples](https://github.com/tadata-org/fastapi_mcp/tree/main/examples) section in the project.
## Running the server
By running your FastAPI, your MCP will run at `https://app.base.url/mcp`.
For example, by using uvicorn, add to your code:
```python {9-11}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
```
and run the server using `python fastapi_mcp_server.py`, which will serve you the MCP at `http://localhost:8000/mcp`.
## Connecting a client to the MCP server
Once your FastAPI app with MCP integration is running, you would want to connect it to an MCP client.
### Connecting to the MCP Server using SSE
For any MCP client supporting SSE, you will simply need to provide the MCP url.
All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the following config format:
```json
{
"mcpServers": {
"fastapi-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### Connecting to the MCP Server using [mcp-remote](https://www.npmjs.com/package/mcp-remote)
If you want to support authentication, or your MCP client does not support SSE, we recommend using `mcp-remote` as a bridge.
```json
{
"mcpServers": {
"fastapi-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp",
"8080" // Optional port number. Necessary if you want your OAuth to work and you don't have dynamic client registration.
]
}
}
}
```
================================================
FILE: docs/getting-started/welcome.mdx
================================================
---
title: "Welcome to FastAPI-MCP!"
sidebarTitle: "Welcome!"
description: Expose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!
icon: hand-wave
---
MCP (Model Context Protocol) is the emerging standard to define how AI agents communicate with applications. Using FastAPI-MCP, creating a secured MCP server to your application takes only 3 lines of code:
```python {2, 6, 7}
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount_http()
```
That's it! Your auto-generated MCP server is now available at `https://app.base.url/mcp`
## Features
- [**Authentication**](/advanced/auth) built in, using your existing FastAPI dependencies!
- **FastAPI-native:** Not just another OpenAPI -> MCP converter
- **Zero configuration** required - just point it at your FastAPI app and it works
- **Preserving schemas** of your request models and response models
- **Preserve documentation** of all your endpoints, just as it is in Swagger
- [**Flexible deployment**](/advanced/deploy) - Mount your MCP server to the same app, or deploy separately
- [**ASGI interface**](/advanced/asgi) - Uses FastAPI's ASGI interface directly for efficient internal communication
## Hosted Solution
If you prefer a managed hosted solution check out [tadata.com](https://tadata.com).
================================================
FILE: examples/01_basic_usage_example.py
================================================
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
# Add MCP server to the FastAPI app
mcp = FastApiMCP(app)
# Mount the MCP server to the FastAPI app
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/02_full_schema_description_example.py
================================================
"""
This example shows how to describe the full response schema instead of just a response example.
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
# Add MCP server to the FastAPI app
mcp = FastApiMCP(
app,
name="Item API MCP",
description="MCP server for the Item API",
describe_full_response_schema=True, # Describe the full response JSON-schema instead of just a response example
describe_all_responses=True, # Describe all the possible responses instead of just the success (2XX) response
)
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/03_custom_exposed_endpoints_example.py
================================================
"""
This example shows how to customize exposing endpoints by filtering operation IDs and tags.
Notes on filtering:
- You cannot use both `include_operations` and `exclude_operations` at the same time
- You cannot use both `include_tags` and `exclude_tags` at the same time
- You can combine operation filtering with tag filtering (e.g., use `include_operations` with `include_tags`)
- When combining filters, a greedy approach will be taken. Endpoints matching either criteria will be included
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
# Examples demonstrating how to filter MCP tools by operation IDs and tags
# Filter by including specific operation IDs
include_operations_mcp = FastApiMCP(
app,
name="Item API MCP - Included Operations",
include_operations=["get_item", "list_items"],
)
# Filter by excluding specific operation IDs
exclude_operations_mcp = FastApiMCP(
app,
name="Item API MCP - Excluded Operations",
exclude_operations=["create_item", "update_item", "delete_item"],
)
# Filter by including specific tags
include_tags_mcp = FastApiMCP(
app,
name="Item API MCP - Included Tags",
include_tags=["items"],
)
# Filter by excluding specific tags
exclude_tags_mcp = FastApiMCP(
app,
name="Item API MCP - Excluded Tags",
exclude_tags=["search"],
)
# Combine operation IDs and tags (include mode)
combined_include_mcp = FastApiMCP(
app,
name="Item API MCP - Combined Include",
include_operations=["delete_item"],
include_tags=["search"],
)
# Mount all MCP servers with different paths
include_operations_mcp.mount_http(mount_path="/include-operations-mcp")
exclude_operations_mcp.mount_http(mount_path="/exclude-operations-mcp")
include_tags_mcp.mount_http(mount_path="/include-tags-mcp")
exclude_tags_mcp.mount_http(mount_path="/exclude-tags-mcp")
combined_include_mcp.mount_http(mount_path="/combined-include-mcp")
if __name__ == "__main__":
import uvicorn
print("Server is running with multiple MCP endpoints:")
print(" - /include-operations-mcp: Only get_item and list_items operations")
print(" - /exclude-operations-mcp: All operations except create_item, update_item, and delete_item")
print(" - /include-tags-mcp: Only operations with the 'items' tag")
print(" - /exclude-tags-mcp: All operations except those with the 'search' tag")
print(" - /combined-include-mcp: Operations with 'search' tag or delete_item operation")
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/04_separate_server_example.py
================================================
"""
This example shows how to run the MCP server and the FastAPI app separately.
You can create an MCP server from one FastAPI app, and mount it to a different app.
"""
from fastapi import FastAPI
from examples.shared.apps.items import app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
MCP_SERVER_HOST = "localhost"
MCP_SERVER_PORT = 8000
ITEMS_API_HOST = "localhost"
ITEMS_API_PORT = 8001
# Take the FastAPI app only as a source for MCP server generation
mcp = FastApiMCP(app)
# Mount the MCP server to a separate FastAPI app
mcp_app = FastAPI()
mcp.mount_http(mcp_app)
# Run the MCP server separately from the original FastAPI app.
# It still works 🚀
# Your original API is **not exposed**, only via the MCP server.
if __name__ == "__main__":
import uvicorn
uvicorn.run(mcp_app, host="0.0.0.0", port=8000)
================================================
FILE: examples/05_reregister_tools_example.py
================================================
"""
This example shows how to re-register tools if you add endpoints after the MCP server was created.
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
mcp = FastApiMCP(app) # Add MCP server to the FastAPI app
mcp.mount_http() # MCP server
# This endpoint will not be registered as a tool, since it was added after the MCP instance was created
@app.get("/new/endpoint/", operation_id="new_endpoint", response_model=dict[str, str])
async def new_endpoint():
return {"message": "Hello, world!"}
# But if you re-run the setup, the new endpoints will now be exposed.
mcp.setup_server()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/06_custom_mcp_router_example.py
================================================
"""
This example shows how to mount the MCP server to a specific APIRouter, giving a custom mount path.
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi import APIRouter
from fastapi_mcp import FastApiMCP
setup_logging()
other_router = APIRouter(prefix="/other/route")
app.include_router(other_router)
mcp = FastApiMCP(app)
# Mount the MCP server to a specific router.
# It will now only be available at `/other/route/mcp`
mcp.mount_http(other_router)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/07_configure_http_timeout_example.py
================================================
"""
This example shows how to configure the HTTP client timeout for the MCP server.
In case you have API endpoints that take longer than 5 seconds to respond, you can increase the timeout.
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
import httpx
from fastapi_mcp import FastApiMCP
setup_logging()
mcp = FastApiMCP(app, http_client=httpx.AsyncClient(timeout=20))
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/08_auth_example_token_passthrough.py
================================================
"""
This example shows how to reject any request without a valid token passed in the Authorization header.
In order to configure the auth header, the config file for the MCP server should looks like this:
```json
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8000/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
]
},
"env": {
"AUTH_HEADER": "Bearer "
}
}
}
```
"""
from examples.shared.apps.items import app # The FastAPI app
from examples.shared.setup import setup_logging
from fastapi import Depends
from fastapi.security import HTTPBearer
from fastapi_mcp import FastApiMCP, AuthConfig
setup_logging()
# Scheme for the Authorization header
token_auth_scheme = HTTPBearer()
# Create a private endpoint
@app.get("/private")
async def private(token=Depends(token_auth_scheme)):
return token.credentials
# Create the MCP server with the token auth scheme
mcp = FastApiMCP(
app,
name="Protected MCP",
auth_config=AuthConfig(
dependencies=[Depends(token_auth_scheme)],
),
)
# Mount the MCP server
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/09_auth_example_auth0.py
================================================
from fastapi import FastAPI, Depends, HTTPException, Request, status
from pydantic_settings import BaseSettings
from typing import Any
import logging
from fastapi_mcp import FastApiMCP, AuthConfig
from examples.shared.auth import fetch_jwks_public_key
from examples.shared.setup import setup_logging
setup_logging()
logger = logging.getLogger(__name__)
class Settings(BaseSettings):
"""
For this to work, you need an .env file in the root of the project with the following variables:
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
"""
auth0_domain: str # Auth0 domain, e.g. "your-tenant.auth0.com"
auth0_audience: str # Audience, e.g. "https://your-tenant.auth0.com/api/v2/"
auth0_client_id: str
auth0_client_secret: str
@property
def auth0_jwks_url(self):
return f"https://{self.auth0_domain}/.well-known/jwks.json"
@property
def auth0_oauth_metadata_url(self):
return f"https://{self.auth0_domain}/.well-known/openid-configuration"
class Config:
env_file = ".env"
settings = Settings() # type: ignore
async def lifespan(app: FastAPI):
app.state.jwks_public_key = await fetch_jwks_public_key(settings.auth0_jwks_url)
logger.info(f"Auth0 client ID in settings: {settings.auth0_client_id}")
logger.info(f"Auth0 domain in settings: {settings.auth0_domain}")
logger.info(f"Auth0 audience in settings: {settings.auth0_audience}")
yield
async def verify_auth(request: Request) -> dict[str, Any]:
try:
import jwt
auth_header = request.headers.get("authorization", "")
if not auth_header.startswith("Bearer "):
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid authorization header")
token = auth_header.split(" ")[1]
header = jwt.get_unverified_header(token)
# Check if this is a JWE token (encrypted token)
if header.get("alg") == "dir" and header.get("enc") == "A256GCM":
raise ValueError(
"Token is encrypted, offline validation not possible. "
"This is usually due to not specifying the audience when requesting the token."
)
# Otherwise, it's a JWT, we can validate it offline
if header.get("alg") in ["RS256", "HS256"]:
claims = jwt.decode(
token,
app.state.jwks_public_key,
algorithms=["RS256", "HS256"],
audience=settings.auth0_audience,
issuer=f"https://{settings.auth0_domain}/",
options={"verify_signature": True},
)
return claims
except Exception as e:
logger.error(f"Auth error: {str(e)}")
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Unauthorized")
async def get_current_user_id(claims: dict = Depends(verify_auth)) -> str:
user_id = claims.get("sub")
if not user_id:
logger.error("No user ID found in token")
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Unauthorized")
return user_id
app = FastAPI(lifespan=lifespan)
@app.get("/api/public", operation_id="public")
async def public():
return {"message": "This is a public route"}
@app.get("/api/protected", operation_id="protected")
async def protected(user_id: str = Depends(get_current_user_id)):
return {"message": f"Hello, {user_id}!", "user_id": user_id}
# Set up FastAPI-MCP with Auth0 auth
mcp = FastApiMCP(
app,
name="MCP With Auth0",
description="Example of FastAPI-MCP with Auth0 authentication",
auth_config=AuthConfig(
issuer=f"https://{settings.auth0_domain}/",
authorize_url=f"https://{settings.auth0_domain}/authorize",
oauth_metadata_url=settings.auth0_oauth_metadata_url,
audience=settings.auth0_audience,
client_id=settings.auth0_client_id,
client_secret=settings.auth0_client_secret,
dependencies=[Depends(verify_auth)],
setup_proxies=True,
),
)
# Mount the MCP server
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
================================================
FILE: examples/README.md
================================================
# FastAPI-MCP Examples
The following examples demonstrate various features and usage patterns of FastAPI-MCP:
1. [Basic Usage Example](01_basic_usage_example.py) - Basic FastAPI-MCP integration
2. [Full Schema Description](02_full_schema_description_example.py) - Customizing schema descriptions
3. [Custom Exposed Endpoints](03_custom_exposed_endpoints_example.py) - Controlling which endpoints are exposed
4. [Separate Server](04_separate_server_example.py) - Deploying MCP server separately
5. [Reregister Tools](05_reregister_tools_example.py) - Adding endpoints after MCP server creation
6. [Custom MCP Router](06_custom_mcp_router_example.py) - Advanced routing configuration
7. [Configure HTTP Timeout](07_configure_http_timeout_example.py) - Customizing timeout settings
================================================
FILE: examples/__init__.py
================================================
================================================
FILE: examples/shared/__init__.py
================================================
================================================
FILE: examples/shared/apps/__init__.py
================================================
================================================
FILE: examples/shared/apps/items.py
================================================
"""
Simple example of using FastAPI-MCP to add an MCP server to a FastAPI app.
"""
from fastapi import FastAPI, HTTPException, Query
from pydantic import BaseModel
from typing import List, Optional
app = FastAPI()
class Item(BaseModel):
id: int
name: str
description: Optional[str] = None
price: float
tags: List[str] = []
items_db: dict[int, Item] = {}
@app.get("/items/", response_model=List[Item], tags=["items"], operation_id="list_items")
async def list_items(skip: int = 0, limit: int = 10):
"""
List all items in the database.
Returns a list of items, with pagination support.
"""
return list(items_db.values())[skip : skip + limit]
@app.get("/items/{item_id}", response_model=Item, tags=["items"], operation_id="get_item")
async def read_item(item_id: int):
"""
Get a specific item by its ID.
Raises a 404 error if the item does not exist.
"""
if item_id not in items_db:
raise HTTPException(status_code=404, detail="Item not found")
return items_db[item_id]
@app.post("/items/", response_model=Item, tags=["items"], operation_id="create_item")
async def create_item(item: Item):
"""
Create a new item in the database.
Returns the created item with its assigned ID.
"""
items_db[item.id] = item
return item
@app.put("/items/{item_id}", response_model=Item, tags=["items"], operation_id="update_item")
async def update_item(item_id: int, item: Item):
"""
Update an existing item.
Raises a 404 error if the item does not exist.
"""
if item_id not in items_db:
raise HTTPException(status_code=404, detail="Item not found")
item.id = item_id
items_db[item_id] = item
return item
@app.delete("/items/{item_id}", tags=["items"], operation_id="delete_item")
async def delete_item(item_id: int):
"""
Delete an item from the database.
Raises a 404 error if the item does not exist.
"""
if item_id not in items_db:
raise HTTPException(status_code=404, detail="Item not found")
del items_db[item_id]
return {"message": "Item deleted successfully"}
@app.get("/items/search/", response_model=List[Item], tags=["search"], operation_id="search_items")
async def search_items(
q: Optional[str] = Query(None, description="Search query string"),
min_price: Optional[float] = Query(None, description="Minimum price"),
max_price: Optional[float] = Query(None, description="Maximum price"),
tags: List[str] = Query([], description="Filter by tags"),
):
"""
Search for items with various filters.
Returns a list of items that match the search criteria.
"""
results = list(items_db.values())
if q:
q = q.lower()
results = [
item for item in results if q in item.name.lower() or (item.description and q in item.description.lower())
]
if min_price is not None:
results = [item for item in results if item.price >= min_price]
if max_price is not None:
results = [item for item in results if item.price <= max_price]
if tags:
results = [item for item in results if all(tag in item.tags for tag in tags)]
return results
sample_items = [
Item(id=1, name="Hammer", description="A tool for hammering nails", price=9.99, tags=["tool", "hardware"]),
Item(id=2, name="Screwdriver", description="A tool for driving screws", price=7.99, tags=["tool", "hardware"]),
Item(id=3, name="Wrench", description="A tool for tightening bolts", price=12.99, tags=["tool", "hardware"]),
Item(id=4, name="Saw", description="A tool for cutting wood", price=19.99, tags=["tool", "hardware", "cutting"]),
Item(id=5, name="Drill", description="A tool for drilling holes", price=49.99, tags=["tool", "hardware", "power"]),
]
for item in sample_items:
items_db[item.id] = item
================================================
FILE: examples/shared/auth.py
================================================
from jwt.algorithms import RSAAlgorithm
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
import logging
import httpx
from examples.shared.setup import setup_logging
setup_logging()
logger = logging.getLogger(__name__)
async def fetch_jwks_public_key(url: str) -> str:
"""
Fetch JWKS from a given URL and extract the primary public key in PEM format.
Args:
url: The JWKS URL to fetch from
Returns:
PEM-formatted public key as a string
"""
logger.info(f"Fetching JWKS from: {url}")
async with httpx.AsyncClient() as client:
response = await client.get(url)
response.raise_for_status()
jwks_data = response.json()
if not jwks_data or "keys" not in jwks_data or not jwks_data["keys"]:
logger.error("Invalid JWKS data format: missing or empty 'keys' array")
raise ValueError("Invalid JWKS data format: missing or empty 'keys' array")
# Just use the first key in the set
jwk = jwks_data["keys"][0]
# Convert JWK to PEM format
public_key = RSAAlgorithm.from_jwk(jwk)
if isinstance(public_key, RSAPublicKey):
pem = public_key.public_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PublicFormat.SubjectPublicKeyInfo,
)
pem_str = pem.decode("utf-8")
logger.info("Successfully extracted public key from JWKS")
return pem_str
else:
logger.error("Invalid JWKS data format: expected RSA public key")
raise ValueError("Invalid JWKS data format: expected RSA public key")
================================================
FILE: examples/shared/setup.py
================================================
import logging
from pydantic import BaseModel
class LoggingConfig(BaseModel):
LOGGER_NAME: str = "fastapi_mcp"
LOG_FORMAT: str = "%(levelprefix)s %(asctime)s\t[%(name)s] %(message)s"
LOG_LEVEL: str = logging.getLevelName(logging.DEBUG)
version: int = 1
disable_existing_loggers: bool = False
formatters: dict = {
"default": {
"()": "uvicorn.logging.DefaultFormatter",
"fmt": LOG_FORMAT,
"datefmt": "%Y-%m-%d %H:%M:%S",
},
}
handlers: dict = {
"default": {
"formatter": "default",
"class": "logging.StreamHandler",
"stream": "ext://sys.stdout",
},
}
loggers: dict = {
"": {"handlers": ["default"], "level": LOG_LEVEL}, # Root logger
"uvicorn": {"handlers": ["default"], "level": LOG_LEVEL},
LOGGER_NAME: {"handlers": ["default"], "level": LOG_LEVEL},
}
def setup_logging():
from logging.config import dictConfig
logging_config = LoggingConfig()
dictConfig(logging_config.model_dump())
================================================
FILE: fastapi_mcp/__init__.py
================================================
"""
FastAPI-MCP: Automatic MCP server generator for FastAPI applications.
Created by Tadata Inc. (https://github.com/tadata-org)
"""
try:
from importlib.metadata import version
__version__ = version("fastapi-mcp")
except Exception: # pragma: no cover
# Fallback for local development
__version__ = "0.0.0.dev0" # pragma: no cover
from .server import FastApiMCP
from .types import AuthConfig, OAuthMetadata
__all__ = [
"FastApiMCP",
"AuthConfig",
"OAuthMetadata",
]
================================================
FILE: fastapi_mcp/auth/__init__.py
================================================
================================================
FILE: fastapi_mcp/auth/proxy.py
================================================
from typing_extensions import Annotated, Doc
from fastapi import FastAPI, HTTPException, Request, status
from fastapi.responses import RedirectResponse
import httpx
from typing import Optional
import logging
from urllib.parse import urlencode
from fastapi_mcp.types import (
ClientRegistrationRequest,
ClientRegistrationResponse,
AuthConfig,
OAuthMetadata,
OAuthMetadataDict,
StrHttpUrl,
)
logger = logging.getLogger(__name__)
def setup_oauth_custom_metadata(
app: Annotated[FastAPI, Doc("The FastAPI app instance")],
auth_config: Annotated[AuthConfig, Doc("The AuthConfig used")],
metadata: Annotated[OAuthMetadataDict, Doc("The custom metadata specified in AuthConfig")],
include_in_schema: Annotated[bool, Doc("Whether to include the metadata endpoint in your OpenAPI docs")] = False,
):
"""
Just serve the custom metadata provided to AuthConfig under the path specified in `metadata_path`.
"""
auth_config = AuthConfig.model_validate(auth_config)
metadata = OAuthMetadata.model_validate(metadata)
@app.get(
auth_config.metadata_path,
response_model=OAuthMetadata,
response_model_exclude_unset=True,
response_model_exclude_none=True,
include_in_schema=include_in_schema,
operation_id="oauth_custom_metadata",
)
async def oauth_metadata_proxy():
return metadata
def setup_oauth_metadata_proxy(
app: Annotated[FastAPI, Doc("The FastAPI app instance")],
metadata_url: Annotated[
str,
Doc(
"""
The URL of the OAuth provider's metadata endpoint that you want to proxy.
"""
),
],
path: Annotated[
str,
Doc(
"""
The path to mount the OAuth metadata endpoint at.
Clients will usually expect this to be /.well-known/oauth-authorization-server
"""
),
] = "/.well-known/oauth-authorization-server",
authorize_path: Annotated[
str,
Doc(
"""
The path to mount the authorize endpoint at.
Clients will usually expect this to be /oauth/authorize
"""
),
] = "/oauth/authorize",
register_path: Annotated[
Optional[str],
Doc(
"""
The path to mount the register endpoint at.
Clients will usually expect this to be /oauth/register
"""
),
] = None,
include_in_schema: Annotated[bool, Doc("Whether to include the metadata endpoint in your OpenAPI docs")] = False,
):
"""
Proxy for your OAuth provider's Metadata endpoint, just adding our (fake) registration endpoint.
"""
@app.get(
path,
response_model=OAuthMetadata,
response_model_exclude_unset=True,
response_model_exclude_none=True,
include_in_schema=include_in_schema,
operation_id="oauth_metadata_proxy",
)
async def oauth_metadata_proxy(request: Request):
base_url = str(request.base_url).rstrip("/")
# Fetch your OAuth provider's OpenID Connect metadata
async with httpx.AsyncClient() as client:
response = await client.get(metadata_url)
if response.status_code != 200:
logger.error(
f"Failed to fetch OAuth metadata from {metadata_url}: {response.status_code}. Response: {response.text}"
)
raise HTTPException(
status_code=status.HTTP_502_BAD_GATEWAY,
detail="Failed to fetch OAuth metadata",
)
oauth_metadata = response.json()
# Override the registration endpoint if provided
if register_path:
oauth_metadata["registration_endpoint"] = f"{base_url}{register_path}"
# Replace your OAuth provider's authorize endpoint with our proxy
oauth_metadata["authorization_endpoint"] = f"{base_url}{authorize_path}"
return OAuthMetadata.model_validate(oauth_metadata)
def setup_oauth_authorize_proxy(
app: Annotated[FastAPI, Doc("The FastAPI app instance")],
client_id: Annotated[
str,
Doc(
"""
In case the client doesn't specify a client ID, this will be used as the default client ID on the
request to your OAuth provider.
"""
),
],
authorize_url: Annotated[
Optional[StrHttpUrl],
Doc(
"""
The URL of your OAuth provider's authorization endpoint.
Usually this is something like `https://app.example.com/oauth/authorize`.
"""
),
],
audience: Annotated[
Optional[str],
Doc(
"""
Currently (2025-04-21), some Auth-supporting MCP clients (like `npx mcp-remote`) might not specify the
audience when sending a request to your server.
This may cause unexpected behavior from your OAuth provider, so this is a workaround.
In case the client doesn't specify an audience, this will be used as the default audience on the
request to your OAuth provider.
"""
),
] = None,
default_scope: Annotated[
str,
Doc(
"""
Currently (2025-04-21), some Auth-supporting MCP clients (like `npx mcp-remote`) might not specify the
scope when sending a request to your server.
This may cause unexpected behavior from your OAuth provider, so this is a workaround.
Here is where you can optionally specify a default scope that will be sent to your OAuth provider in case
the client doesn't specify it.
"""
),
] = "openid profile email",
path: Annotated[str, Doc("The path to mount the authorize endpoint at")] = "/oauth/authorize",
include_in_schema: Annotated[bool, Doc("Whether to include the authorize endpoint in your OpenAPI docs")] = False,
):
"""
Proxy for your OAuth provider's authorize endpoint that logs the requested scopes and adds
default scopes and the audience parameter if not provided.
"""
@app.get(
path,
include_in_schema=include_in_schema,
)
async def oauth_authorize_proxy(
response_type: str = "code",
client_id: Optional[str] = client_id,
redirect_uri: Optional[str] = None,
scope: str = "",
state: Optional[str] = None,
code_challenge: Optional[str] = None,
code_challenge_method: Optional[str] = None,
audience: Optional[str] = audience,
):
if not scope:
logger.warning("Client didn't provide any scopes! Using default scopes.")
scope = default_scope
logger.debug(f"Default scope: {scope}")
scopes = scope.split()
logger.debug(f"Scopes passed: {scopes}")
for required_scope in default_scope.split():
if required_scope not in scopes:
scopes.append(required_scope)
params = {
"response_type": response_type,
"client_id": client_id,
"redirect_uri": redirect_uri,
"scope": " ".join(scopes),
"audience": audience,
}
if state:
params["state"] = state
if code_challenge:
params["code_challenge"] = code_challenge
if code_challenge_method:
params["code_challenge_method"] = code_challenge_method
auth_url = f"{authorize_url}?{urlencode(params)}"
return RedirectResponse(url=auth_url)
def setup_oauth_fake_dynamic_register_endpoint(
app: Annotated[FastAPI, Doc("The FastAPI app instance")],
client_id: Annotated[str, Doc("The client ID of the pre-registered client")],
client_secret: Annotated[str, Doc("The client secret of the pre-registered client")],
path: Annotated[str, Doc("The path to mount the register endpoint at")] = "/oauth/register",
include_in_schema: Annotated[bool, Doc("Whether to include the register endpoint in your OpenAPI docs")] = False,
):
"""
A proxy for dynamic client registration endpoint.
In MCP 2025-03-26 Spec, it is recommended to support OAuth Dynamic Client Registration (RFC 7591).
Furthermore, `npx mcp-remote` which is the current de-facto client that supports MCP's up-to-date spec,
requires this endpoint to be present.
But, this is an overcomplication for most use cases.
So instead of actually implementing dynamic client registration, we just echo back the pre-registered
client ID and secret.
Use this if you don't need dynamic client registration, or if your OAuth provider doesn't support it.
"""
@app.post(
path,
response_model=ClientRegistrationResponse,
include_in_schema=include_in_schema,
)
async def oauth_register_proxy(request: ClientRegistrationRequest) -> ClientRegistrationResponse:
client_response = ClientRegistrationResponse(
client_name=request.client_name or "MCP Server", # Name doesn't really affect functionality
client_id=client_id,
client_secret=client_secret,
redirect_uris=request.redirect_uris, # Just echo back their requested URIs
grant_types=request.grant_types or ["authorization_code"],
token_endpoint_auth_method=request.token_endpoint_auth_method or "none",
)
return client_response
================================================
FILE: fastapi_mcp/openapi/__init__.py
================================================
================================================
FILE: fastapi_mcp/openapi/convert.py
================================================
import json
import logging
from typing import Any, Dict, List, Tuple
import mcp.types as types
from .utils import (
clean_schema_for_display,
generate_example_from_schema,
resolve_schema_references,
get_single_param_type_from_schema,
)
logger = logging.getLogger(__name__)
def convert_openapi_to_mcp_tools(
openapi_schema: Dict[str, Any],
describe_all_responses: bool = False,
describe_full_response_schema: bool = False,
) -> Tuple[List[types.Tool], Dict[str, Dict[str, Any]]]:
"""
Convert OpenAPI operations to MCP tools.
Args:
openapi_schema: The OpenAPI schema
describe_all_responses: Whether to include all possible response schemas in tool descriptions
describe_full_response_schema: Whether to include full response schema in tool descriptions
Returns:
A tuple containing:
- A list of MCP tools
- A mapping of operation IDs to operation details for HTTP execution
"""
# Resolve all references in the schema at once
resolved_openapi_schema = resolve_schema_references(openapi_schema, openapi_schema)
tools = []
operation_map = {}
# Process each path in the OpenAPI schema
for path, path_item in resolved_openapi_schema.get("paths", {}).items():
for method, operation in path_item.items():
# Skip non-HTTP methods
if method not in ["get", "post", "put", "delete", "patch"]:
logger.warning(f"Skipping non-HTTP method: {method}")
continue
# Get operation metadata
operation_id = operation.get("operationId")
if not operation_id:
logger.warning(f"Skipping operation with no operationId: {operation}")
continue
# Save operation details for later HTTP calls
operation_map[operation_id] = {
"path": path,
"method": method,
"parameters": operation.get("parameters", []),
"request_body": operation.get("requestBody", {}),
}
summary = operation.get("summary", "")
description = operation.get("description", "")
# Build tool description
tool_description = f"{summary}" if summary else f"{method.upper()} {path}"
if description:
tool_description += f"\n\n{description}"
# Add response information to the description
responses = operation.get("responses", {})
if responses:
response_info = "\n\n### Responses:\n"
# Find the success response
success_codes = range(200, 300)
success_response = None
for status_code in success_codes:
if str(status_code) in responses:
success_response = responses[str(status_code)]
break
# Get the list of responses to include
responses_to_include = responses
if not describe_all_responses and success_response:
# If we're not describing all responses, only include the success response
success_code = next((code for code in success_codes if str(code) in responses), None)
if success_code:
responses_to_include = {str(success_code): success_response}
# Process all selected responses
for status_code, response_data in responses_to_include.items():
response_desc = response_data.get("description", "")
response_info += f"\n**{status_code}**: {response_desc}"
# Highlight if this is the main success response
if response_data == success_response:
response_info += " (Success Response)"
# Add schema information if available
if "content" in response_data:
for content_type, content_data in response_data["content"].items():
if "schema" in content_data:
schema = content_data["schema"]
response_info += f"\nContent-Type: {content_type}"
# Clean the schema for display
display_schema = clean_schema_for_display(schema)
# Try to get example response
example_response = None
# Check if content has examples
if "examples" in content_data:
for example_key, example_data in content_data["examples"].items():
if "value" in example_data:
example_response = example_data["value"]
break
# If content has example
elif "example" in content_data:
example_response = content_data["example"]
# If we have an example response, add it to the docs
if example_response:
response_info += "\n\n**Example Response:**\n```json\n"
response_info += json.dumps(example_response, indent=2)
response_info += "\n```"
# Otherwise generate an example from the schema
else:
generated_example = generate_example_from_schema(display_schema)
if generated_example:
response_info += "\n\n**Example Response:**\n```json\n"
response_info += json.dumps(generated_example, indent=2)
response_info += "\n```"
# Only include full schema information if requested
if describe_full_response_schema:
# Format schema information based on its type
if display_schema.get("type") == "array" and "items" in display_schema:
items_schema = display_schema["items"]
response_info += "\n\n**Output Schema:** Array of items with the following structure:\n```json\n"
response_info += json.dumps(items_schema, indent=2)
response_info += "\n```"
elif "properties" in display_schema:
response_info += "\n\n**Output Schema:**\n```json\n"
response_info += json.dumps(display_schema, indent=2)
response_info += "\n```"
else:
response_info += "\n\n**Output Schema:**\n```json\n"
response_info += json.dumps(display_schema, indent=2)
response_info += "\n```"
tool_description += response_info
# Organize parameters by type
path_params = []
query_params = []
header_params = []
body_params = []
for param in operation.get("parameters", []):
param_name = param.get("name")
param_in = param.get("in")
required = param.get("required", False)
if param_in == "path":
path_params.append((param_name, param))
elif param_in == "query":
query_params.append((param_name, param))
elif param_in == "header":
header_params.append((param_name, param))
# Process request body if present
request_body = operation.get("requestBody", {})
if request_body and "content" in request_body:
content_type = next(iter(request_body["content"]), None)
if content_type and "schema" in request_body["content"][content_type]:
schema = request_body["content"][content_type]["schema"]
if "properties" in schema:
for prop_name, prop_schema in schema["properties"].items():
required = prop_name in schema.get("required", [])
body_params.append(
(
prop_name,
{
"name": prop_name,
"schema": prop_schema,
"required": required,
},
)
)
# Create input schema properties for all parameters
properties = {}
required_props = []
# Add path parameters to properties
for param_name, param in path_params:
param_schema = param.get("schema", {})
param_desc = param.get("description", "")
param_required = param.get("required", True) # Path params are usually required
properties[param_name] = param_schema.copy()
properties[param_name]["title"] = param_name
if param_desc:
properties[param_name]["description"] = param_desc
if "type" not in properties[param_name]:
properties[param_name]["type"] = param_schema.get("type", "string")
if param_required:
required_props.append(param_name)
# Add query parameters to properties
for param_name, param in query_params:
param_schema = param.get("schema", {})
param_desc = param.get("description", "")
param_required = param.get("required", False)
properties[param_name] = param_schema.copy()
properties[param_name]["title"] = param_name
if param_desc:
properties[param_name]["description"] = param_desc
if "type" not in properties[param_name]:
properties[param_name]["type"] = get_single_param_type_from_schema(param_schema)
if "default" in param_schema:
properties[param_name]["default"] = param_schema["default"]
if param_required:
required_props.append(param_name)
# Add body parameters to properties
for param_name, param in body_params:
param_schema = param.get("schema", {})
param_desc = param.get("description", "")
param_required = param.get("required", False)
properties[param_name] = param_schema.copy()
properties[param_name]["title"] = param_name
if param_desc:
properties[param_name]["description"] = param_desc
if "type" not in properties[param_name]:
properties[param_name]["type"] = get_single_param_type_from_schema(param_schema)
if "default" in param_schema:
properties[param_name]["default"] = param_schema["default"]
if param_required:
required_props.append(param_name)
# Create a proper input schema for the tool
input_schema = {"type": "object", "properties": properties, "title": f"{operation_id}Arguments"}
if required_props:
input_schema["required"] = required_props
# Create the MCP tool definition
tool = types.Tool(name=operation_id, description=tool_description, inputSchema=input_schema)
tools.append(tool)
return tools, operation_map
================================================
FILE: fastapi_mcp/openapi/utils.py
================================================
from typing import Any, Dict
def get_single_param_type_from_schema(param_schema: Dict[str, Any]) -> str:
"""
Get the type of a parameter from the schema.
If the schema is a union type, return the first type.
"""
if "anyOf" in param_schema:
types = {schema.get("type") for schema in param_schema["anyOf"] if schema.get("type")}
if "null" in types:
types.remove("null")
if types:
return next(iter(types))
return "string"
return param_schema.get("type", "string")
def resolve_schema_references(schema_part: Dict[str, Any], reference_schema: Dict[str, Any]) -> Dict[str, Any]:
"""
Resolve schema references in OpenAPI schemas.
Args:
schema_part: The part of the schema being processed that may contain references
reference_schema: The complete schema used to resolve references from
Returns:
The schema with references resolved
"""
# Make a copy to avoid modifying the input schema
schema_part = schema_part.copy()
# Handle $ref directly in the schema
if "$ref" in schema_part:
ref_path = schema_part["$ref"]
# Standard OpenAPI references are in the format "#/components/schemas/ModelName"
if ref_path.startswith("#/components/schemas/"):
model_name = ref_path.split("/")[-1]
if "components" in reference_schema and "schemas" in reference_schema["components"]:
if model_name in reference_schema["components"]["schemas"]:
# Replace with the resolved schema
ref_schema = reference_schema["components"]["schemas"][model_name].copy()
# Remove the $ref key and merge with the original schema
schema_part.pop("$ref")
schema_part.update(ref_schema)
# Recursively resolve references in all dictionary values
for key, value in schema_part.items():
if isinstance(value, dict):
schema_part[key] = resolve_schema_references(value, reference_schema)
elif isinstance(value, list):
# Only process list items that are dictionaries since only they can contain refs
schema_part[key] = [
resolve_schema_references(item, reference_schema) if isinstance(item, dict) else item for item in value
]
return schema_part
def clean_schema_for_display(schema: Dict[str, Any]) -> Dict[str, Any]:
"""
Clean up a schema for display by removing internal fields.
Args:
schema: The schema to clean
Returns:
The cleaned schema
"""
# Make a copy to avoid modifying the input schema
schema = schema.copy()
# Remove common internal fields that are not helpful for LLMs
fields_to_remove = [
"allOf",
"anyOf",
"oneOf",
"nullable",
"discriminator",
"readOnly",
"writeOnly",
"xml",
"externalDocs",
]
for field in fields_to_remove:
if field in schema:
schema.pop(field)
# Process nested properties
if "properties" in schema:
for prop_name, prop_schema in schema["properties"].items():
if isinstance(prop_schema, dict):
schema["properties"][prop_name] = clean_schema_for_display(prop_schema)
# Process array items
if "type" in schema and schema["type"] == "array" and "items" in schema:
if isinstance(schema["items"], dict):
schema["items"] = clean_schema_for_display(schema["items"])
return schema
def generate_example_from_schema(schema: Dict[str, Any]) -> Any:
"""
Generate a simple example response from a JSON schema.
Args:
schema: The JSON schema to generate an example from
Returns:
An example object based on the schema
"""
if not schema or not isinstance(schema, dict):
return None
# Handle different types
schema_type = schema.get("type")
if schema_type == "object":
result = {}
if "properties" in schema:
for prop_name, prop_schema in schema["properties"].items():
# Generate an example for each property
prop_example = generate_example_from_schema(prop_schema)
if prop_example is not None:
result[prop_name] = prop_example
return result
elif schema_type == "array":
if "items" in schema:
# Generate a single example item
item_example = generate_example_from_schema(schema["items"])
if item_example is not None:
return [item_example]
return []
elif schema_type == "string":
# Check if there's a format
format_type = schema.get("format")
if format_type == "date-time":
return "2023-01-01T00:00:00Z"
elif format_type == "date":
return "2023-01-01"
elif format_type == "email":
return "user@example.com"
elif format_type == "uri":
return "https://example.com"
# Use title or property name if available
return schema.get("title", "string")
elif schema_type == "integer":
return 1
elif schema_type == "number":
return 1.0
elif schema_type == "boolean":
return True
elif schema_type == "null":
return None
# Default case
return None
================================================
FILE: fastapi_mcp/server.py
================================================
import json
import httpx
from typing import Dict, Optional, Any, List, Union, Literal, Sequence
from typing_extensions import Annotated, Doc
from fastapi import FastAPI, Request, APIRouter, params
from fastapi.openapi.utils import get_openapi
from mcp.server.lowlevel.server import Server
import mcp.types as types
from fastapi_mcp.openapi.convert import convert_openapi_to_mcp_tools
from fastapi_mcp.transport.sse import FastApiSseTransport
from fastapi_mcp.transport.http import FastApiHttpSessionManager
from fastapi_mcp.types import HTTPRequestInfo, AuthConfig
import logging
logger = logging.getLogger(__name__)
class FastApiMCP:
"""
Create an MCP server from a FastAPI app.
"""
def __init__(
self,
fastapi: Annotated[
FastAPI,
Doc("The FastAPI application to create an MCP server from"),
],
name: Annotated[
Optional[str],
Doc("Name for the MCP server (defaults to app.title)"),
] = None,
description: Annotated[
Optional[str],
Doc("Description for the MCP server (defaults to app.description)"),
] = None,
describe_all_responses: Annotated[
bool,
Doc("Whether to include all possible response schemas in tool descriptions"),
] = False,
describe_full_response_schema: Annotated[
bool,
Doc("Whether to include full json schema for responses in tool descriptions"),
] = False,
http_client: Annotated[
Optional[httpx.AsyncClient],
Doc(
"""
Optional custom HTTP client to use for API calls to the FastAPI app.
Has to be an instance of `httpx.AsyncClient`.
"""
),
] = None,
include_operations: Annotated[
Optional[List[str]],
Doc("List of operation IDs to include as MCP tools. Cannot be used with exclude_operations."),
] = None,
exclude_operations: Annotated[
Optional[List[str]],
Doc("List of operation IDs to exclude from MCP tools. Cannot be used with include_operations."),
] = None,
include_tags: Annotated[
Optional[List[str]],
Doc("List of tags to include as MCP tools. Cannot be used with exclude_tags."),
] = None,
exclude_tags: Annotated[
Optional[List[str]],
Doc("List of tags to exclude from MCP tools. Cannot be used with include_tags."),
] = None,
auth_config: Annotated[
Optional[AuthConfig],
Doc("Configuration for MCP authentication"),
] = None,
headers: Annotated[
List[str],
Doc(
"""
List of HTTP header names to forward from the incoming MCP request into each tool invocation.
Only headers in this allowlist will be forwarded. Defaults to ['authorization'].
"""
),
] = ["authorization"],
):
# Validate operation and tag filtering options
if include_operations is not None and exclude_operations is not None:
raise ValueError("Cannot specify both include_operations and exclude_operations")
if include_tags is not None and exclude_tags is not None:
raise ValueError("Cannot specify both include_tags and exclude_tags")
self.operation_map: Dict[str, Dict[str, Any]]
self.tools: List[types.Tool]
self.server: Server
self.fastapi = fastapi
self.name = name or self.fastapi.title or "FastAPI MCP"
self.description = description or self.fastapi.description
self._base_url = "http://apiserver"
self._describe_all_responses = describe_all_responses
self._describe_full_response_schema = describe_full_response_schema
self._include_operations = include_operations
self._exclude_operations = exclude_operations
self._include_tags = include_tags
self._exclude_tags = exclude_tags
self._auth_config = auth_config
if self._auth_config:
self._auth_config = self._auth_config.model_validate(self._auth_config)
self._http_client = http_client or httpx.AsyncClient(
transport=httpx.ASGITransport(app=self.fastapi, raise_app_exceptions=False),
base_url=self._base_url,
timeout=10.0,
)
self._forward_headers = {h.lower() for h in headers}
self._http_transport: FastApiHttpSessionManager | None = None # Store reference to HTTP transport for cleanup
self.setup_server()
def setup_server(self) -> None:
openapi_schema = get_openapi(
title=self.fastapi.title,
version=self.fastapi.version,
openapi_version=self.fastapi.openapi_version,
description=self.fastapi.description,
routes=self.fastapi.routes,
)
all_tools, self.operation_map = convert_openapi_to_mcp_tools(
openapi_schema,
describe_all_responses=self._describe_all_responses,
describe_full_response_schema=self._describe_full_response_schema,
)
# Filter tools based on operation IDs and tags
self.tools = self._filter_tools(all_tools, openapi_schema)
mcp_server: Server = Server(self.name, self.description)
@mcp_server.list_tools()
async def handle_list_tools() -> List[types.Tool]:
return self.tools
@mcp_server.call_tool()
async def handle_call_tool(
name: str, arguments: Dict[str, Any]
) -> List[Union[types.TextContent, types.ImageContent, types.EmbeddedResource]]:
# Extract HTTP request info from MCP context
http_request_info = None
try:
# Access the MCP server's request context to get the original HTTP Request
request_context = mcp_server.request_context
if request_context and hasattr(request_context, "request"):
http_request = request_context.request
if http_request and hasattr(http_request, "method"):
http_request_info = HTTPRequestInfo(
method=http_request.method,
path=http_request.url.path,
headers=dict(http_request.headers),
cookies=http_request.cookies,
query_params=dict(http_request.query_params),
body=None,
)
logger.debug(
f"Extracted HTTP request info from context: {http_request_info.method} {http_request_info.path}"
)
except (LookupError, AttributeError) as e:
logger.error(f"Could not extract HTTP request info from context: {e}")
return await self._execute_api_tool(
client=self._http_client,
tool_name=name,
arguments=arguments,
operation_map=self.operation_map,
http_request_info=http_request_info,
)
self.server = mcp_server
def _register_mcp_connection_endpoint_sse(
self,
router: FastAPI | APIRouter,
transport: FastApiSseTransport,
mount_path: str,
dependencies: Optional[Sequence[params.Depends]],
):
@router.get(mount_path, include_in_schema=False, operation_id="mcp_connection", dependencies=dependencies)
async def handle_mcp_connection(request: Request):
async with transport.connect_sse(request.scope, request.receive, request._send) as (reader, writer):
await self.server.run(
reader,
writer,
self.server.create_initialization_options(notification_options=None, experimental_capabilities={}),
raise_exceptions=False,
)
def _register_mcp_messages_endpoint_sse(
self,
router: FastAPI | APIRouter,
transport: FastApiSseTransport,
mount_path: str,
dependencies: Optional[Sequence[params.Depends]],
):
@router.post(
f"{mount_path}/messages/",
include_in_schema=False,
operation_id="mcp_messages",
dependencies=dependencies,
)
async def handle_post_message(request: Request):
return await transport.handle_fastapi_post_message(request)
def _register_mcp_endpoints_sse(
self,
router: FastAPI | APIRouter,
transport: FastApiSseTransport,
mount_path: str,
dependencies: Optional[Sequence[params.Depends]],
):
self._register_mcp_connection_endpoint_sse(router, transport, mount_path, dependencies)
self._register_mcp_messages_endpoint_sse(router, transport, mount_path, dependencies)
def _register_mcp_http_endpoint(
self,
router: FastAPI | APIRouter,
transport: FastApiHttpSessionManager,
mount_path: str,
dependencies: Optional[Sequence[params.Depends]],
):
@router.api_route(
mount_path,
methods=["GET", "POST", "DELETE"],
include_in_schema=False,
operation_id="mcp_http",
dependencies=dependencies,
)
async def handle_mcp_streamable_http(request: Request):
return await transport.handle_fastapi_request(request)
def _register_mcp_endpoints_http(
self,
router: FastAPI | APIRouter,
transport: FastApiHttpSessionManager,
mount_path: str,
dependencies: Optional[Sequence[params.Depends]],
):
self._register_mcp_http_endpoint(router, transport, mount_path, dependencies)
def _setup_auth_2025_03_26(self):
from fastapi_mcp.auth.proxy import (
setup_oauth_custom_metadata,
setup_oauth_metadata_proxy,
setup_oauth_authorize_proxy,
setup_oauth_fake_dynamic_register_endpoint,
)
if self._auth_config:
if self._auth_config.custom_oauth_metadata:
setup_oauth_custom_metadata(
app=self.fastapi,
auth_config=self._auth_config,
metadata=self._auth_config.custom_oauth_metadata,
)
elif self._auth_config.setup_proxies:
assert self._auth_config.client_id is not None
metadata_url = self._auth_config.oauth_metadata_url
if not metadata_url:
metadata_url = f"{self._auth_config.issuer}{self._auth_config.metadata_path}"
setup_oauth_metadata_proxy(
app=self.fastapi,
metadata_url=metadata_url,
path=self._auth_config.metadata_path,
register_path="/oauth/register" if self._auth_config.setup_fake_dynamic_registration else None,
)
setup_oauth_authorize_proxy(
app=self.fastapi,
client_id=self._auth_config.client_id,
authorize_url=self._auth_config.authorize_url,
audience=self._auth_config.audience,
default_scope=self._auth_config.default_scope,
)
if self._auth_config.setup_fake_dynamic_registration:
assert self._auth_config.client_secret is not None
setup_oauth_fake_dynamic_register_endpoint(
app=self.fastapi,
client_id=self._auth_config.client_id,
client_secret=self._auth_config.client_secret,
)
def _setup_auth(self):
if self._auth_config:
if self._auth_config.version == "2025-03-26":
self._setup_auth_2025_03_26()
else:
raise ValueError(
f"Unsupported MCP spec version: {self._auth_config.version}. Please check your AuthConfig."
)
else:
logger.info("No auth config provided, skipping auth setup")
def mount_http(
self,
router: Annotated[
Optional[FastAPI | APIRouter],
Doc(
"""
The FastAPI app or APIRouter to mount the MCP server to. If not provided, the MCP
server will be mounted to the FastAPI app.
"""
),
] = None,
mount_path: Annotated[
str,
Doc(
"""
Path where the MCP server will be mounted.
Mount path is appended to the root path of FastAPI router, or to the prefix of APIRouter.
Defaults to '/mcp'.
"""
),
] = "/mcp",
) -> None:
"""
Mount the MCP server with HTTP transport to **any** FastAPI app or APIRouter.
There is no requirement that the FastAPI app or APIRouter is the same as the one that the MCP
server was created from.
"""
# Normalize mount path
if not mount_path.startswith("/"):
mount_path = f"/{mount_path}"
if mount_path.endswith("/"):
mount_path = mount_path[:-1]
if not router:
router = self.fastapi
assert isinstance(router, (FastAPI, APIRouter)), f"Invalid router type: {type(router)}"
http_transport = FastApiHttpSessionManager(mcp_server=self.server)
dependencies = self._auth_config.dependencies if self._auth_config else None
self._register_mcp_endpoints_http(router, http_transport, mount_path, dependencies)
self._setup_auth()
self._http_transport = http_transport # Store reference
# HACK: If we got a router and not a FastAPI instance, we need to re-include the router so that
# FastAPI will pick up the new routes we added. The problem with this approach is that we assume
# that the router is a sub-router of self.fastapi, which may not always be the case.
#
# TODO: Find a better way to do this.
if isinstance(router, APIRouter):
self.fastapi.include_router(router)
logger.info(f"MCP HTTP server listening at {mount_path}")
def mount_sse(
self,
router: Annotated[
Optional[FastAPI | APIRouter],
Doc(
"""
The FastAPI app or APIRouter to mount the MCP server to. If not provided, the MCP
server will be mounted to the FastAPI app.
"""
),
] = None,
mount_path: Annotated[
str,
Doc(
"""
Path where the MCP server will be mounted.
Mount path is appended to the root path of FastAPI router, or to the prefix of APIRouter.
Defaults to '/sse'.
"""
),
] = "/sse",
) -> None:
"""
Mount the MCP server with SSE transport to **any** FastAPI app or APIRouter.
There is no requirement that the FastAPI app or APIRouter is the same as the one that the MCP
server was created from.
"""
# Normalize mount path
if not mount_path.startswith("/"):
mount_path = f"/{mount_path}"
if mount_path.endswith("/"):
mount_path = mount_path[:-1]
if not router:
router = self.fastapi
# Build the base path correctly for the SSE transport
assert isinstance(router, (FastAPI, APIRouter)), f"Invalid router type: {type(router)}"
base_path = mount_path if isinstance(router, FastAPI) else router.prefix + mount_path
messages_path = f"{base_path}/messages/"
sse_transport = FastApiSseTransport(messages_path)
dependencies = self._auth_config.dependencies if self._auth_config else None
self._register_mcp_endpoints_sse(router, sse_transport, mount_path, dependencies)
self._setup_auth()
# HACK: If we got a router and not a FastAPI instance, we need to re-include the router so that
# FastAPI will pick up the new routes we added. The problem with this approach is that we assume
# that the router is a sub-router of self.fastapi, which may not always be the case.
#
# TODO: Find a better way to do this.
if isinstance(router, APIRouter):
self.fastapi.include_router(router)
logger.info(f"MCP SSE server listening at {mount_path}")
def mount(
self,
router: Annotated[
Optional[FastAPI | APIRouter],
Doc(
"""
The FastAPI app or APIRouter to mount the MCP server to. If not provided, the MCP
server will be mounted to the FastAPI app.
"""
),
] = None,
mount_path: Annotated[
str,
Doc(
"""
Path where the MCP server will be mounted.
Mount path is appended to the root path of FastAPI router, or to the prefix of APIRouter.
Defaults to '/mcp'.
"""
),
] = "/mcp",
transport: Annotated[
Literal["sse"],
Doc(
"""
The transport type for the MCP server. Currently only 'sse' is supported.
This parameter is deprecated.
"""
),
] = "sse",
) -> None:
"""
[DEPRECATED] Mount the MCP server to **any** FastAPI app or APIRouter.
This method is deprecated and will be removed in a future version.
Use mount_http() for HTTP transport (recommended) or mount_sse() for SSE transport instead.
For backwards compatibility, this method defaults to SSE transport.
There is no requirement that the FastAPI app or APIRouter is the same as the one that the MCP
server was created from.
"""
import warnings
warnings.warn(
"mount() is deprecated and will be removed in a future version. "
"Use mount_http() for HTTP transport (recommended) or mount_sse() for SSE transport instead.",
DeprecationWarning,
stacklevel=2,
)
if transport == "sse":
self.mount_sse(router, mount_path)
else: # pragma: no cover
raise ValueError( # pragma: no cover
f"Unsupported transport: {transport}. Use mount_sse() or mount_http() instead."
)
async def _execute_api_tool(
self,
client: Annotated[httpx.AsyncClient, Doc("httpx client to use in API calls")],
tool_name: Annotated[str, Doc("The name of the tool to execute")],
arguments: Annotated[Dict[str, Any], Doc("The arguments for the tool")],
operation_map: Annotated[Dict[str, Dict[str, Any]], Doc("A mapping from tool names to operation details")],
http_request_info: Annotated[
Optional[HTTPRequestInfo],
Doc("HTTP request info to forward to the actual API call"),
] = None,
) -> List[Union[types.TextContent, types.ImageContent, types.EmbeddedResource]]:
"""
Execute an MCP tool by making an HTTP request to the corresponding API endpoint.
Returns:
The result as MCP content types
"""
if tool_name not in operation_map:
raise Exception(f"Unknown tool: {tool_name}")
operation = operation_map[tool_name]
path: str = operation["path"]
method: str = operation["method"]
parameters: List[Dict[str, Any]] = operation.get("parameters", [])
arguments = arguments.copy() if arguments else {} # Deep copy arguments to avoid mutating the original
for param in parameters:
if param.get("in") == "path" and param.get("name") in arguments:
param_name = param.get("name", None)
if param_name is None:
raise ValueError(f"Parameter name is None for parameter: {param}")
path = path.replace(f"{{{param_name}}}", str(arguments.pop(param_name)))
query = {}
for param in parameters:
if param.get("in") == "query" and param.get("name") in arguments:
param_name = param.get("name", None)
if param_name is None:
raise ValueError(f"Parameter name is None for parameter: {param}")
query[param_name] = arguments.pop(param_name)
headers = {}
for param in parameters:
if param.get("in") == "header" and param.get("name") in arguments:
param_name = param.get("name", None)
if param_name is None:
raise ValueError(f"Parameter name is None for parameter: {param}")
headers[param_name] = arguments.pop(param_name)
# Forward headers that are in the allowlist
if http_request_info and http_request_info.headers:
for name, value in http_request_info.headers.items():
# case-insensitive check for allowed headers
if name.lower() in self._forward_headers:
headers[name] = value
body = arguments if arguments else None
try:
logger.debug(f"Making {method.upper()} request to {path}")
response = await self._request(client, method, path, query, headers, body)
# TODO: Better typing for the AsyncClientProtocol. It should return a ResponseProtocol that has a json() method that returns a dict/list/etc.
try:
result = response.json()
result_text = json.dumps(result, indent=2, ensure_ascii=False)
except json.JSONDecodeError:
if hasattr(response, "text"):
result_text = response.text
else:
result_text = response.content
# If not raising an exception, the MCP server will return the result as a regular text response, without marking it as an error.
# TODO: Use a raise_for_status() method on the response (it needs to also be implemented in the AsyncClientProtocol)
if 400 <= response.status_code < 600:
raise Exception(
f"Error calling {tool_name}. Status code: {response.status_code}. Response: {response.text}"
)
try:
return [types.TextContent(type="text", text=result_text)]
except ValueError:
return [types.TextContent(type="text", text=result_text)]
except Exception as e:
logger.exception(f"Error calling {tool_name}")
raise e
async def _request(
self,
client: httpx.AsyncClient,
method: str,
path: str,
query: Dict[str, Any],
headers: Dict[str, str],
body: Optional[Any],
) -> Any:
if method.lower() == "get":
return await client.get(path, params=query, headers=headers)
elif method.lower() == "post":
return await client.post(path, params=query, headers=headers, json=body)
elif method.lower() == "put":
return await client.put(path, params=query, headers=headers, json=body)
elif method.lower() == "delete":
return await client.delete(path, params=query, headers=headers)
elif method.lower() == "patch":
return await client.patch(path, params=query, headers=headers, json=body)
else:
raise ValueError(f"Unsupported HTTP method: {method}")
def _filter_tools(self, tools: List[types.Tool], openapi_schema: Dict[str, Any]) -> List[types.Tool]:
"""
Filter tools based on operation IDs and tags.
Args:
tools: List of tools to filter
openapi_schema: The OpenAPI schema
Returns:
Filtered list of tools
"""
if (
self._include_operations is None
and self._exclude_operations is None
and self._include_tags is None
and self._exclude_tags is None
):
return tools
operations_by_tag: Dict[str, List[str]] = {}
for path, path_item in openapi_schema.get("paths", {}).items():
for method, operation in path_item.items():
if method not in ["get", "post", "put", "delete", "patch"]:
continue
operation_id = operation.get("operationId")
if not operation_id:
continue
tags = operation.get("tags", [])
for tag in tags:
if tag not in operations_by_tag:
operations_by_tag[tag] = []
operations_by_tag[tag].append(operation_id)
operations_to_include = set()
if self._include_operations is not None:
operations_to_include.update(self._include_operations)
elif self._exclude_operations is not None:
all_operations = {tool.name for tool in tools}
operations_to_include.update(all_operations - set(self._exclude_operations))
if self._include_tags is not None:
for tag in self._include_tags:
operations_to_include.update(operations_by_tag.get(tag, []))
elif self._exclude_tags is not None:
excluded_operations = set()
for tag in self._exclude_tags:
excluded_operations.update(operations_by_tag.get(tag, []))
all_operations = {tool.name for tool in tools}
operations_to_include.update(all_operations - excluded_operations)
filtered_tools = [tool for tool in tools if tool.name in operations_to_include]
if filtered_tools:
filtered_operation_ids = {tool.name for tool in filtered_tools}
self.operation_map = {
op_id: details for op_id, details in self.operation_map.items() if op_id in filtered_operation_ids
}
return filtered_tools
================================================
FILE: fastapi_mcp/transport/__init__.py
================================================
================================================
FILE: fastapi_mcp/transport/http.py
================================================
import logging
import asyncio
from fastapi import Request, Response, HTTPException
from mcp.server.lowlevel.server import Server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager, EventStore
from mcp.server.transport_security import TransportSecuritySettings
logger = logging.getLogger(__name__)
class FastApiHttpSessionManager:
"""
FastAPI-native wrapper around StreamableHTTPSessionManager
"""
def __init__(
self,
mcp_server: Server,
event_store: EventStore | None = None,
json_response: bool = True, # Default to JSON for HTTP transport
security_settings: TransportSecuritySettings | None = None,
):
self.mcp_server = mcp_server
self.event_store = event_store
self.json_response = json_response
self.security_settings = security_settings
self._session_manager: StreamableHTTPSessionManager | None = None
self._manager_task: asyncio.Task | None = None
self._manager_started = False
self._startup_lock = asyncio.Lock()
async def _ensure_session_manager_started(self) -> None:
"""
Ensure the session manager is started.
This is called lazily on the first request to start the session manager
if it hasn't been started yet.
"""
if self._manager_started:
return
async with self._startup_lock:
if self._manager_started:
return
logger.debug("Starting StreamableHTTP session manager")
# Create the session manager
# Note: We don't use stateless=True because we want to support sessions
# but sessions are optional as per the MCP spec
self._session_manager = StreamableHTTPSessionManager(
app=self.mcp_server,
event_store=self.event_store,
json_response=self.json_response,
stateless=False, # Always support sessions, but they're optional
security_settings=self.security_settings,
)
# Start the session manager in a background task
async def run_session_manager():
try:
async with self._session_manager.run():
logger.info("StreamableHTTP session manager is running")
# Keep running until cancelled
await asyncio.Event().wait()
except asyncio.CancelledError:
logger.info("StreamableHTTP session manager is shutting down")
raise
except Exception:
logger.exception("Error in StreamableHTTP session manager")
raise
self._manager_task = asyncio.create_task(run_session_manager())
self._manager_started = True
# Give the session manager a moment to initialize
await asyncio.sleep(0.1)
async def handle_fastapi_request(self, request: Request) -> Response:
"""
Handle a FastAPI request by delegating to the session manager.
This converts FastAPI's Request/Response to ASGI scope/receive/send
and then converts the result back to a FastAPI Response.
"""
# Ensure session manager is started
await self._ensure_session_manager_started()
if not self._session_manager:
raise HTTPException(status_code=500, detail="Session manager not initialized")
logger.debug(f"Handling FastAPI request: {request.method} {request.url.path}")
# Capture the response from the session manager
response_started = False
response_status = 200
response_headers = []
response_body = b""
async def send_callback(message):
nonlocal response_started, response_status, response_headers, response_body
if message["type"] == "http.response.start":
response_started = True
response_status = message["status"]
response_headers = message.get("headers", [])
elif message["type"] == "http.response.body":
response_body += message.get("body", b"")
try:
# Delegate to the session manager's handle_request method
await self._session_manager.handle_request(request.scope, request.receive, send_callback)
# Convert the captured ASGI response to a FastAPI Response
headers_dict = {name.decode(): value.decode() for name, value in response_headers}
return Response(
content=response_body,
status_code=response_status,
headers=headers_dict,
)
except Exception:
logger.exception("Error in StreamableHTTPSessionManager")
raise HTTPException(status_code=500, detail="Internal server error")
async def shutdown(self) -> None:
"""Clean up the session manager and background task."""
if self._manager_task and not self._manager_task.done():
self._manager_task.cancel()
try:
await self._manager_task
except asyncio.CancelledError:
pass
self._manager_started = False
================================================
FILE: fastapi_mcp/transport/sse.py
================================================
from uuid import UUID
import logging
from typing import Union
from anyio.streams.memory import MemoryObjectSendStream
from fastapi import Request, Response, BackgroundTasks, HTTPException
from fastapi.responses import JSONResponse
from mcp.shared.message import SessionMessage, ServerMessageMetadata
from pydantic import ValidationError
from mcp.server.sse import SseServerTransport
from mcp.types import JSONRPCMessage, JSONRPCError, ErrorData
logger = logging.getLogger(__name__)
class FastApiSseTransport(SseServerTransport):
async def handle_fastapi_post_message(self, request: Request) -> Response:
"""
A reimplementation of the handle_post_message method of SseServerTransport
that integrates better with FastAPI.
A few good reasons for doing this:
1. Avoid mounting a whole Starlette app and instead use a more FastAPI-native
approach. Mounting has some known issues and limitations.
2. Avoid re-constructing the scope, receive, and send from the request, as done
in the original implementation.
3. Use FastAPI's native response handling mechanisms and exception patterns to
avoid unexpected rabbit holes.
The combination of mounting a whole Starlette app and reconstructing the scope
and send from the request proved to be especially error-prone for us when using
tracing tools like Sentry, which had destructive effects on the request object
when using the original implementation.
"""
logger.debug("Handling POST message SSE")
session_id_param = request.query_params.get("session_id")
if session_id_param is None:
logger.warning("Received request without session_id")
raise HTTPException(status_code=400, detail="session_id is required")
try:
session_id = UUID(hex=session_id_param)
logger.debug(f"Parsed session ID: {session_id}")
except ValueError:
logger.warning(f"Received invalid session ID: {session_id_param}")
raise HTTPException(status_code=400, detail="Invalid session ID")
writer = self._read_stream_writers.get(session_id)
if not writer:
logger.warning(f"Could not find session for ID: {session_id}")
raise HTTPException(status_code=404, detail="Could not find session")
body = await request.body()
logger.debug(f"Received JSON: {body.decode()}")
try:
message = JSONRPCMessage.model_validate_json(body)
logger.debug(f"Validated client message: {message}")
except ValidationError as err:
logger.error(f"Failed to parse message: {err}")
# Create background task to send error
background_tasks = BackgroundTasks()
background_tasks.add_task(self._send_message_safely, writer, err)
response = JSONResponse(content={"error": "Could not parse message"}, status_code=400)
response.background = background_tasks
return response
except Exception as e:
logger.error(f"Error processing request body: {e}")
raise HTTPException(status_code=400, detail="Invalid request body")
# Create background task to send message with proper request context metadata
background_tasks = BackgroundTasks()
metadata = ServerMessageMetadata(request_context=request)
session_message = SessionMessage(message, metadata=metadata)
background_tasks.add_task(self._send_message_safely, writer, session_message)
logger.debug("Accepting message, will send in background")
# Return response with background task
response = JSONResponse(content={"message": "Accepted"}, status_code=202)
response.background = background_tasks
return response
async def _send_message_safely(
self, writer: MemoryObjectSendStream[SessionMessage], message: Union[SessionMessage, ValidationError]
):
"""Send a message to the writer, avoiding ASGI race conditions"""
try:
logger.debug(f"Sending message to writer from background task: {message}")
if isinstance(message, ValidationError):
# Convert ValidationError to JSONRPCError
error_data = ErrorData(
code=-32700, # Parse error code in JSON-RPC
message="Parse error",
data={"validation_error": str(message)},
)
json_rpc_error = JSONRPCError(
jsonrpc="2.0",
id="unknown", # We don't know the ID from the invalid request
error=error_data,
)
error_message = SessionMessage(JSONRPCMessage(root=json_rpc_error))
await writer.send(error_message)
else:
await writer.send(message)
except Exception as e:
logger.error(f"Error sending message to writer: {e}")
================================================
FILE: fastapi_mcp/types.py
================================================
import time
from typing import Any, Dict, Annotated, Union, Optional, Sequence, Literal, List
from typing_extensions import Doc
from pydantic import (
BaseModel,
ConfigDict,
HttpUrl,
field_validator,
model_validator,
)
from pydantic.main import IncEx
from fastapi import params
StrHttpUrl = Annotated[Union[str, HttpUrl], HttpUrl]
class BaseType(BaseModel):
model_config = ConfigDict(extra="ignore", arbitrary_types_allowed=True)
class HTTPRequestInfo(BaseType):
method: str
path: str
headers: Dict[str, str]
cookies: Dict[str, str]
query_params: Dict[str, str]
body: Any
class OAuthMetadata(BaseType):
"""OAuth 2.0 Server Metadata according to RFC 8414"""
issuer: Annotated[
StrHttpUrl,
Doc(
"""
The authorization server's issuer identifier, which is a URL that uses the https scheme.
"""
),
]
authorization_endpoint: Annotated[
Optional[StrHttpUrl],
Doc(
"""
URL of the authorization server's authorization endpoint.
"""
),
] = None
token_endpoint: Annotated[
StrHttpUrl,
Doc(
"""
URL of the authorization server's token endpoint.
"""
),
]
scopes_supported: Annotated[
List[str],
Doc(
"""
List of OAuth 2.0 scopes that the authorization server supports.
"""
),
] = ["openid", "profile", "email"]
response_types_supported: Annotated[
List[str],
Doc(
"""
List of the OAuth 2.0 response_type values that the authorization server supports.
"""
),
] = ["code"]
grant_types_supported: Annotated[
List[str],
Doc(
"""
List of the OAuth 2.0 grant type values that the authorization server supports.
"""
),
] = ["authorization_code", "client_credentials"]
token_endpoint_auth_methods_supported: Annotated[
List[str],
Doc(
"""
List of client authentication methods supported by the token endpoint.
"""
),
] = ["none"]
code_challenge_methods_supported: Annotated[
List[str],
Doc(
"""
List of PKCE code challenge methods supported by the authorization server.
"""
),
] = ["S256"]
registration_endpoint: Annotated[
Optional[StrHttpUrl],
Doc(
"""
URL of the authorization server's client registration endpoint.
"""
),
] = None
@field_validator(
"scopes_supported",
"response_types_supported",
"grant_types_supported",
"token_endpoint_auth_methods_supported",
"code_challenge_methods_supported",
)
@classmethod
def validate_non_empty_lists(cls, v, info):
if not v:
raise ValueError(f"{info.field_name} cannot be empty")
return v
@model_validator(mode="after")
def validate_endpoints_for_grant_types(self):
if "authorization_code" in self.grant_types_supported and not self.authorization_endpoint:
raise ValueError("authorization_endpoint is required when authorization_code grant type is supported")
return self
def model_dump(
self,
*,
mode: Literal["json", "python"] | str = "python",
include: IncEx | None = None,
exclude: IncEx | None = None,
context: Any | None = None,
by_alias: bool = False,
exclude_unset: bool = True,
exclude_defaults: bool = False,
exclude_none: bool = True,
round_trip: bool = False,
warnings: bool | Literal["none", "warn", "error"] = True,
serialize_as_any: bool = False,
) -> dict[str, Any]:
# Always exclude unset and None fields, since clients don't take it well when
# OAuth metadata fields are present but empty.
exclude_unset = True
exclude_none = True
return super().model_dump(
mode=mode,
include=include,
exclude=exclude,
context=context,
by_alias=by_alias,
exclude_unset=exclude_unset,
exclude_defaults=exclude_defaults,
exclude_none=exclude_none,
round_trip=round_trip,
warnings=warnings,
serialize_as_any=serialize_as_any,
)
OAuthMetadataDict = Annotated[Union[Dict[str, Any], OAuthMetadata], OAuthMetadata]
class AuthConfig(BaseType):
version: Annotated[
Literal["2025-03-26"],
Doc(
"""
The MCP spec version to use for setting up authorization.
Currently only "2025-03-26" is supported.
"""
),
] = "2025-03-26"
dependencies: Annotated[
Optional[Sequence[params.Depends]],
Doc(
"""
FastAPI dependencies (using `Depends()`) that check for authentication or authorization
and raise 401 or 403 errors if the request is not authenticated or authorized.
This is necessary to trigger the client to start an OAuth flow.
Example:
```python
# Your authentication dependency
async def authenticate_request(request: Request, token: str = Depends(oauth2_scheme)):
payload = verify_token(request, token)
if payload is None:
raise HTTPException(status_code=401, detail="Unauthorized")
return payload
# Usage with FastAPI-MCP
mcp = FastApiMCP(
app,
auth_config=AuthConfig(dependencies=[Depends(authenticate_request)]),
)
```
"""
),
] = None
issuer: Annotated[
Optional[str],
Doc(
"""
The issuer of the OAuth 2.0 server.
Required if you don't provide `custom_oauth_metadata`.
Usually it's either the base URL of your app, or the URL of the OAuth provider.
For example, for Auth0, this would be `https://your-tenant.auth0.com`.
"""
),
] = None
oauth_metadata_url: Annotated[
Optional[StrHttpUrl],
Doc(
"""
The full URL of the OAuth provider's metadata endpoint.
If not provided, FastAPI-MCP will attempt to guess based on the `issuer` and `metadata_path`.
Only relevant if `setup_proxies` is `True`.
If this URL is wrong, the metadata proxy will not work.
"""
),
] = None
authorize_url: Annotated[
Optional[StrHttpUrl],
Doc(
"""
The URL of your OAuth provider's authorization endpoint.
Usually this is something like `https://app.example.com/oauth/authorize`.
"""
),
] = None
audience: Annotated[
Optional[str],
Doc(
"""
Currently (2025-04-21), some Auth-supporting MCP clients (like `npx mcp-remote`) might not specify the
audience when sending a request to your server.
This may cause unexpected behavior from your OAuth provider, so this is a workaround.
In case the client doesn't specify an audience, this will be used as the default audience on the
request to your OAuth provider.
"""
),
] = None
default_scope: Annotated[
str,
Doc(
"""
Currently (2025-04-21), some Auth-supporting MCP clients (like `npx mcp-remote`) might not specify the
scope when sending a request to your server.
This may cause unexpected behavior from your OAuth provider, so this is a workaround.
Here is where you can optionally specify a default scope that will be sent to your OAuth provider in case
the client doesn't specify it.
"""
),
] = "openid profile email"
client_id: Annotated[
Optional[str],
Doc(
"""
In case the client doesn't specify a client ID, this will be used as the default client ID on the
request to your OAuth provider.
This is mandatory only if you set `setup_proxies` to `True`.
"""
),
] = None
client_secret: Annotated[
Optional[str],
Doc(
"""
The client secret to use for the client ID.
This is mandatory only if you set `setup_proxies` to `True` and `setup_fake_dynamic_registration` to `True`.
"""
),
] = None
custom_oauth_metadata: Annotated[
Optional[OAuthMetadataDict],
Doc(
"""
Custom OAuth metadata to register.
If your OAuth flow works with MCP out-of-the-box, you should just use this option to provide the
metadata yourself.
Otherwise, set `setup_proxies` to `True` to automatically setup MCP-compliant proxies around your
OAuth provider's endpoints.
"""
),
] = None
setup_proxies: Annotated[
bool,
Doc(
"""
Whether to automatically setup MCP-compliant proxies around your original OAuth provider's endpoints.
"""
),
] = False
setup_fake_dynamic_registration: Annotated[
bool,
Doc(
"""
Whether to automatically setup a fake dynamic client registration endpoint.
In MCP 2025-03-26 Spec, it is recommended to support OAuth Dynamic Client Registration (RFC 7591).
Furthermore, `npx mcp-remote` which is the current de-facto client that supports MCP's up-to-date spec,
requires this endpoint to be present.
For most cases, a fake dynamic registration endpoint is enough, thus you should set this to `True`.
This is only used if `setup_proxies` is also `True`.
"""
),
] = True
metadata_path: Annotated[
str,
Doc(
"""
The path to mount the OAuth metadata endpoint at.
Clients will usually expect this to be /.well-known/oauth-authorization-server
"""
),
] = "/.well-known/oauth-authorization-server"
@model_validator(mode="after")
def validate_required_fields(self):
if self.custom_oauth_metadata is None and self.issuer is None and not self.dependencies:
raise ValueError("at least one of 'issuer', 'custom_oauth_metadata' or 'dependencies' is required")
if self.setup_proxies:
if self.client_id is None:
raise ValueError("'client_id' is required when 'setup_proxies' is True")
if self.setup_fake_dynamic_registration and not self.client_secret:
raise ValueError("'client_secret' is required when 'setup_fake_dynamic_registration' is True")
return self
class ClientRegistrationRequest(BaseType):
redirect_uris: List[str]
client_name: Optional[str] = None
grant_types: Optional[List[str]] = ["authorization_code"]
token_endpoint_auth_method: Optional[str] = "none"
class ClientRegistrationResponse(BaseType):
client_id: str
client_id_issued_at: int = int(time.time())
client_secret: Optional[str] = None
client_secret_expires_at: int = 0
redirect_uris: List[str]
grant_types: List[str]
token_endpoint_auth_method: str
client_name: str
================================================
FILE: fastapi_mcp/utils/__init__.py
================================================
================================================
FILE: mypy.ini
================================================
[mypy]
================================================
FILE: pyproject.toml
================================================
[build-system]
requires = ["hatchling", "tomli"]
build-backend = "hatchling.build"
[project]
name = "fastapi-mcp"
version = "0.4.0"
description = "Automatic MCP server generator for FastAPI applications - converts FastAPI endpoints to MCP tools for LLM integration"
readme = "README.md"
requires-python = ">=3.10"
license = {file = "LICENSE"}
authors = [
{name = "Tadata Inc.", email = "itay@tadata.com"},
]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Topic :: Software Development :: Libraries :: Python Modules",
"Topic :: Internet :: WWW/HTTP",
"Framework :: FastAPI",
]
keywords = ["fastapi", "openapi", "mcp", "llm", "claude", "ai", "tools", "api", "conversion", "modelcontextprotocol"]
dependencies = [
"fastapi>=0.100.0",
"typer>=0.9.0",
"rich>=13.0.0",
"mcp>=1.12.0",
"pydantic>=2.0.0",
"pydantic-settings>=2.5.2",
"uvicorn>=0.20.0",
"httpx>=0.24.0",
"requests>=2.25.0",
"tomli>=2.2.1",
]
[dependency-groups]
dev = [
"mypy>=1.15.0",
"ruff>=0.9.10",
"types-setuptools>=75.8.2.20250305",
"pytest>=8.3.5",
"pytest-asyncio>=0.26.0",
"pytest-cov>=6.1.1",
"pre-commit>=4.2.0",
"pyjwt>=2.10.1",
"cryptography>=44.0.2",
"types-jsonschema>=4.25.0.20250720",
]
[project.urls]
Homepage = "https://github.com/tadata-org/fastapi_mcp"
Documentation = "https://github.com/tadata-org/fastapi_mcp#readme"
"Bug Tracker" = "https://github.com/tadata-org/fastapi_mcp/issues"
"PyPI" = "https://pypi.org/project/fastapi-mcp/"
"Source Code" = "https://github.com/tadata-org/fastapi_mcp"
"Changelog" = "https://github.com/tadata-org/fastapi_mcp/blob/main/CHANGELOG.md"
[tool.hatch.build.targets.wheel]
packages = ["fastapi_mcp"]
[tool.ruff]
line-length = 120
target-version = "py312"
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
python_files = "test_*.py"
================================================
FILE: pytest.ini
================================================
[pytest]
addopts = -vvv --cov=. --cov-report xml --cov-report term-missing --cov-fail-under=80 --cov-config=.coveragerc
asyncio_mode = auto
log_cli = true
log_cli_level = DEBUG
log_cli_format = %(asctime)s - %(name)s - %(levelname)s - %(message)s
================================================
FILE: tests/__init__.py
================================================
================================================
FILE: tests/conftest.py
================================================
import sys
import os
import pytest
import coverage
# Add the parent directory to the path
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
from .fixtures.types import * # noqa: F403
from .fixtures.example_data import * # noqa: F403
from .fixtures.simple_app import * # noqa: F403
from .fixtures.complex_app import * # noqa: F403
@pytest.hookimpl(trylast=True)
def pytest_configure(config):
"""Configure pytest-cov for proper subprocess coverage."""
if config.pluginmanager.hasplugin("pytest_cov"):
# Ensure environment variables are set for subprocess coverage
os.environ["COVERAGE_PROCESS_START"] = os.path.abspath(".coveragerc")
# Set up environment for combinining coverage data from subprocesses
os.environ["PYTHONPATH"] = os.path.abspath(".")
# Make sure the pytest-cov plugin is active for subprocesses
config.option.cov_fail_under = 0 # Disable fail under in the primary process
@pytest.hookimpl(trylast=True)
def pytest_sessionfinish(session, exitstatus):
"""Combine coverage data from subprocesses at the end of the test session."""
cov_dir = os.path.abspath(".")
if exitstatus == 0 and os.environ.get("COVERAGE_PROCESS_START"):
try:
cov = coverage.Coverage()
cov.combine(data_paths=[cov_dir], strict=True)
cov.save()
except Exception as e:
print(f"Error combining coverage data: {e}", file=sys.stderr)
================================================
FILE: tests/fixtures/complex_app.py
================================================
from typing import Optional, List, Dict, Any, Union
from uuid import UUID
from fastapi import FastAPI, Query, Path, Body, Header, Cookie
import pytest
from tests.fixtures.conftest import make_fastapi_app_base
from .types import (
Product,
Customer,
OrderResponse,
PaginatedResponse,
ProductCategory,
OrderRequest,
ErrorResponse,
)
def make_complex_fastapi_app(
example_product: Product,
example_customer: Customer,
example_order_response: OrderResponse,
parametrized_config: dict[str, Any] | None = None,
) -> FastAPI:
app = make_fastapi_app_base(parametrized_config=parametrized_config)
@app.get(
"/products",
response_model=PaginatedResponse,
tags=["products"],
operation_id="list_products",
response_model_exclude_none=True,
)
async def list_products(
category: Optional[ProductCategory] = Query(None, description="Filter by product category"),
min_price: Optional[float] = Query(None, description="Minimum price filter", gt=0),
max_price: Optional[float] = Query(None, description="Maximum price filter", gt=0),
tag: Optional[List[str]] = Query(None, description="Filter by tags"),
sort_by: str = Query("created_at", description="Field to sort by"),
sort_direction: str = Query("desc", description="Sort direction (asc or desc)"),
in_stock_only: bool = Query(False, description="Show only in-stock products"),
page: int = Query(1, description="Page number", ge=1),
size: int = Query(20, description="Page size", ge=1, le=100),
user_agent: Optional[str] = Header(None, description="User agent header"),
):
"""
List products with various filtering, sorting and pagination options.
Returns a paginated response of products.
"""
return PaginatedResponse(items=[example_product], total=1, page=page, size=size, pages=1)
@app.get(
"/products/{product_id}",
response_model=Product,
tags=["products"],
operation_id="get_product",
responses={
404: {"model": ErrorResponse, "description": "Product not found"},
},
)
async def get_product(
product_id: UUID = Path(..., description="The ID of the product to retrieve"),
include_unavailable: bool = Query(False, description="Include product even if not available"),
):
"""
Get detailed information about a specific product by its ID.
Includes all variants, images, and metadata.
"""
# Just returning the example product with the requested ID
product_copy = example_product.model_copy()
product_copy.id = product_id
return product_copy
@app.post(
"/orders",
response_model=OrderResponse,
tags=["orders"],
operation_id="create_order",
status_code=201,
responses={
400: {"model": ErrorResponse, "description": "Invalid order data"},
404: {"model": ErrorResponse, "description": "Customer or product not found"},
422: {"model": ErrorResponse, "description": "Validation error"},
},
)
async def create_order(
order: OrderRequest = Body(..., description="Order details"),
user_id: Optional[UUID] = Cookie(None, description="User ID from cookie"),
authorization: Optional[str] = Header(None, description="Authorization header"),
):
"""
Create a new order with multiple items, shipping details, and payment information.
Returns the created order with full details including status and tracking information.
"""
# Return a copy of the example order response with the customer ID from the request
order_copy = example_order_response.model_copy()
order_copy.customer_id = order.customer_id
order_copy.items = order.items
return order_copy
@app.get(
"/customers/{customer_id}",
response_model=Union[Customer, Dict[str, Any]],
tags=["customers"],
operation_id="get_customer",
responses={
404: {"model": ErrorResponse, "description": "Customer not found"},
403: {"model": ErrorResponse, "description": "Forbidden access"},
},
)
async def get_customer(
customer_id: UUID = Path(..., description="The ID of the customer to retrieve"),
include_orders: bool = Query(False, description="Include customer's order history"),
include_payment_methods: bool = Query(False, description="Include customer's saved payment methods"),
fields: List[str] = Query(None, description="Specific fields to include in response"),
):
"""
Get detailed information about a specific customer by ID.
Can include additional related information like order history.
"""
# Return a copy of the example customer with the requested ID
customer_copy = example_customer.model_copy()
customer_copy.id = customer_id
return customer_copy
return app
@pytest.fixture
def complex_fastapi_app(
example_product: Product,
example_customer: Customer,
example_order_response: OrderResponse,
) -> FastAPI:
return make_complex_fastapi_app(
example_product=example_product,
example_customer=example_customer,
example_order_response=example_order_response,
)
================================================
FILE: tests/fixtures/conftest.py
================================================
from typing import Any
from fastapi import FastAPI
def make_fastapi_app_base(parametrized_config: dict[str, Any] | None = None) -> FastAPI:
fastapi_config: dict[str, Any] = {
"title": "Test API",
"description": "A test API app for unit testing",
"version": "0.1.0",
}
app = FastAPI(**fastapi_config | parametrized_config if parametrized_config is not None else {})
return app
================================================
FILE: tests/fixtures/example_data.py
================================================
from datetime import datetime, date
from uuid import UUID
import pytest
from .types import (
Address,
ProductVariant,
Product,
ProductCategory,
Customer,
CustomerTier,
OrderItem,
PaymentDetails,
OrderRequest,
OrderResponse,
PaginatedResponse,
OrderStatus,
PaymentMethod,
)
@pytest.fixture
def example_address() -> Address:
return Address(street="123 Main St", city="Anytown", state="CA", postal_code="12345", country="US", is_primary=True)
@pytest.fixture
def example_product_variant() -> ProductVariant:
return ProductVariant(
sku="EP-001-BLK", color="Black", stock_count=10, size=None, weight=None, dimensions=None, in_stock=True
)
@pytest.fixture
def example_product(example_product_variant) -> Product:
return Product(
id=UUID("550e8400-e29b-41d4-a716-446655440000"),
name="Example Product",
description="This is an example product",
category=ProductCategory.ELECTRONICS,
price=199.99,
discount_percent=None,
tax_rate=None,
rating=None,
review_count=0,
tags=["example", "new"],
image_urls=["https://example.com/image.jpg"],
created_at=datetime.now(),
variants=[example_product_variant],
)
@pytest.fixture
def example_customer(example_address) -> Customer:
return Customer(
id=UUID("770f9511-f39c-42d5-a860-557654551222"),
email="customer@example.com",
full_name="John Doe",
phone="1234567890",
tier=CustomerTier.STANDARD,
addresses=[example_address],
created_at=datetime.now(),
preferences={"theme": "dark", "notifications": True},
consent={"marketing": True, "analytics": True},
)
@pytest.fixture
def example_order_item() -> OrderItem:
return OrderItem(
product_id=UUID("550e8400-e29b-41d4-a716-446655440000"),
variant_sku="EP-001-BLK",
quantity=2,
unit_price=199.99,
discount_amount=10.00,
total=389.98,
)
@pytest.fixture
def example_payment_details() -> PaymentDetails:
return PaymentDetails(
method=PaymentMethod.CREDIT_CARD,
transaction_id="txn_12345",
status="completed",
amount=389.98,
currency="USD",
paid_at=datetime.now(),
)
@pytest.fixture
def example_order_request(example_order_item) -> OrderRequest:
return OrderRequest(
customer_id=UUID("770f9511-f39c-42d5-a860-557654551222"),
items=[example_order_item],
shipping_address_id=UUID("880f9511-f39c-42d5-a860-557654551333"),
billing_address_id=None,
payment_method=PaymentMethod.CREDIT_CARD,
notes="Please deliver before 6pm",
use_loyalty_points=False,
)
@pytest.fixture
def example_order_response(example_order_item, example_address, example_payment_details) -> OrderResponse:
return OrderResponse(
id=UUID("660f9511-f39c-42d5-a860-557654551111"),
customer_id=UUID("770f9511-f39c-42d5-a860-557654551222"),
status=OrderStatus.PENDING,
items=[example_order_item],
shipping_address=example_address,
billing_address=example_address,
payment=example_payment_details,
subtotal=389.98,
shipping_cost=10.0,
tax_amount=20.0,
discount_amount=10.0,
total_amount=409.98,
tracking_number="TRK123456789",
estimated_delivery=date.today(),
created_at=datetime.now(),
notes="Please deliver before 6pm",
metadata={},
)
@pytest.fixture
def example_paginated_products(example_product) -> PaginatedResponse:
return PaginatedResponse(items=[example_product], total=1, page=1, size=20, pages=1)
================================================
FILE: tests/fixtures/simple_app.py
================================================
from typing import Optional, List, Any
from fastapi import FastAPI, Query, Path, Body, HTTPException
import pytest
from tests.fixtures.conftest import make_fastapi_app_base
from .types import Item
def make_simple_fastapi_app(parametrized_config: dict[str, Any] | None = None) -> FastAPI:
app = make_fastapi_app_base(parametrized_config=parametrized_config)
items = [
Item(id=1, name="Item 1", price=10.0, tags=["tag1", "tag2"], description="Item 1 description"),
Item(id=2, name="Item 2", price=20.0, tags=["tag2", "tag3"]),
Item(id=3, name="Item 3", price=30.0, tags=["tag3", "tag4"], description="Item 3 description"),
]
@app.get("/items/", response_model=List[Item], tags=["items"], operation_id="list_items")
async def list_items(
skip: int = Query(0, description="Number of items to skip"),
limit: int = Query(10, description="Max number of items to return"),
sort_by: Optional[str] = Query(None, description="Field to sort by"),
) -> List[Item]:
"""List all items with pagination and sorting options."""
return items[skip : skip + limit]
@app.get("/items/{item_id}", response_model=Item, tags=["items"], operation_id="get_item")
async def read_item(
item_id: int = Path(..., description="The ID of the item to retrieve"),
include_details: bool = Query(False, description="Include additional details"),
) -> Item:
"""Get a specific item by its ID with optional details."""
found_item = next((item for item in items if item.id == item_id), None)
if found_item is None:
raise HTTPException(status_code=404, detail="Item not found")
return found_item
@app.post("/items/", response_model=Item, tags=["items"], operation_id="create_item")
async def create_item(item: Item = Body(..., description="The item to create")) -> Item:
"""Create a new item in the database."""
items.append(item)
return item
@app.put("/items/{item_id}", response_model=Item, tags=["items"], operation_id="update_item")
async def update_item(
item_id: int = Path(..., description="The ID of the item to update"),
item: Item = Body(..., description="The updated item data"),
) -> Item:
"""Update an existing item."""
item.id = item_id
return item
@app.delete("/items/{item_id}", status_code=204, tags=["items"], operation_id="delete_item")
async def delete_item(item_id: int = Path(..., description="The ID of the item to delete")) -> None:
"""Delete an item from the database."""
return None
@app.get("/error", tags=["error"], operation_id="raise_error")
async def raise_error() -> None:
"""Fail on purpose and cause a 500 error."""
raise Exception("This is a test error")
return app
@pytest.fixture
def simple_fastapi_app() -> FastAPI:
return make_simple_fastapi_app()
@pytest.fixture
def simple_fastapi_app_with_root_path() -> FastAPI:
return make_simple_fastapi_app(parametrized_config={"root_path": "/api/v1"})
================================================
FILE: tests/fixtures/types.py
================================================
from typing import Optional, List, Dict, Any
from datetime import datetime, date
from enum import Enum
from uuid import UUID
from pydantic import BaseModel, Field
class Item(BaseModel):
id: int
name: str
description: Optional[str] = None
price: float
tags: List[str] = []
class OrderStatus(str, Enum):
PENDING = "pending"
PROCESSING = "processing"
SHIPPED = "shipped"
DELIVERED = "delivered"
CANCELLED = "cancelled"
RETURNED = "returned"
class PaymentMethod(str, Enum):
CREDIT_CARD = "credit_card"
DEBIT_CARD = "debit_card"
PAYPAL = "paypal"
BANK_TRANSFER = "bank_transfer"
CASH_ON_DELIVERY = "cash_on_delivery"
class ProductCategory(str, Enum):
ELECTRONICS = "electronics"
CLOTHING = "clothing"
FOOD = "food"
BOOKS = "books"
OTHER = "other"
class ProductVariant(BaseModel):
sku: str = Field(..., description="Stock keeping unit code")
color: Optional[str] = Field(None, description="Color variant")
size: Optional[str] = Field(None, description="Size variant")
weight: Optional[float] = Field(None, description="Weight in kg", gt=0)
dimensions: Optional[Dict[str, float]] = Field(None, description="Dimensions in cm (length, width, height)")
in_stock: bool = Field(True, description="Whether this variant is in stock")
stock_count: Optional[int] = Field(None, description="Number of items in stock", ge=0)
class Address(BaseModel):
street: str
city: str
state: str
postal_code: str
country: str
is_primary: bool = False
class CustomerTier(str, Enum):
STANDARD = "standard"
PREMIUM = "premium"
VIP = "vip"
class Customer(BaseModel):
id: UUID
email: str
full_name: str
phone: Optional[str] = Field(None, min_length=10, max_length=15)
tier: CustomerTier = CustomerTier.STANDARD
addresses: List[Address] = []
is_active: bool = True
created_at: datetime
last_login: Optional[datetime] = None
preferences: Dict[str, Any] = {}
consent: Dict[str, bool] = {}
class Product(BaseModel):
id: UUID
name: str
description: str
category: ProductCategory
price: float = Field(..., gt=0)
discount_percent: Optional[float] = Field(None, ge=0, le=100)
tax_rate: Optional[float] = Field(None, ge=0, le=100)
variants: List[ProductVariant] = []
tags: List[str] = []
image_urls: List[str] = []
rating: Optional[float] = Field(None, ge=0, le=5)
review_count: int = Field(0, ge=0)
created_at: datetime
updated_at: Optional[datetime] = None
is_available: bool = True
metadata: Dict[str, Any] = {}
class OrderItem(BaseModel):
product_id: UUID
variant_sku: Optional[str] = None
quantity: int = Field(..., gt=0)
unit_price: float
discount_amount: float = 0
total: float
class PaymentDetails(BaseModel):
method: PaymentMethod
transaction_id: Optional[str] = None
status: str
amount: float
currency: str = "USD"
paid_at: Optional[datetime] = None
class OrderRequest(BaseModel):
customer_id: UUID
items: List[OrderItem]
shipping_address_id: UUID
billing_address_id: Optional[UUID] = None
payment_method: PaymentMethod
notes: Optional[str] = None
use_loyalty_points: bool = False
class OrderResponse(BaseModel):
id: UUID
customer_id: UUID
status: OrderStatus = OrderStatus.PENDING
items: List[OrderItem]
shipping_address: Address
billing_address: Address
payment: PaymentDetails
subtotal: float
shipping_cost: float
tax_amount: float
discount_amount: float
total_amount: float
tracking_number: Optional[str] = None
estimated_delivery: Optional[date] = None
created_at: datetime
updated_at: Optional[datetime] = None
notes: Optional[str] = None
metadata: Dict[str, Any] = {}
class PaginatedResponse(BaseModel):
items: List[Any]
total: int
page: int
size: int
pages: int
class ErrorResponse(BaseModel):
status_code: int
message: str
details: Optional[Dict[str, Any]] = None
================================================
FILE: tests/test_basic_functionality.py
================================================
from fastapi import FastAPI
from mcp.server.lowlevel.server import Server
from fastapi_mcp import FastApiMCP
def test_create_mcp_server(simple_fastapi_app: FastAPI):
"""Test creating an MCP server without mounting it."""
mcp = FastApiMCP(
simple_fastapi_app,
name="Test MCP Server",
description="Test description",
)
# Verify the MCP server was created correctly
assert mcp.name == "Test MCP Server"
assert mcp.description == "Test description"
assert isinstance(mcp.server, Server)
assert len(mcp.tools) > 0, "Should have extracted tools from the app"
assert len(mcp.operation_map) > 0, "Should have operation mapping"
# Check that the operation map contains all expected operations from simple_app
expected_operations = ["list_items", "get_item", "create_item", "update_item", "delete_item", "raise_error"]
for op in expected_operations:
assert op in mcp.operation_map, f"Operation {op} not found in operation map"
def test_default_values(simple_fastapi_app: FastAPI):
"""Test that default values are used when not explicitly provided."""
mcp = FastApiMCP(simple_fastapi_app)
# Verify default values
assert mcp.name == simple_fastapi_app.title
assert mcp.description == simple_fastapi_app.description
# Mount with default path
mcp.mount()
# Check that the MCP server was properly mounted
# Look for a route that includes our mount path in its pattern
route_found = any("/mcp" in str(route) for route in simple_fastapi_app.routes)
assert route_found, "MCP server mount point not found in app routes"
def test_normalize_paths(simple_fastapi_app: FastAPI):
"""Test that mount paths are normalized correctly."""
mcp = FastApiMCP(simple_fastapi_app)
# Test with path without leading slash
mount_path = "test-mcp"
mcp.mount(mount_path=mount_path)
# Check that the route was added with a normalized path
route_found = any("/test-mcp" in str(route) for route in simple_fastapi_app.routes)
assert route_found, "Normalized mount path not found in app routes"
# Create a new MCP server
mcp2 = FastApiMCP(simple_fastapi_app)
# Test with path with trailing slash
mount_path = "/test-mcp2/"
mcp2.mount(mount_path=mount_path)
# Check that the route was added with a normalized path
route_found = any("/test-mcp2" in str(route) for route in simple_fastapi_app.routes)
assert route_found, "Normalized mount path not found in app routes"
================================================
FILE: tests/test_configuration.py
================================================
from fastapi import FastAPI
import pytest
from fastapi_mcp import FastApiMCP
def test_default_configuration(simple_fastapi_app: FastAPI):
"""Test the default configuration of FastApiMCP."""
# Create MCP server with defaults
mcp_server = FastApiMCP(simple_fastapi_app)
# Check default name and description
assert mcp_server.name == simple_fastapi_app.title
assert mcp_server.description == simple_fastapi_app.description
# Check default options
assert mcp_server._describe_all_responses is False
assert mcp_server._describe_full_response_schema is False
def test_custom_configuration(simple_fastapi_app: FastAPI):
"""Test a custom configuration of FastApiMCP."""
# Create MCP server with custom options
custom_name = "Custom MCP Server"
custom_description = "A custom MCP server for testing"
mcp_server = FastApiMCP(
simple_fastapi_app,
name=custom_name,
description=custom_description,
describe_all_responses=True,
describe_full_response_schema=True,
)
# Check custom name and description
assert mcp_server.name == custom_name
assert mcp_server.description == custom_description
# Check custom options
assert mcp_server._describe_all_responses is True
assert mcp_server._describe_full_response_schema is True
def test_describe_all_responses_config_simple_app(simple_fastapi_app: FastAPI):
"""Test the describe_all_responses behavior with the simple app."""
mcp_default = FastApiMCP(
simple_fastapi_app,
)
mcp_all_responses = FastApiMCP(
simple_fastapi_app,
describe_all_responses=True,
)
for tool in mcp_default.tools:
assert tool.description is not None
if tool.name == "raise_error":
pass
elif tool.name != "delete_item":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**Example Response:**") == 1, (
"The description should only contain one example response"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain a full output schema"
)
else:
# The delete endpoint in the Items API returns a 204 status code
assert tool.description.count("**200**") == 0, "The description should not contain a 200 status code"
assert tool.description.count("**204**") == 1, "The description should contain a 204 status code"
# The delete endpoint in the Items API returns a 204 status code and has no response body
assert tool.description.count("**Example Response:**") == 0, (
"The description should not contain any example responses"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain a full output schema"
)
for tool in mcp_all_responses.tools:
assert tool.description is not None
if tool.name == "raise_error":
pass
elif tool.name != "delete_item":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
assert tool.description.count("**Example Response:**") == 2, (
"The description should contain two example responses"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain a full output schema"
)
else:
assert tool.description.count("**204**") == 1, "The description should contain a 204 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# The delete endpoint in the Items API returns a 204 status code and has no response body
# But FastAPI's default 422 response should be present
# So just 1 instance of Example Response should be present
assert tool.description.count("**Example Response:**") == 1, (
"The description should contain one example response"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain any output schema"
)
def test_describe_full_response_schema_config_simple_app(simple_fastapi_app: FastAPI):
"""Test the describe_full_response_schema behavior with the simple app."""
mcp_full_response_schema = FastApiMCP(
simple_fastapi_app,
describe_full_response_schema=True,
)
for tool in mcp_full_response_schema.tools:
assert tool.description is not None
if tool.name == "raise_error":
pass
elif tool.name != "delete_item":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**Example Response:**") == 1, (
"The description should only contain one example response"
)
assert tool.description.count("**Output Schema:**") == 1, (
"The description should contain one full output schema"
)
else:
# The delete endpoint in the Items API returns a 204 status code
assert tool.description.count("**200**") == 0, "The description should not contain a 200 status code"
assert tool.description.count("**204**") == 1, "The description should contain a 204 status code"
# The delete endpoint in the Items API returns a 204 status code and has no response body
assert tool.description.count("**Example Response:**") == 0, (
"The description should not contain any example responses"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain a full output schema"
)
def test_describe_all_responses_and_full_response_schema_config_simple_app(simple_fastapi_app: FastAPI):
"""Test the describe_all_responses and describe_full_response_schema params together with the simple app."""
mcp_all_responses_and_full_response_schema = FastApiMCP(
simple_fastapi_app,
describe_all_responses=True,
describe_full_response_schema=True,
)
for tool in mcp_all_responses_and_full_response_schema.tools:
assert tool.description is not None
if tool.name == "raise_error":
pass
elif tool.name != "delete_item":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
assert tool.description.count("**Example Response:**") == 2, (
"The description should contain two example responses"
)
assert tool.description.count("**Output Schema:**") == 2, (
"The description should contain two full output schemas"
)
else:
# The delete endpoint in the Items API returns a 204 status code
assert tool.description.count("**200**") == 0, "The description should not contain a 200 status code"
assert tool.description.count("**204**") == 1, "The description should contain a 204 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# The delete endpoint in the Items API returns a 204 status code and has no response body
# But FastAPI's default 422 response should be present
# So just 1 instance of Example Response and Output Schema should be present
assert tool.description.count("**Example Response:**") == 1, (
"The description should contain one example response"
)
assert tool.description.count("**Output Schema:**") == 1, (
"The description should contain one full output schema"
)
def test_describe_all_responses_config_complex_app(complex_fastapi_app: FastAPI):
"""Test the describe_all_responses behavior with the complex app."""
mcp_default = FastApiMCP(
complex_fastapi_app,
)
mcp_all_responses = FastApiMCP(
complex_fastapi_app,
describe_all_responses=True,
)
# Test default behavior (only success responses)
for tool in mcp_default.tools:
assert tool.description is not None
# Check get_product which has a 200 response and 404 error response defined
if tool.name == "get_product":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
# Some endpoints might not have example responses if they couldn't be generated
# Only verify no error responses are included
# Check create_order which has 201, 400, 404, and 422 responses defined
elif tool.name == "create_order":
assert tool.description.count("**201**") == 1, "The description should contain a 201 status code"
assert tool.description.count("**400**") == 0, "The description should not contain a 400 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
assert tool.description.count("**422**") == 0, "The description should not contain a 422 status code"
# Some endpoints might not have example responses if they couldn't be generated
# Check get_customer which has 200, 404, and 403 responses defined
elif tool.name == "get_customer":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
assert tool.description.count("**403**") == 0, "The description should not contain a 403 status code"
# Based on the error message, this endpoint doesn't have example responses in the description
assert tool.description.count("**Example Response:**") == 0, (
"This endpoint doesn't appear to have example responses in the default configuration"
)
assert tool.description.count("**Output Schema:**") == 0, (
"The description should not contain a full output schema"
)
# Test with describe_all_responses=True (should include error responses)
for tool in mcp_all_responses.tools:
assert tool.description is not None
# Check get_product which has a 200 response and 404 error response defined
if tool.name == "get_product":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# Don't check exact count as implementations may vary, just ensure there are examples
# Check create_order which has 201, 400, 404, and 422 responses defined
elif tool.name == "create_order":
assert tool.description.count("**201**") == 1, "The description should contain a 201 status code"
assert tool.description.count("**400**") == 1, "The description should contain a 400 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# Don't check exact count as implementations may vary, just ensure there are examples
# Check get_customer which has 200, 404, and 403 responses defined
elif tool.name == "get_customer":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**403**") == 1, "The description should contain a 403 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# Based on error messages, we need to check actual implementation behavior
def test_describe_full_response_schema_config_complex_app(complex_fastapi_app: FastAPI):
"""Test the describe_full_response_schema behavior with the complex app."""
mcp_full_response_schema = FastApiMCP(
complex_fastapi_app,
describe_full_response_schema=True,
)
for tool in mcp_full_response_schema.tools:
assert tool.description is not None
# Check get_product which has a 200 response and 404 error response defined
if tool.name == "get_product":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
# Only verify the success response schema is present
assert tool.description.count("**Output Schema:**") >= 1, (
"The description should contain at least one full output schema"
)
# Check create_order which has 201, 400, 404, and 422 responses defined
elif tool.name == "create_order":
assert tool.description.count("**201**") == 1, "The description should contain a 201 status code"
assert tool.description.count("**400**") == 0, "The description should not contain a 400 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
assert tool.description.count("**422**") == 0, "The description should not contain a 422 status code"
# Only verify the success response schema is present
assert tool.description.count("**Output Schema:**") >= 1, (
"The description should contain at least one full output schema"
)
# Check get_customer which has 200, 404, and 403 responses defined
elif tool.name == "get_customer":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 0, "The description should not contain a 404 status code"
assert tool.description.count("**403**") == 0, "The description should not contain a 403 status code"
# Based on error message, there are no example responses but there is an output schema
assert tool.description.count("**Example Response:**") == 0, (
"This endpoint doesn't appear to have example responses"
)
assert tool.description.count("**Output Schema:**") >= 1, (
"The description should contain at least one full output schema"
)
def test_describe_all_responses_and_full_response_schema_config_complex_app(complex_fastapi_app: FastAPI):
"""Test the describe_all_responses and describe_full_response_schema together with the complex app."""
mcp_all_responses_and_full_schema = FastApiMCP(
complex_fastapi_app,
describe_all_responses=True,
describe_full_response_schema=True,
)
for tool in mcp_all_responses_and_full_schema.tools:
assert tool.description is not None
# Check get_product which has a 200 response and 404 error response defined
if tool.name == "get_product":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# Based on the error message data, adjust the expected counts
# Don't check exact counts, just ensure they exist
assert tool.description.count("**Example Response:**") > 0, (
"The description should contain example responses"
)
assert tool.description.count("**Output Schema:**") > 0, (
"The description should contain full output schemas"
)
# Check create_order which has 201, 400, 404, and 422 responses defined
elif tool.name == "create_order":
assert tool.description.count("**201**") == 1, "The description should contain a 201 status code"
assert tool.description.count("**400**") == 1, "The description should contain a 400 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# Don't check exact counts, just ensure they exist
assert tool.description.count("**Example Response:**") > 0, (
"The description should contain example responses"
)
assert tool.description.count("**Output Schema:**") > 0, (
"The description should contain full output schemas"
)
# Check get_customer which has 200, 404, and 403 responses defined
elif tool.name == "get_customer":
assert tool.description.count("**200**") == 1, "The description should contain a 200 status code"
assert tool.description.count("**404**") == 1, "The description should contain a 404 status code"
assert tool.description.count("**403**") == 1, "The description should contain a 403 status code"
assert tool.description.count("**422**") == 1, "The description should contain a 422 status code"
# From error message, we know there are exactly 3 example responses for this endpoint
assert tool.description.count("**Example Response:**") == 3, (
"The description should contain exactly three example responses"
)
assert tool.description.count("**Output Schema:**") > 0, (
"The description should contain full output schemas"
)
def test_filtering_functionality():
"""Test that FastApiMCP correctly filters endpoints based on operation IDs and tags."""
app = FastAPI()
# Define endpoints with different operation IDs and tags
@app.get("/items/", operation_id="list_items", tags=["items"])
async def list_items():
return [{"id": 1}]
@app.get("/items/{item_id}", operation_id="get_item", tags=["items", "read"])
async def get_item(item_id: int):
return {"id": item_id}
@app.post("/items/", operation_id="create_item", tags=["items", "write"])
async def create_item():
return {"id": 2}
@app.put("/items/{item_id}", operation_id="update_item", tags=["items", "write"])
async def update_item(item_id: int):
return {"id": item_id}
@app.delete("/items/{item_id}", operation_id="delete_item", tags=["items", "delete"])
async def delete_item(item_id: int):
return {"id": item_id}
@app.get("/search/", operation_id="search_items", tags=["search"])
async def search_items():
return [{"id": 1}]
# Test include_operations
include_ops_mcp = FastApiMCP(app, include_operations=["get_item", "list_items"])
assert len(include_ops_mcp.tools) == 2
assert {tool.name for tool in include_ops_mcp.tools} == {"get_item", "list_items"}
# Test exclude_operations
exclude_ops_mcp = FastApiMCP(app, exclude_operations=["delete_item", "search_items"])
assert len(exclude_ops_mcp.tools) == 4
assert {tool.name for tool in exclude_ops_mcp.tools} == {"get_item", "list_items", "create_item", "update_item"}
# Test include_tags
include_tags_mcp = FastApiMCP(app, include_tags=["read"])
assert len(include_tags_mcp.tools) == 1
assert {tool.name for tool in include_tags_mcp.tools} == {"get_item"}
# Test exclude_tags
exclude_tags_mcp = FastApiMCP(app, exclude_tags=["write", "delete"])
assert len(exclude_tags_mcp.tools) == 3
assert {tool.name for tool in exclude_tags_mcp.tools} == {"get_item", "list_items", "search_items"}
# Test combining include_operations and include_tags
combined_include_mcp = FastApiMCP(app, include_operations=["delete_item"], include_tags=["search"])
assert len(combined_include_mcp.tools) == 2
assert {tool.name for tool in combined_include_mcp.tools} == {"delete_item", "search_items"}
# Test invalid combinations
with pytest.raises(ValueError):
FastApiMCP(app, include_operations=["get_item"], exclude_operations=["delete_item"])
with pytest.raises(ValueError):
FastApiMCP(app, include_tags=["items"], exclude_tags=["write"])
def test_filtering_edge_cases():
"""Test edge cases for the filtering functionality."""
app = FastAPI()
# Define endpoints with different operation IDs and tags
@app.get("/items/", operation_id="list_items", tags=["items"])
async def list_items():
return [{"id": 1}]
@app.get("/items/{item_id}", operation_id="get_item", tags=["items", "read"])
async def get_item(item_id: int):
return {"id": item_id}
# Test with no filtering (default behavior)
default_mcp = FastApiMCP(app)
assert len(default_mcp.tools) == 2
assert {tool.name for tool in default_mcp.tools} == {"get_item", "list_items"}
# Test with empty include_operations
empty_include_ops_mcp = FastApiMCP(app, include_operations=[])
assert len(empty_include_ops_mcp.tools) == 0
assert empty_include_ops_mcp.tools == []
# Test with empty exclude_operations (should include all)
empty_exclude_ops_mcp = FastApiMCP(app, exclude_operations=[])
assert len(empty_exclude_ops_mcp.tools) == 2
assert {tool.name for tool in empty_exclude_ops_mcp.tools} == {"get_item", "list_items"}
# Test with empty include_tags
empty_include_tags_mcp = FastApiMCP(app, include_tags=[])
assert len(empty_include_tags_mcp.tools) == 0
assert empty_include_tags_mcp.tools == []
# Test with empty exclude_tags (should include all)
empty_exclude_tags_mcp = FastApiMCP(app, exclude_tags=[])
assert len(empty_exclude_tags_mcp.tools) == 2
assert {tool.name for tool in empty_exclude_tags_mcp.tools} == {"get_item", "list_items"}
# Test with non-existent operation IDs
nonexistent_ops_mcp = FastApiMCP(app, include_operations=["non_existent_op"])
assert len(nonexistent_ops_mcp.tools) == 0
assert nonexistent_ops_mcp.tools == []
# Test with non-existent tags
nonexistent_tags_mcp = FastApiMCP(app, include_tags=["non_existent_tag"])
assert len(nonexistent_tags_mcp.tools) == 0
assert nonexistent_tags_mcp.tools == []
# Test excluding non-existent operation IDs
exclude_nonexistent_ops_mcp = FastApiMCP(app, exclude_operations=["non_existent_op"])
assert len(exclude_nonexistent_ops_mcp.tools) == 2
assert {tool.name for tool in exclude_nonexistent_ops_mcp.tools} == {"get_item", "list_items"}
# Test excluding non-existent tags
exclude_nonexistent_tags_mcp = FastApiMCP(app, exclude_tags=["non_existent_tag"])
assert len(exclude_nonexistent_tags_mcp.tools) == 2
assert {tool.name for tool in exclude_nonexistent_tags_mcp.tools} == {"get_item", "list_items"}
# Test with an endpoint that has no tags
@app.get("/no-tags", operation_id="no_tags")
async def no_tags():
return {"result": "no tags"}
# Test include_tags with an endpoint that has no tags
no_tags_app_mcp = FastApiMCP(app, include_tags=["items"])
assert len(no_tags_app_mcp.tools) == 2
assert "no_tags" not in {tool.name for tool in no_tags_app_mcp.tools}
# Test exclude_tags with an endpoint that has no tags
no_tags_exclude_mcp = FastApiMCP(app, exclude_tags=["items"])
assert len(no_tags_exclude_mcp.tools) == 1
assert {tool.name for tool in no_tags_exclude_mcp.tools} == {"no_tags"}
def test_filtering_with_missing_operation_ids():
"""Test filtering behavior with endpoints that don't have operation IDs."""
app = FastAPI()
# Define an endpoint with an operation ID
@app.get("/items/", operation_id="list_items", tags=["items"])
async def list_items():
return [{"id": 1}]
# Define an endpoint without an operation ID
@app.get("/no-op-id/")
async def no_op_id():
return {"result": "no operation ID"}
# Test that both endpoints are discovered
default_mcp = FastApiMCP(app)
# FastAPI-MCP will generate an operation ID for endpoints without one
# The auto-generated ID will typically be 'no_op_id_no_op_id__get'
assert len(default_mcp.tools) == 2
# Get the auto-generated operation ID
auto_generated_op_id = None
for tool in default_mcp.tools:
if tool.name != "list_items":
auto_generated_op_id = tool.name
break
assert auto_generated_op_id is not None
assert "list_items" in {tool.name for tool in default_mcp.tools}
# Test include_operations with the known operation ID
include_ops_mcp = FastApiMCP(app, include_operations=["list_items"])
assert len(include_ops_mcp.tools) == 1
assert {tool.name for tool in include_ops_mcp.tools} == {"list_items"}
# Test include_operations with the auto-generated operation ID
include_auto_ops_mcp = FastApiMCP(app, include_operations=[auto_generated_op_id])
assert len(include_auto_ops_mcp.tools) == 1
assert {tool.name for tool in include_auto_ops_mcp.tools} == {auto_generated_op_id}
# Test include_tags with a tag that matches the endpoint
include_tags_mcp = FastApiMCP(app, include_tags=["items"])
assert len(include_tags_mcp.tools) == 1
assert {tool.name for tool in include_tags_mcp.tools} == {"list_items"}
def test_filter_with_empty_tools():
"""Test filtering with an empty tools list to ensure it handles this edge case correctly."""
# Create a FastAPI app without any routes
app = FastAPI()
# Create MCP server (should have no tools)
empty_mcp = FastApiMCP(app)
assert len(empty_mcp.tools) == 0
# Test filtering with various options on an empty app
include_ops_mcp = FastApiMCP(app, include_operations=["some_op"])
assert len(include_ops_mcp.tools) == 0
exclude_ops_mcp = FastApiMCP(app, exclude_operations=["some_op"])
assert len(exclude_ops_mcp.tools) == 0
include_tags_mcp = FastApiMCP(app, include_tags=["some_tag"])
assert len(include_tags_mcp.tools) == 0
exclude_tags_mcp = FastApiMCP(app, exclude_tags=["some_tag"])
assert len(exclude_tags_mcp.tools) == 0
# Test combined filtering
combined_mcp = FastApiMCP(app, include_operations=["op"], include_tags=["tag"])
assert len(combined_mcp.tools) == 0
def test_filtering_with_empty_tags_array():
"""Test filtering behavior with endpoints that have empty tags array."""
app = FastAPI()
# Define an endpoint with tags
@app.get("/items/", operation_id="list_items", tags=["items"])
async def list_items():
return [{"id": 1}]
# Define an endpoint with an empty tags array
@app.get("/empty-tags/", operation_id="empty_tags", tags=[])
async def empty_tags():
return {"result": "empty tags"}
# Test default behavior
default_mcp = FastApiMCP(app)
assert len(default_mcp.tools) == 2
assert {tool.name for tool in default_mcp.tools} == {"list_items", "empty_tags"}
# Test include_tags
include_tags_mcp = FastApiMCP(app, include_tags=["items"])
assert len(include_tags_mcp.tools) == 1
assert {tool.name for tool in include_tags_mcp.tools} == {"list_items"}
# Test exclude_tags
exclude_tags_mcp = FastApiMCP(app, exclude_tags=["items"])
assert len(exclude_tags_mcp.tools) == 1
assert {tool.name for tool in exclude_tags_mcp.tools} == {"empty_tags"}
================================================
FILE: tests/test_http_real_transport.py
================================================
import multiprocessing
import socket
import time
import os
import signal
import atexit
import sys
import threading
import coverage
from typing import AsyncGenerator, Generator
from fastapi import FastAPI
import pytest
import httpx
import uvicorn
from fastapi_mcp import FastApiMCP
import mcp.types as types
HOST = "127.0.0.1"
SERVER_NAME = "Test MCP Server"
def run_server(server_port: int, fastapi_app: FastAPI) -> None:
# Initialize coverage for subprocesses
cov = None
if "COVERAGE_PROCESS_START" in os.environ:
cov = coverage.Coverage(source=["fastapi_mcp"])
cov.start()
# Create a function to save coverage data at exit
def cleanup():
if cov:
cov.stop()
cov.save()
# Register multiple cleanup mechanisms to ensure coverage data is saved
atexit.register(cleanup)
# Setup signal handler for clean termination
def handle_signal(signum, frame):
cleanup()
sys.exit(0)
signal.signal(signal.SIGTERM, handle_signal)
# Backup thread to ensure coverage is written if process is terminated abruptly
def periodic_save():
while True:
time.sleep(1.0)
if cov:
cov.save()
save_thread = threading.Thread(target=periodic_save)
save_thread.daemon = True
save_thread.start()
# Configure the server
mcp = FastApiMCP(
fastapi_app,
name=SERVER_NAME,
description="Test description",
)
mcp.mount_http()
# Start the server
server = uvicorn.Server(config=uvicorn.Config(app=fastapi_app, host=HOST, port=server_port, log_level="error"))
server.run()
# Give server time to start
while not server.started:
time.sleep(0.5)
# Ensure coverage is saved if exiting the normal way
if cov:
cov.stop()
cov.save()
@pytest.fixture(params=["simple_fastapi_app", "simple_fastapi_app_with_root_path"])
def server(request: pytest.FixtureRequest) -> Generator[str, None, None]:
# Ensure COVERAGE_PROCESS_START is set in the environment for subprocesses
coverage_rc = os.path.abspath(".coveragerc")
os.environ["COVERAGE_PROCESS_START"] = coverage_rc
# Get a free port
with socket.socket() as s:
s.bind((HOST, 0))
server_port = s.getsockname()[1]
# Use fork method to avoid pickling issues
ctx = multiprocessing.get_context("fork")
# Run the server in a subprocess
fastapi_app = request.getfixturevalue(request.param)
proc = ctx.Process(
target=run_server,
kwargs={"server_port": server_port, "fastapi_app": fastapi_app},
daemon=True,
)
proc.start()
# Wait for server to be running
max_attempts = 20
attempt = 0
while attempt < max_attempts:
try:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
s.connect((HOST, server_port))
break
except ConnectionRefusedError:
time.sleep(0.1)
attempt += 1
else:
raise RuntimeError(f"Server failed to start after {max_attempts} attempts")
# Return the server URL
yield f"http://{HOST}:{server_port}{fastapi_app.root_path}"
# Signal the server to stop - added graceful shutdown before kill
try:
proc.terminate()
proc.join(timeout=2)
except (OSError, AttributeError):
pass
if proc.is_alive():
proc.kill()
proc.join(timeout=2)
if proc.is_alive():
raise RuntimeError("server process failed to terminate")
@pytest.fixture()
async def http_client(server: str) -> AsyncGenerator[httpx.AsyncClient, None]:
async with httpx.AsyncClient(base_url=server) as client:
yield client
@pytest.mark.anyio
async def test_http_initialize_request(http_client: httpx.AsyncClient, server: str) -> None:
mcp_path = "/mcp" # Always use absolute path since server already includes root_path
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {
"sampling": None,
"elicitation": None,
"experimental": None,
"roots": None,
},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert response.status_code == 200
result = response.json()
assert result["jsonrpc"] == "2.0"
assert result["id"] == 1
assert "result" in result
assert result["result"]["serverInfo"]["name"] == SERVER_NAME
@pytest.mark.anyio
async def test_http_list_tools(http_client: httpx.AsyncClient, server: str) -> None:
"""Test tool listing via HTTP POST with JSON response."""
mcp_path = "/mcp"
init_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert init_response.status_code == 200
# Extract session ID from the initialize response
session_id = init_response.headers.get("mcp-session-id")
assert session_id is not None, "Server should return a session ID"
initialized_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "notifications/initialized",
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert initialized_response.status_code == 202
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "tools/list",
"id": 2,
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert response.status_code == 200
result = response.json()
assert result["jsonrpc"] == "2.0"
assert result["id"] == 2
assert "result" in result
assert "tools" in result["result"]
assert len(result["result"]["tools"]) > 0
# Verify we have the expected tools from the simple FastAPI app
tool_names = [tool["name"] for tool in result["result"]["tools"]]
assert "get_item" in tool_names
assert "list_items" in tool_names
@pytest.mark.anyio
async def test_http_call_tool(http_client: httpx.AsyncClient, server: str) -> None:
"""Test tool calling via HTTP POST with JSON response."""
mcp_path = "/mcp"
init_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert init_response.status_code == 200
# Extract session ID from the initialize response
session_id = init_response.headers.get("mcp-session-id")
assert session_id is not None, "Server should return a session ID"
initialized_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "notifications/initialized",
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert initialized_response.status_code == 202
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "tools/call",
"id": 3,
"params": {
"name": "get_item",
"arguments": {"item_id": 1},
},
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert response.status_code == 200
result = response.json()
assert result["jsonrpc"] == "2.0"
assert result["id"] == 3
assert "result" in result
assert result["result"]["isError"] is False
assert "content" in result["result"]
assert len(result["result"]["content"]) > 0
# Verify the response contains expected item data
content = result["result"]["content"][0]
assert content["type"] == "text"
assert "Item 1" in content["text"] # Should contain the item name
@pytest.mark.anyio
async def test_http_ping(http_client: httpx.AsyncClient, server: str) -> None:
"""Test ping functionality via HTTP POST."""
mcp_path = "/mcp"
init_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert init_response.status_code == 200
# Extract session ID from the initialize response
session_id = init_response.headers.get("mcp-session-id")
assert session_id is not None, "Server should return a session ID"
initialized_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "notifications/initialized",
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert initialized_response.status_code == 202
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "ping",
"id": 4,
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert response.status_code == 200
result = response.json()
assert result["jsonrpc"] == "2.0"
assert result["id"] == 4
assert "result" in result
@pytest.mark.anyio
async def test_http_error_handling(http_client: httpx.AsyncClient, server: str) -> None:
"""Test error handling for invalid requests."""
mcp_path = "/mcp"
response = await http_client.post(
mcp_path,
content="invalid json",
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert response.status_code == 400
result = response.json()
assert "error" in result
assert result["error"]["code"] == -32700 # Parse error
@pytest.mark.anyio
async def test_http_invalid_method(http_client: httpx.AsyncClient, server: str) -> None:
"""Test error handling for invalid methods."""
mcp_path = "/mcp"
# First initialize to get a session ID
init_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert init_response.status_code == 200
# Extract session ID from the initialize response
session_id = init_response.headers.get("mcp-session-id")
assert session_id is not None, "Server should return a session ID"
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "invalid/method",
"id": 5,
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert response.status_code == 200
result = response.json()
assert result["jsonrpc"] == "2.0"
assert result["id"] == 5
assert "error" in result
assert result["error"]["code"] == -32602 # Invalid request parameters
@pytest.mark.anyio
async def test_http_notification_handling(http_client: httpx.AsyncClient, server: str) -> None:
"""Test that notifications return 202 Accepted without response body."""
mcp_path = "/mcp"
# First initialize to get a session ID
init_response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": types.LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0.0"},
},
},
headers={"Accept": "application/json, text/event-stream", "Content-Type": "application/json"},
)
assert init_response.status_code == 200
# Extract session ID from the initialize response
session_id = init_response.headers.get("mcp-session-id")
assert session_id is not None, "Server should return a session ID"
response = await http_client.post(
mcp_path,
json={
"jsonrpc": "2.0",
"method": "notifications/cancelled",
"params": {"requestId": "test-123"},
},
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"mcp-session-id": session_id,
},
)
assert response.status_code == 202
# Notifications should return empty body
assert response.content == b"" or response.text == "null"
================================================
FILE: tests/test_mcp_complex_app.py
================================================
import json
import pytest
import mcp.types as types
from mcp.server.lowlevel import Server
from mcp.shared.memory import create_connected_server_and_client_session
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from .fixtures.types import Product, Customer, OrderResponse
@pytest.fixture
def fastapi_mcp(complex_fastapi_app: FastAPI) -> FastApiMCP:
mcp = FastApiMCP(
complex_fastapi_app,
name="Test MCP Server",
description="Test description",
)
mcp.mount()
return mcp
@pytest.fixture
def lowlevel_server_complex_app(fastapi_mcp: FastApiMCP) -> Server:
return fastapi_mcp.server
@pytest.mark.asyncio
async def test_list_tools(lowlevel_server_complex_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
tools_result = await client_session.list_tools()
assert len(tools_result.tools) > 0
tool_names = [tool.name for tool in tools_result.tools]
expected_operations = ["list_products", "get_product", "create_order", "get_customer"]
for op in expected_operations:
assert op in tool_names
@pytest.mark.asyncio
async def test_call_tool_list_products_default(lowlevel_server_complex_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool("list_products", {})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert "items" in result
assert result["total"] == 1
assert result["page"] == 1
assert len(result["items"]) == 1
@pytest.mark.asyncio
async def test_call_tool_list_products_with_filters(lowlevel_server_complex_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool(
"list_products",
{"category": "electronics", "min_price": 10.0, "page": 1, "size": 10, "in_stock_only": True},
)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert "items" in result
assert result["page"] == 1
assert result["size"] == 10
@pytest.mark.asyncio
async def test_call_tool_get_product(lowlevel_server_complex_app: Server, example_product: Product):
product_id = "123e4567-e89b-12d3-a456-426614174000" # Valid UUID format
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool("get_product", {"product_id": product_id})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == product_id
assert "name" in result
assert "price" in result
assert "description" in result
@pytest.mark.asyncio
async def test_call_tool_get_product_with_options(lowlevel_server_complex_app: Server):
product_id = "123e4567-e89b-12d3-a456-426614174000" # Valid UUID format
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool(
"get_product", {"product_id": product_id, "include_unavailable": True}
)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == product_id
@pytest.mark.asyncio
async def test_call_tool_create_order(lowlevel_server_complex_app: Server, example_order_response: OrderResponse):
customer_id = "123e4567-e89b-12d3-a456-426614174000" # Valid UUID format
product_id = "123e4567-e89b-12d3-a456-426614174001" # Valid UUID format
shipping_address_id = "123e4567-e89b-12d3-a456-426614174002" # Valid UUID format
order_request = {
"customer_id": customer_id,
"items": [{"product_id": product_id, "quantity": 2, "unit_price": 29.99, "total": 59.98}],
"shipping_address_id": shipping_address_id,
"payment_method": "credit_card",
}
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool("create_order", order_request)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["customer_id"] == customer_id
assert "id" in result
assert "status" in result
assert "items" in result
assert len(result["items"]) > 0
@pytest.mark.asyncio
async def test_call_tool_create_order_validation_error(lowlevel_server_complex_app: Server):
# Missing required fields
order_request = {
# Missing customer_id
"items": [],
# Missing shipping_address_id
"payment_method": "credit_card",
}
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool("create_order", order_request)
assert response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert "422" in text_content.text or "validation" in text_content.text.lower()
@pytest.mark.asyncio
async def test_call_tool_get_customer(lowlevel_server_complex_app: Server, example_customer: Customer):
customer_id = "123e4567-e89b-12d3-a456-426614174000" # Valid UUID format
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool("get_customer", {"customer_id": customer_id})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == customer_id
assert "full_name" in result
assert "email" in result
@pytest.mark.asyncio
async def test_call_tool_get_customer_with_options(lowlevel_server_complex_app: Server):
customer_id = "123e4567-e89b-12d3-a456-426614174000" # Valid UUID format
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
response = await client_session.call_tool(
"get_customer",
{
"customer_id": customer_id,
"include_orders": True,
"include_payment_methods": True,
"fields": ["full_name", "email", "orders"],
},
)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == customer_id
@pytest.mark.asyncio
async def test_error_handling_missing_parameter(lowlevel_server_complex_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_complex_app) as client_session:
# Missing required product_id parameter
response = await client_session.call_tool("get_product", {})
assert response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert "input validation error" in text_content.text.lower(), "Expected an input validation error"
assert "required" in text_content.text.lower(), "Expected a missing required parameter error"
================================================
FILE: tests/test_mcp_execute_api_tool.py
================================================
import pytest
from unittest.mock import AsyncMock, patch, MagicMock
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from mcp.types import TextContent
@pytest.mark.asyncio
async def test_execute_api_tool_success(simple_fastapi_app: FastAPI):
"""Test successful execution of an API tool."""
mcp = FastApiMCP(simple_fastapi_app)
# Mock the HTTP client response
mock_response = MagicMock()
mock_response.json.return_value = {"id": 1, "name": "Test Item"}
mock_response.status_code = 200
mock_response.text = '{"id": 1, "name": "Test Item"}'
# Mock the HTTP client
mock_client = AsyncMock()
mock_client.get.return_value = mock_response
# Test parameters
tool_name = "get_item"
arguments = {"item_id": 1}
# Execute the tool
with patch.object(mcp, '_http_client', mock_client):
result = await mcp._execute_api_tool(
client=mock_client,
tool_name=tool_name,
arguments=arguments,
operation_map=mcp.operation_map
)
# Verify the result
assert len(result) == 1
assert isinstance(result[0], TextContent)
assert result[0].text == '{\n "id": 1,\n "name": "Test Item"\n}'
# Verify the HTTP client was called correctly
mock_client.get.assert_called_once_with(
"/items/1",
params={},
headers={}
)
@pytest.mark.asyncio
async def test_execute_api_tool_with_query_params(simple_fastapi_app: FastAPI):
"""Test execution of an API tool with query parameters."""
mcp = FastApiMCP(simple_fastapi_app)
# Mock the HTTP client response
mock_response = MagicMock()
mock_response.json.return_value = [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]
mock_response.status_code = 200
mock_response.text = '[{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]'
# Mock the HTTP client
mock_client = AsyncMock()
mock_client.get.return_value = mock_response
# Test parameters
tool_name = "list_items"
arguments = {"skip": 0, "limit": 2}
# Execute the tool
with patch.object(mcp, '_http_client', mock_client):
result = await mcp._execute_api_tool(
client=mock_client,
tool_name=tool_name,
arguments=arguments,
operation_map=mcp.operation_map
)
# Verify the result
assert len(result) == 1
assert isinstance(result[0], TextContent)
# Verify the HTTP client was called with query parameters
mock_client.get.assert_called_once_with(
"/items/",
params={"skip": 0, "limit": 2},
headers={}
)
@pytest.mark.asyncio
async def test_execute_api_tool_with_body(simple_fastapi_app: FastAPI):
"""Test execution of an API tool with request body."""
mcp = FastApiMCP(simple_fastapi_app)
# Mock the HTTP client response
mock_response = MagicMock()
mock_response.json.return_value = {"id": 1, "name": "New Item"}
mock_response.status_code = 200
mock_response.text = '{"id": 1, "name": "New Item"}'
# Mock the HTTP client
mock_client = AsyncMock()
mock_client.post.return_value = mock_response
# Test parameters
tool_name = "create_item"
arguments = {
"item": {
"id": 1,
"name": "New Item",
"price": 10.0,
"tags": ["tag1"],
"description": "New item description"
}
}
# Execute the tool
with patch.object(mcp, '_http_client', mock_client):
result = await mcp._execute_api_tool(
client=mock_client,
tool_name=tool_name,
arguments=arguments,
operation_map=mcp.operation_map
)
# Verify the result
assert len(result) == 1
assert isinstance(result[0], TextContent)
# Verify the HTTP client was called with the request body
mock_client.post.assert_called_once_with(
"/items/",
params={},
headers={},
json=arguments
)
@pytest.mark.asyncio
async def test_execute_api_tool_with_non_ascii_chars(simple_fastapi_app: FastAPI):
"""Test execution of an API tool with non-ASCII characters."""
mcp = FastApiMCP(simple_fastapi_app)
# Test data with both ASCII and non-ASCII characters
test_data = {
"id": 1,
"name": "你好 World", # Chinese characters + ASCII
"price": 10.0,
"tags": ["tag1", "标签2"], # Chinese characters in tags
"description": "这是一个测试描述" # All Chinese characters
}
# Mock the HTTP client response
mock_response = MagicMock()
mock_response.json.return_value = test_data
mock_response.status_code = 200
mock_response.text = '{"id": 1, "name": "你好 World", "price": 10.0, "tags": ["tag1", "标签2"], "description": "这是一个测试描述"}'
# Mock the HTTP client
mock_client = AsyncMock()
mock_client.get.return_value = mock_response
# Test parameters
tool_name = "get_item"
arguments = {"item_id": 1}
# Execute the tool
with patch.object(mcp, '_http_client', mock_client):
result = await mcp._execute_api_tool(
client=mock_client,
tool_name=tool_name,
arguments=arguments,
operation_map=mcp.operation_map
)
# Verify the result
assert len(result) == 1
assert isinstance(result[0], TextContent)
# Verify that the response contains both ASCII and non-ASCII characters
response_text = result[0].text
assert "你好" in response_text # Chinese characters preserved
assert "World" in response_text # ASCII characters preserved
assert "标签2" in response_text # Chinese characters in tags preserved
assert "这是一个测试描述" in response_text # All Chinese description preserved
# Verify the HTTP client was called correctly
mock_client.get.assert_called_once_with(
"/items/1",
params={},
headers={}
)
================================================
FILE: tests/test_mcp_simple_app.py
================================================
import json
import pytest
import mcp.types as types
from mcp.server.lowlevel import Server
from mcp.shared.memory import create_connected_server_and_client_session
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from .fixtures.types import Item
@pytest.fixture
def fastapi_mcp(simple_fastapi_app: FastAPI) -> FastApiMCP:
mcp = FastApiMCP(
simple_fastapi_app,
name="Test MCP Server",
description="Test description",
)
mcp.mount()
return mcp
@pytest.fixture
def fastapi_mcp_with_custom_header(simple_fastapi_app: FastAPI) -> FastApiMCP:
mcp = FastApiMCP(
simple_fastapi_app,
name="Test MCP Server with custom header",
description="Test description",
headers=["X-Custom-Header"],
)
mcp.mount()
return mcp
@pytest.fixture
def lowlevel_server_simple_app(fastapi_mcp: FastApiMCP) -> Server:
return fastapi_mcp.server
@pytest.mark.asyncio
async def test_list_tools(lowlevel_server_simple_app: Server):
"""Test listing tools via direct MCP connection."""
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
tools_result = await client_session.list_tools()
assert len(tools_result.tools) > 0
tool_names = [tool.name for tool in tools_result.tools]
expected_operations = ["list_items", "get_item", "create_item", "update_item", "delete_item", "raise_error"]
for op in expected_operations:
assert op in tool_names
@pytest.mark.asyncio
async def test_call_tool_get_item_1(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("get_item", {"item_id": 1})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result: dict = json.loads(text_content.text)
parsed_result = Item(**result)
assert parsed_result.id == 1
assert parsed_result.name == "Item 1"
assert parsed_result.price == 10.0
assert parsed_result.tags == ["tag1", "tag2"]
@pytest.mark.asyncio
async def test_call_tool_get_item_2(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("get_item", {"item_id": 2})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result: dict = json.loads(text_content.text)
parsed_result = Item(**result)
assert parsed_result.id == 2
assert parsed_result.name == "Item 2"
assert parsed_result.price == 20.0
assert parsed_result.tags == ["tag2", "tag3"]
@pytest.mark.asyncio
async def test_call_tool_raise_error(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("raise_error", {})
assert response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert "500" in text_content.text
assert "internal server error" in text_content.text.lower()
@pytest.mark.asyncio
async def test_error_handling(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("get_item", {})
assert response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert "item_id" in text_content.text.lower() or "missing" in text_content.text.lower()
assert "input validation error" in text_content.text.lower(), "Expected an input validation error"
@pytest.mark.asyncio
async def test_complex_tool_arguments(lowlevel_server_simple_app: Server):
test_item = {
"id": 42,
"name": "Test Item",
"description": "A test item for MCP",
"price": 9.99,
"tags": ["test", "mcp"],
}
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("create_item", test_item)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == test_item["id"]
assert result["name"] == test_item["name"]
assert result["price"] == test_item["price"]
assert result["tags"] == test_item["tags"]
@pytest.mark.asyncio
async def test_call_tool_list_items_default(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("list_items", {})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
results = json.loads(text_content.text)
assert len(results) == 3 # Default should return all three items with default pagination
# Check first item matches expected data
item = results[0]
assert item["id"] == 1
assert item["name"] == "Item 1"
@pytest.mark.asyncio
async def test_call_tool_list_items_with_pagination(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("list_items", {"skip": 1, "limit": 1})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
results = json.loads(text_content.text)
assert len(results) == 1
# Should be the second item in the list (after skipping the first)
item = results[0]
assert item["id"] == 2
assert item["name"] == "Item 2"
@pytest.mark.asyncio
async def test_call_tool_get_item_not_found(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("get_item", {"item_id": 999})
assert response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert "404" in text_content.text
assert "not found" in text_content.text.lower()
@pytest.mark.asyncio
async def test_call_tool_update_item(lowlevel_server_simple_app: Server):
test_update = {
"item_id": 3,
"id": 3,
"name": "Updated Item 3",
"description": "Updated description",
"price": 35.99,
"tags": ["updated", "modified"],
}
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("update_item", test_update)
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result = json.loads(text_content.text)
assert result["id"] == test_update["item_id"]
assert result["name"] == test_update["name"]
assert result["description"] == test_update["description"]
assert result["price"] == test_update["price"]
assert result["tags"] == test_update["tags"]
@pytest.mark.asyncio
async def test_call_tool_delete_item(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("delete_item", {"item_id": 3})
assert not response.isError
# The endpoint returns 204 No Content, so we expect an empty response
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
assert (
text_content.text.strip() == "{}" or text_content.text.strip() == "null" or text_content.text.strip() == ""
)
@pytest.mark.asyncio
async def test_call_tool_get_item_with_details(lowlevel_server_simple_app: Server):
async with create_connected_server_and_client_session(lowlevel_server_simple_app) as client_session:
response = await client_session.call_tool("get_item", {"item_id": 1, "include_details": True})
assert not response.isError
assert len(response.content) > 0
text_content = next(c for c in response.content if isinstance(c, types.TextContent))
result: dict = json.loads(text_content.text)
parsed_result = Item(**result)
assert parsed_result.id == 1
assert parsed_result.name == "Item 1"
assert parsed_result.price == 10.0
assert parsed_result.tags == ["tag1", "tag2"]
assert parsed_result.description == "Item 1 description"
@pytest.mark.asyncio
async def test_headers_passthrough_to_tool_handler(fastapi_mcp: FastApiMCP):
"""Test that the original request's headers pass through to the MCP tool call handler."""
from unittest.mock import patch, MagicMock
from fastapi_mcp.types import HTTPRequestInfo
# Test with uppercase "Authorization" header
with patch.object(fastapi_mcp, "_request") as mock_request:
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.text = '{"result": "success"}'
mock_response.json.return_value = {"result": "success"}
mock_request.return_value = mock_response
http_request_info = HTTPRequestInfo(
method="POST",
path="/test",
headers={"Authorization": "Bearer token123"},
cookies={},
query_params={},
body=None,
)
try:
# Call the _execute_api_tool method directly
# We don't care if it succeeds, just that _request gets the right headers
await fastapi_mcp._execute_api_tool(
client=fastapi_mcp._http_client,
tool_name="get_item",
arguments={"item_id": 1},
operation_map=fastapi_mcp.operation_map,
http_request_info=http_request_info,
)
except Exception:
pass
assert mock_request.called, "The _request method was not called"
if mock_request.called:
headers_arg = mock_request.call_args[0][4] # headers are the 5th argument
assert "Authorization" in headers_arg
assert headers_arg["Authorization"] == "Bearer token123"
# Test again with lowercase "authorization" header
with patch.object(fastapi_mcp, "_request") as mock_request:
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.text = '{"result": "success"}'
mock_response.json.return_value = {"result": "success"}
mock_request.return_value = mock_response
http_request_info = HTTPRequestInfo(
method="POST",
path="/test",
headers={"authorization": "Bearer token456"},
cookies={},
query_params={},
body=None,
)
try:
await fastapi_mcp._execute_api_tool(
client=fastapi_mcp._http_client,
tool_name="get_item",
arguments={"item_id": 1},
operation_map=fastapi_mcp.operation_map,
http_request_info=http_request_info,
)
except Exception:
pass
assert mock_request.called, "The _request method was not called"
if mock_request.called:
headers_arg = mock_request.call_args[0][4] # headers are the 5th argument
assert "authorization" in headers_arg
assert headers_arg["authorization"] == "Bearer token456"
@pytest.mark.asyncio
async def test_custom_header_passthrough_to_tool_handler(fastapi_mcp_with_custom_header: FastApiMCP):
from unittest.mock import patch, MagicMock
from fastapi_mcp.types import HTTPRequestInfo
# Test with custom header "X-Custom-Header"
with patch.object(fastapi_mcp_with_custom_header, "_request") as mock_request:
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.text = '{"result": "success"}'
mock_response.json.return_value = {"result": "success"}
mock_request.return_value = mock_response
http_request_info = HTTPRequestInfo(
method="POST",
path="/test",
headers={"X-Custom-Header": "MyValue123"},
cookies={},
query_params={},
body=None,
)
try:
# Call the _execute_api_tool method directly
# We don't care if it succeeds, just that _request gets the right headers
await fastapi_mcp_with_custom_header._execute_api_tool(
client=fastapi_mcp_with_custom_header._http_client,
tool_name="get_item",
arguments={"item_id": 1},
operation_map=fastapi_mcp_with_custom_header.operation_map,
http_request_info=http_request_info,
)
except Exception:
pass
assert mock_request.called, "The _request method was not called"
if mock_request.called:
headers_arg = mock_request.call_args[0][4] # headers are the 5th argument
assert "X-Custom-Header" in headers_arg
assert headers_arg["X-Custom-Header"] == "MyValue123"
@pytest.mark.asyncio
async def test_context_extraction_in_tool_handler(fastapi_mcp: FastApiMCP):
"""Test that handle_call_tool extracts HTTP request info from MCP context."""
from unittest.mock import patch, MagicMock
import mcp.types as types
from mcp.server.lowlevel.server import request_ctx
# Create a fake HTTP request object with headers
fake_http_request = MagicMock()
fake_http_request.method = "POST"
fake_http_request.url.path = "/test"
fake_http_request.headers = {"Authorization": "Bearer token-123", "X-Custom": "custom-value-123"}
fake_http_request.cookies = {}
fake_http_request.query_params = {}
# Create a fake request context containing the HTTP request
fake_request_context = MagicMock()
fake_request_context.request = fake_http_request
# Test with authorization header extraction from context
token = request_ctx.set(fake_request_context)
try:
with patch.object(fastapi_mcp, "_execute_api_tool") as mock_execute:
mock_execute.return_value = [types.TextContent(type="text", text="success")]
# Create a CallToolRequest like the MCP protocol would
call_request = types.CallToolRequest(
method="tools/call", params=types.CallToolRequestParams(name="get_item", arguments={"item_id": 1})
)
try:
# Call the tool handler directly like the MCP server would
await fastapi_mcp.server.request_handlers[types.CallToolRequest](call_request)
except Exception:
pass
assert mock_execute.called, "The _execute_api_tool method was not called"
if mock_execute.called:
# Verify that HTTPRequestInfo was extracted from context and passed to _execute_api_tool
http_request_info = mock_execute.call_args.kwargs["http_request_info"]
assert http_request_info is not None, "HTTPRequestInfo should be extracted from context"
assert http_request_info.method == "POST"
assert http_request_info.path == "/test"
assert "Authorization" in http_request_info.headers
assert http_request_info.headers["Authorization"] == "Bearer token-123"
assert "X-Custom" in http_request_info.headers
assert http_request_info.headers["X-Custom"] == "custom-value-123"
finally:
# Clean up the context variable
request_ctx.reset(token)
# Test with missing request context (should still work but with None)
with patch.object(fastapi_mcp, "_execute_api_tool") as mock_execute:
mock_execute.return_value = [types.TextContent(type="text", text="success")]
call_request = types.CallToolRequest(
method="tools/call", params=types.CallToolRequestParams(name="get_item", arguments={"item_id": 1})
)
try:
await fastapi_mcp.server.request_handlers[types.CallToolRequest](call_request)
except Exception:
pass
assert mock_execute.called, "The _execute_api_tool method was not called"
if mock_execute.called:
# Verify that HTTPRequestInfo is None when context is not available
http_request_info = mock_execute.call_args.kwargs["http_request_info"]
assert http_request_info is None, "HTTPRequestInfo should be None when context is not available"
================================================
FILE: tests/test_openapi_conversion.py
================================================
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
import mcp.types as types
from fastapi_mcp.openapi.convert import convert_openapi_to_mcp_tools
from fastapi_mcp.openapi.utils import (
clean_schema_for_display,
generate_example_from_schema,
get_single_param_type_from_schema,
)
def test_simple_app_conversion(simple_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=simple_fastapi_app.title,
version=simple_fastapi_app.version,
openapi_version=simple_fastapi_app.openapi_version,
description=simple_fastapi_app.description,
routes=simple_fastapi_app.routes,
)
tools, operation_map = convert_openapi_to_mcp_tools(openapi_schema)
assert len(tools) == 6
assert len(operation_map) == 6
expected_operations = ["list_items", "get_item", "create_item", "update_item", "delete_item", "raise_error"]
for op in expected_operations:
assert op in operation_map
for tool in tools:
assert isinstance(tool, types.Tool)
assert tool.name in expected_operations
assert tool.description is not None
assert tool.inputSchema is not None
def test_complex_app_conversion(complex_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
tools, operation_map = convert_openapi_to_mcp_tools(openapi_schema)
expected_operations = ["list_products", "get_product", "create_order", "get_customer"]
assert len(tools) == len(expected_operations)
assert len(operation_map) == len(expected_operations)
for op in expected_operations:
assert op in operation_map
for tool in tools:
assert isinstance(tool, types.Tool)
assert tool.name in expected_operations
assert tool.description is not None
assert tool.inputSchema is not None
def test_describe_full_response_schema(simple_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=simple_fastapi_app.title,
version=simple_fastapi_app.version,
openapi_version=simple_fastapi_app.openapi_version,
description=simple_fastapi_app.description,
routes=simple_fastapi_app.routes,
)
tools_full, _ = convert_openapi_to_mcp_tools(openapi_schema, describe_full_response_schema=True)
tools_simple, _ = convert_openapi_to_mcp_tools(openapi_schema, describe_full_response_schema=False)
for i, tool in enumerate(tools_full):
assert tool.description is not None
assert tools_simple[i].description is not None
tool_desc = tool.description or ""
simple_desc = tools_simple[i].description or ""
assert len(tool_desc) >= len(simple_desc)
if tool.name == "delete_item":
continue
assert "**Output Schema:**" in tool_desc
if "**Output Schema:**" in simple_desc:
assert len(tool_desc) > len(simple_desc)
def test_describe_all_responses(complex_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
tools_all, _ = convert_openapi_to_mcp_tools(openapi_schema, describe_all_responses=True)
tools_success, _ = convert_openapi_to_mcp_tools(openapi_schema, describe_all_responses=False)
create_order_all = next(t for t in tools_all if t.name == "create_order")
create_order_success = next(t for t in tools_success if t.name == "create_order")
assert create_order_all.description is not None
assert create_order_success.description is not None
all_desc = create_order_all.description or ""
success_desc = create_order_success.description or ""
assert "400" in all_desc
assert "404" in all_desc
assert "422" in all_desc
assert all_desc.count("400") >= success_desc.count("400")
def test_schema_utils():
schema = {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}},
},
"required": ["id", "name"],
"additionalProperties": False,
"x-internal": "Some internal data",
}
cleaned = clean_schema_for_display(schema)
assert "required" in cleaned
assert "properties" in cleaned
assert "type" in cleaned
example = generate_example_from_schema(schema)
assert "id" in example
assert "name" in example
assert "tags" in example
assert isinstance(example["id"], int)
assert isinstance(example["name"], str)
assert isinstance(example["tags"], list)
assert get_single_param_type_from_schema({"type": "string"}) == "string"
assert get_single_param_type_from_schema({"type": "array", "items": {"type": "string"}}) == "array"
array_schema = {"type": "array", "items": {"type": "string", "enum": ["red", "green", "blue"]}}
array_example = generate_example_from_schema(array_schema)
assert isinstance(array_example, list)
assert len(array_example) > 0
assert isinstance(array_example[0], str)
def test_parameter_handling(complex_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
tools, operation_map = convert_openapi_to_mcp_tools(openapi_schema)
list_products_tool = next(tool for tool in tools if tool.name == "list_products")
properties = list_products_tool.inputSchema["properties"]
assert "product_id" not in properties # This is from get_product, not list_products
assert "category" in properties
assert properties["category"].get("type") == "string" # Enum converted to string
assert "description" in properties["category"]
assert "Filter by product category" in properties["category"]["description"]
assert "min_price" in properties
assert properties["min_price"].get("type") == "number"
assert "description" in properties["min_price"]
assert "Minimum price filter" in properties["min_price"]["description"]
if "minimum" in properties["min_price"]:
assert properties["min_price"]["minimum"] > 0 # gt=0 in Query param
assert "in_stock_only" in properties
assert properties["in_stock_only"].get("type") == "boolean"
assert properties["in_stock_only"].get("default") is False # Default value preserved
assert "page" in properties
assert properties["page"].get("type") == "integer"
assert properties["page"].get("default") == 1 # Default value preserved
if "minimum" in properties["page"]:
assert properties["page"]["minimum"] >= 1 # ge=1 in Query param
assert "size" in properties
assert properties["size"].get("type") == "integer"
if "minimum" in properties["size"] and "maximum" in properties["size"]:
assert properties["size"]["minimum"] >= 1 # ge=1 in Query param
assert properties["size"]["maximum"] <= 100 # le=100 in Query param
assert "tag" in properties
assert properties["tag"].get("type") == "array"
required = list_products_tool.inputSchema.get("required", [])
assert "page" not in required # Has default value
assert "category" not in required # Optional parameter
assert "list_products" in operation_map
assert operation_map["list_products"]["path"] == "/products"
assert operation_map["list_products"]["method"] == "get"
get_product_tool = next(tool for tool in tools if tool.name == "get_product")
get_product_props = get_product_tool.inputSchema["properties"]
assert "product_id" in get_product_props
assert get_product_props["product_id"].get("type") == "string" # UUID converted to string
assert "description" in get_product_props["product_id"]
get_customer_tool = next(tool for tool in tools if tool.name == "get_customer")
get_customer_props = get_customer_tool.inputSchema["properties"]
assert "fields" in get_customer_props
assert get_customer_props["fields"].get("type") == "array"
if "items" in get_customer_props["fields"]:
assert get_customer_props["fields"]["items"].get("type") == "string"
def test_request_body_handling(complex_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
create_order_route = openapi_schema["paths"]["/orders"]["post"]
original_request_body = create_order_route["requestBody"]["content"]["application/json"]["schema"]
original_properties = original_request_body.get("properties", {})
tools, operation_map = convert_openapi_to_mcp_tools(openapi_schema)
create_order_tool = next(tool for tool in tools if tool.name == "create_order")
properties = create_order_tool.inputSchema["properties"]
assert "customer_id" in properties
assert "items" in properties
assert "shipping_address_id" in properties
assert "payment_method" in properties
assert "notes" in properties
for param_name in ["customer_id", "items", "shipping_address_id", "payment_method", "notes"]:
if "description" in original_properties.get(param_name, {}):
assert "description" in properties[param_name]
assert properties[param_name]["description"] == original_properties[param_name]["description"]
for param_name in ["customer_id", "items", "shipping_address_id", "payment_method", "notes"]:
assert properties[param_name]["title"] == param_name
for param_name in ["customer_id", "items", "shipping_address_id", "payment_method", "notes"]:
if "default" in original_properties.get(param_name, {}):
assert "default" in properties[param_name]
assert properties[param_name]["default"] == original_properties[param_name]["default"]
required = create_order_tool.inputSchema.get("required", [])
assert "customer_id" in required
assert "items" in required
assert "shipping_address_id" in required
assert "payment_method" in required
assert "notes" not in required # Optional in OrderRequest
assert properties["items"].get("type") == "array"
if "items" in properties["items"]:
item_props = properties["items"]["items"]
assert item_props.get("type") == "object"
if "properties" in item_props:
assert "product_id" in item_props["properties"]
assert "quantity" in item_props["properties"]
assert "unit_price" in item_props["properties"]
assert "total" in item_props["properties"]
for nested_param in ["product_id", "quantity", "unit_price", "total"]:
assert "title" in item_props["properties"][nested_param]
# Check if the original nested schema had descriptions
original_item_schema = original_properties.get("items", {}).get("items", {}).get("properties", {})
if "description" in original_item_schema.get(nested_param, {}):
assert "description" in item_props["properties"][nested_param]
assert (
item_props["properties"][nested_param]["description"]
== original_item_schema[nested_param]["description"]
)
assert "create_order" in operation_map
assert operation_map["create_order"]["path"] == "/orders"
assert operation_map["create_order"]["method"] == "post"
def test_missing_type_handling(complex_fastapi_app: FastAPI):
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
# Remove the type field from the product_id schema
params = openapi_schema["paths"]["/products/{product_id}"]["get"]["parameters"]
for param in params:
if param.get("name") == "product_id" and "schema" in param:
param["schema"].pop("type", None)
break
tools, operation_map = convert_openapi_to_mcp_tools(openapi_schema)
get_product_tool = next(tool for tool in tools if tool.name == "get_product")
get_product_props = get_product_tool.inputSchema["properties"]
assert "product_id" in get_product_props
assert get_product_props["product_id"].get("type") == "string" # Default type applied
def test_body_params_descriptions_and_defaults(complex_fastapi_app: FastAPI):
"""
Test that descriptions and defaults from request body parameters
are properly transferred to the MCP tool schema properties.
"""
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
order_request_schema = openapi_schema["components"]["schemas"]["OrderRequest"]
order_request_schema["properties"]["customer_id"]["description"] = "Test customer ID description"
order_request_schema["properties"]["payment_method"]["description"] = "Test payment method description"
order_request_schema["properties"]["notes"]["default"] = "Default order notes"
item_schema = openapi_schema["components"]["schemas"]["OrderItem"]
item_schema["properties"]["product_id"]["description"] = "Test product ID description"
item_schema["properties"]["quantity"]["default"] = 1
tools, _ = convert_openapi_to_mcp_tools(openapi_schema)
create_order_tool = next(tool for tool in tools if tool.name == "create_order")
properties = create_order_tool.inputSchema["properties"]
assert "description" in properties["customer_id"]
assert properties["customer_id"]["description"] == "Test customer ID description"
assert "description" in properties["payment_method"]
assert properties["payment_method"]["description"] == "Test payment method description"
assert "default" in properties["notes"]
assert properties["notes"]["default"] == "Default order notes"
if "items" in properties:
assert properties["items"]["type"] == "array"
assert "items" in properties["items"]
item_props = properties["items"]["items"]["properties"]
assert "description" in item_props["product_id"]
assert item_props["product_id"]["description"] == "Test product ID description"
assert "default" in item_props["quantity"]
assert item_props["quantity"]["default"] == 1
def test_body_params_edge_cases(complex_fastapi_app: FastAPI):
"""
Test handling of edge cases for body parameters, such as:
- Empty or missing descriptions
- Missing type information
- Empty properties object
- Schema without properties
"""
openapi_schema = get_openapi(
title=complex_fastapi_app.title,
version=complex_fastapi_app.version,
openapi_version=complex_fastapi_app.openapi_version,
description=complex_fastapi_app.description,
routes=complex_fastapi_app.routes,
)
order_request_schema = openapi_schema["components"]["schemas"]["OrderRequest"]
if "description" in order_request_schema["properties"]["customer_id"]:
del order_request_schema["properties"]["customer_id"]["description"]
if "type" in order_request_schema["properties"]["notes"]:
del order_request_schema["properties"]["notes"]["type"]
item_schema = openapi_schema["components"]["schemas"]["OrderItem"]
if "properties" in item_schema["properties"]["total"]:
del item_schema["properties"]["total"]["properties"]
tools, _ = convert_openapi_to_mcp_tools(openapi_schema)
create_order_tool = next(tool for tool in tools if tool.name == "create_order")
properties = create_order_tool.inputSchema["properties"]
assert "customer_id" in properties
assert "title" in properties["customer_id"]
assert properties["customer_id"]["title"] == "customer_id"
assert "notes" in properties
assert "type" in properties["notes"]
assert properties["notes"]["type"] in ["string", "object"] # Default should be either string or object
if "items" in properties:
item_props = properties["items"]["items"]["properties"]
assert "total" in item_props
================================================
FILE: tests/test_sse_mock_transport.py
================================================
import pytest
import uuid
from uuid import UUID
from unittest.mock import AsyncMock, MagicMock, patch
from fastapi import HTTPException, Request
from mcp.shared.message import SessionMessage
from pydantic import ValidationError
from anyio.streams.memory import MemoryObjectSendStream
from fastapi_mcp.transport.sse import FastApiSseTransport
from mcp.types import JSONRPCMessage, JSONRPCError
@pytest.fixture
def mock_transport() -> FastApiSseTransport:
# Initialize transport with a mock endpoint
transport = FastApiSseTransport("/messages")
transport._read_stream_writers = {}
return transport
@pytest.fixture
def valid_session_id():
session_id = uuid.uuid4()
return session_id
@pytest.fixture
def mock_writer():
return AsyncMock(spec=MemoryObjectSendStream)
@pytest.mark.anyio
async def test_handle_post_message_missing_session_id(mock_transport: FastApiSseTransport) -> None:
"""Test handling a request with a missing session_id."""
# Create a mock request with no session_id
mock_request = MagicMock(spec=Request)
mock_request.query_params = {}
# Check that the function raises HTTPException with the correct status code
with pytest.raises(HTTPException) as excinfo:
await mock_transport.handle_fastapi_post_message(mock_request)
assert excinfo.value.status_code == 400
assert "session_id is required" in excinfo.value.detail
@pytest.mark.anyio
async def test_handle_post_message_invalid_session_id(mock_transport: FastApiSseTransport) -> None:
"""Test handling a request with an invalid session_id."""
# Create a mock request with an invalid session_id
mock_request = MagicMock(spec=Request)
mock_request.query_params = {"session_id": "not-a-valid-uuid"}
# Check that the function raises HTTPException with the correct status code
with pytest.raises(HTTPException) as excinfo:
await mock_transport.handle_fastapi_post_message(mock_request)
assert excinfo.value.status_code == 400
assert "Invalid session ID" in excinfo.value.detail
@pytest.mark.anyio
async def test_handle_post_message_session_not_found(
mock_transport: FastApiSseTransport, valid_session_id: UUID
) -> None:
"""Test handling a request with a valid session_id that doesn't exist."""
# Create a mock request with a valid session_id
mock_request = MagicMock(spec=Request)
mock_request.query_params = {"session_id": valid_session_id.hex}
# The session_id is valid but not in the transport's writers
with pytest.raises(HTTPException) as excinfo:
await mock_transport.handle_fastapi_post_message(mock_request)
assert excinfo.value.status_code == 404
assert "Could not find session" in excinfo.value.detail
@pytest.mark.anyio
async def test_handle_post_message_validation_error(
mock_transport: FastApiSseTransport, valid_session_id: UUID, mock_writer: AsyncMock
) -> None:
"""Test handling a request with invalid JSON that causes a ValidationError."""
# Set up the mock transport with a valid session
mock_transport._read_stream_writers[valid_session_id] = mock_writer
# Create a mock request with valid session_id but invalid body
mock_request = MagicMock(spec=Request)
mock_request.query_params = {"session_id": valid_session_id.hex}
mock_request.body = AsyncMock(return_value=b'{"invalid": "json"}')
# Mock BackgroundTasks
with patch("fastapi_mcp.transport.sse.BackgroundTasks") as MockBackgroundTasks:
mock_background_tasks = MockBackgroundTasks.return_value
# Call the function
response = await mock_transport.handle_fastapi_post_message(mock_request)
# Verify response and background task setup
assert response.status_code == 400
assert "error" in response.body.decode() if isinstance(response.body, bytes) else False
assert mock_background_tasks.add_task.called
assert response.background == mock_background_tasks
@pytest.mark.anyio
async def test_handle_post_message_general_exception(
mock_transport: FastApiSseTransport, valid_session_id: UUID, mock_writer: AsyncMock
) -> None:
"""Test handling a request that causes a general exception during body processing."""
# Set up the mock transport with a valid session
mock_transport._read_stream_writers[valid_session_id] = mock_writer
# Create a mock request that raises an exception when body is accessed
mock_request = MagicMock(spec=Request)
mock_request.query_params = {"session_id": valid_session_id.hex}
# Instead of mocking the body method to raise an exception,
# we'll patch the body method to return a normal value and then
# patch JSONRPCMessage.model_validate_json to raise the exception
mock_request.body = AsyncMock(return_value=b'{"jsonrpc": "2.0", "method": "test", "id": "1"}')
# Mock the model_validate_json method to raise an Exception
with patch("mcp.types.JSONRPCMessage.model_validate_json", side_effect=Exception("Test exception")):
# Check that the function raises HTTPException with the correct status code
with pytest.raises(HTTPException) as excinfo:
await mock_transport.handle_fastapi_post_message(mock_request)
assert excinfo.value.status_code == 400
assert "Invalid request body" in excinfo.value.detail
@pytest.mark.anyio
async def test_send_message_safely_with_validation_error(
mock_transport: FastApiSseTransport, mock_writer: AsyncMock
) -> None:
"""Test sending a ValidationError message safely."""
# Create a minimal validation error manually instead of using from_exception_data
mock_validation_error = MagicMock(spec=ValidationError)
mock_validation_error.__str__.return_value = "Mock validation error" # type: ignore
# Call the function
await mock_transport._send_message_safely(mock_writer, mock_validation_error)
# Verify that the writer.send was called with a JSONRPCError
assert mock_writer.send.called
sent_message = mock_writer.send.call_args[0][0]
assert isinstance(sent_message, SessionMessage)
assert isinstance(sent_message.message, JSONRPCMessage)
assert isinstance(sent_message.message.root, JSONRPCError)
assert sent_message.message.root.error.code == -32700 # Parse error code
@pytest.mark.anyio
async def test_send_message_safely_with_jsonrpc_message(
mock_transport: FastApiSseTransport, mock_writer: AsyncMock
) -> None:
"""Test sending a JSONRPCMessage safely."""
# Create a JSONRPCMessage
message = SessionMessage(
JSONRPCMessage.model_validate({"jsonrpc": "2.0", "id": "123", "method": "test_method", "params": {}})
)
# Call the function
await mock_transport._send_message_safely(mock_writer, message)
# Verify that the writer.send was called with the message
assert mock_writer.send.called
sent_message = mock_writer.send.call_args[0][0]
assert sent_message == message
@pytest.mark.anyio
async def test_send_message_safely_exception_handling(
mock_transport: FastApiSseTransport, mock_writer: AsyncMock
) -> None:
"""Test exception handling when sending a message."""
# Set up the writer to raise an exception
mock_writer.send.side_effect = Exception("Test exception")
# Create a message
message = SessionMessage(
JSONRPCMessage.model_validate({"jsonrpc": "2.0", "id": "123", "method": "test_method", "params": {}})
)
# Call the function - it should not raise an exception
await mock_transport._send_message_safely(mock_writer, message)
# Verify that the writer.send was called
assert mock_writer.send.called
================================================
FILE: tests/test_sse_real_transport.py
================================================
import anyio
import multiprocessing
import socket
import time
import os
import signal
import atexit
import sys
import threading
import coverage
from typing import AsyncGenerator, Generator
from fastapi import FastAPI
from mcp.client.session import ClientSession
from mcp.client.sse import sse_client
from mcp import InitializeResult
from mcp.types import EmptyResult, CallToolResult, ListToolsResult
import pytest
import httpx
import uvicorn
from fastapi_mcp import FastApiMCP
HOST = "127.0.0.1"
SERVER_NAME = "Test MCP Server"
def run_server(server_port: int, fastapi_app: FastAPI) -> None:
# Initialize coverage for subprocesses
cov = None
if "COVERAGE_PROCESS_START" in os.environ:
cov = coverage.Coverage(source=["fastapi_mcp"])
cov.start()
# Create a function to save coverage data at exit
def cleanup():
if cov:
cov.stop()
cov.save()
# Register multiple cleanup mechanisms to ensure coverage data is saved
atexit.register(cleanup)
# Setup signal handler for clean termination
def handle_signal(signum, frame):
cleanup()
sys.exit(0)
signal.signal(signal.SIGTERM, handle_signal)
# Backup thread to ensure coverage is written if process is terminated abruptly
def periodic_save():
while True:
time.sleep(1.0)
if cov:
cov.save()
save_thread = threading.Thread(target=periodic_save)
save_thread.daemon = True
save_thread.start()
# Configure the server
mcp = FastApiMCP(
fastapi_app,
name=SERVER_NAME,
description="Test description",
)
mcp.mount_sse()
# Start the server
server = uvicorn.Server(config=uvicorn.Config(app=fastapi_app, host=HOST, port=server_port, log_level="error"))
server.run()
# Give server time to start
while not server.started:
time.sleep(0.5)
# Ensure coverage is saved if exiting the normal way
if cov:
cov.stop()
cov.save()
@pytest.fixture(params=["simple_fastapi_app", "simple_fastapi_app_with_root_path"])
def server(request: pytest.FixtureRequest) -> Generator[str, None, None]:
# Ensure COVERAGE_PROCESS_START is set in the environment for subprocesses
coverage_rc = os.path.abspath(".coveragerc")
os.environ["COVERAGE_PROCESS_START"] = coverage_rc
# Get a free port
with socket.socket() as s:
s.bind((HOST, 0))
server_port = s.getsockname()[1]
# Use fork method to avoid pickling issues
ctx = multiprocessing.get_context("fork")
# Run the server in a subprocess
fastapi_app = request.getfixturevalue(request.param)
proc = ctx.Process(
target=run_server,
kwargs={"server_port": server_port, "fastapi_app": fastapi_app},
daemon=True,
)
proc.start()
# Wait for server to be running
max_attempts = 20
attempt = 0
while attempt < max_attempts:
try:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
s.connect((HOST, server_port))
break
except ConnectionRefusedError:
time.sleep(0.1)
attempt += 1
else:
raise RuntimeError(f"Server failed to start after {max_attempts} attempts")
# Return the server URL
yield f"http://{HOST}:{server_port}{fastapi_app.root_path}"
# Signal the server to stop - added graceful shutdown before kill
try:
proc.terminate()
proc.join(timeout=2)
except (OSError, AttributeError):
pass
if proc.is_alive():
proc.kill()
proc.join(timeout=2)
if proc.is_alive():
raise RuntimeError("server process failed to terminate")
@pytest.fixture()
async def http_client(server: str) -> AsyncGenerator[httpx.AsyncClient, None]:
async with httpx.AsyncClient(base_url=server) as client:
yield client
@pytest.mark.anyio
async def test_raw_sse_connection(http_client: httpx.AsyncClient, server: str) -> None:
"""Test the SSE connection establishment simply with an HTTP client."""
from urllib.parse import urlparse
parsed_url = urlparse(server)
root_path = parsed_url.path
messages_path = f"{root_path}/sse/messages/" if root_path else "/sse/messages/"
async with anyio.create_task_group():
async def connection_test() -> None:
async with http_client.stream("GET", "/sse") as response:
assert response.status_code == 200
assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
line_number = 0
async for line in response.aiter_lines():
if line_number == 0:
assert line == "event: endpoint"
elif line_number == 1:
assert line.startswith(f"data: {messages_path}?session_id=")
else:
return
line_number += 1
# Add timeout to prevent test from hanging if it fails
with anyio.fail_after(3):
await connection_test()
@pytest.mark.anyio
async def test_sse_basic_connection(server: str) -> None:
async with sse_client(server + "/sse") as streams:
async with ClientSession(*streams) as session:
# Test initialization
result = await session.initialize()
assert isinstance(result, InitializeResult)
assert result.serverInfo.name == SERVER_NAME
# Test ping
ping_result = await session.send_ping()
assert isinstance(ping_result, EmptyResult)
@pytest.mark.anyio
async def test_sse_tool_call(server: str) -> None:
async with sse_client(server + "/sse") as streams:
async with ClientSession(*streams) as session:
await session.initialize()
tools_list_result = await session.list_tools()
assert isinstance(tools_list_result, ListToolsResult)
assert len(tools_list_result.tools) > 0
tool_call_result = await session.call_tool("get_item", {"item_id": 1})
assert isinstance(tool_call_result, CallToolResult)
assert not tool_call_result.isError
assert tool_call_result.content is not None
assert len(tool_call_result.content) > 0
================================================
FILE: tests/test_types_validation.py
================================================
import pytest
from pydantic import ValidationError
from fastapi import Depends
from fastapi_mcp.types import (
OAuthMetadata,
AuthConfig,
)
class TestOAuthMetadata:
def test_non_empty_lists_validation(self):
for field in [
"scopes_supported",
"response_types_supported",
"grant_types_supported",
"token_endpoint_auth_methods_supported",
"code_challenge_methods_supported",
]:
with pytest.raises(ValidationError, match=f"{field} cannot be empty"):
OAuthMetadata(
issuer="https://example.com",
authorization_endpoint="https://example.com/auth",
token_endpoint="https://example.com/token",
**{field: []},
)
def test_authorization_endpoint_required_for_authorization_code(self):
with pytest.raises(ValidationError) as exc_info:
OAuthMetadata(
issuer="https://example.com",
token_endpoint="https://example.com/token",
grant_types_supported=["authorization_code", "client_credentials"],
)
assert "authorization_endpoint is required when authorization_code grant type is supported" in str(
exc_info.value
)
OAuthMetadata(
issuer="https://example.com",
token_endpoint="https://example.com/token",
authorization_endpoint="https://example.com/auth",
grant_types_supported=["client_credentials"],
)
def test_model_dump_excludes_none(self):
metadata = OAuthMetadata(
issuer="https://example.com",
authorization_endpoint="https://example.com/auth",
token_endpoint="https://example.com/token",
)
dumped = metadata.model_dump()
assert "registration_endpoint" not in dumped
class TestAuthConfig:
def test_required_fields_validation(self):
with pytest.raises(
ValidationError, match="at least one of 'issuer', 'custom_oauth_metadata' or 'dependencies' is required"
):
AuthConfig()
AuthConfig(issuer="https://example.com")
AuthConfig(
custom_oauth_metadata={
"issuer": "https://example.com",
"authorization_endpoint": "https://example.com/auth",
"token_endpoint": "https://example.com/token",
},
)
def dummy_dependency():
pass
AuthConfig(dependencies=[Depends(dummy_dependency)])
def test_client_id_required_for_setup_proxies(self):
with pytest.raises(ValidationError, match="'client_id' is required when 'setup_proxies' is True"):
AuthConfig(
issuer="https://example.com",
setup_proxies=True,
)
AuthConfig(
issuer="https://example.com",
setup_proxies=True,
client_id="test-client-id",
client_secret="test-client-secret",
)
def test_client_secret_required_for_fake_registration(self):
with pytest.raises(
ValidationError, match="'client_secret' is required when 'setup_fake_dynamic_registration' is True"
):
AuthConfig(
issuer="https://example.com",
setup_proxies=True,
client_id="test-client-id",
setup_fake_dynamic_registration=True,
)
AuthConfig(
issuer="https://example.com",
setup_proxies=True,
client_id="test-client-id",
client_secret="test-client-secret",
setup_fake_dynamic_registration=True,
)