FastMCP - FastAPI MCP Framework & Runner

fast-mcp

FastAPI ネイティブの Model Context Protocol（MCP）フレームワークです。ルートの自動反映、ASGI スコープのブリッジング、動的な段階的ツール検出、堅牢なエラーリカバリー、チャット内で操作できる MCP Apps（SEP-1865）を備えています。

---

主な機能

• ⚡ ハイブリッドなデュアル ASGI マウント： 標準 ASGI 経由で既存の任意の FastAPI インスタンスにプロセス内で直接マウントできます。外部プロキシも、停止しないサブプロセスも不要です。
• 🔌 ローカル stdio CLI ランナーとデスクトップ AI ブリッジ： fast-mcp stdio main:app または python -m fast_mcp stdio main:app を実行すると、ネットワーク設定なしで標準入出力パイプ経由でデスクトップ AI クライアント（Claude Desktop、Cursor）に接続できます。
• 🔍 ルートの反映： オプトインタグ（tags=["mcp"]）を設定すると、FastAPI エンドポイント、Pydantic モデル、ドキュメント文字列、パス／クエリ／本文のパラメーターが自動的に MCP ツールに変換されます。
• 🛠️ カスタム AI ツール（@mcp.tool）： 反映されたルートと並行して、AI 向けに調整された複合ツールを定義できます。スキーマとドキュメント文字列は自動的に抽出されます。
• 🔐 ASGI スコープのブリッジング： MCP ハンドシェイク中に取得されたクライアントの認証ヘッダー（Authorization: Bearer <token>、Cookie、API キー）をメモリー内の ASGI Request に引き継ぎます。コードを変更せずに、FastAPI の Depends() と Security() プロバイダーをネイティブに解決できます。
• 🧠 動的な段階的ツール検出： 段階的検出（dynamic_discovery=True）、メタツール search_tools(query: str)、依存関係ゼロの KeywordTagRouter により、エージェントのコンテキストウィンドウを保護します。
• 🛡️ 堅牢なエラーリカバリーと JSON の最小化： ルートの HTTPException と Pydantic の検証エラーを捕捉し、情報を含む CallToolResult(isError=True) レスポンスに変換します。これにより、プロトコルエラーを起こさずに LLM が自己修正できます。出力はデフォルトで、トークン効率に配慮したコンパクトな最小化 JSON となり、カスタムの @mcp.serializer 書式設定フックも利用できます。
• 🖥️ デュアル UI とチャット内 MCP Apps（SEP-1865）： /mcp/docs に埋め込み型ブラウザーインスペクターを備え、_meta.ui.resourceUri、組み込みの inspect() ツール、@mcp.app() デコレーターを介して、デスクトップ AI クライアント（Claude Desktop、Cursor、VS Code）内のチャットで操作できる iframe にネイティブ対応しています。

---

インストール

pip install mcp-fastapi

または uv を使います。

uv add mcp-fastapi

---

クイックスタート

from fastapi import FastAPI, Depends, Header, HTTPException
from pydantic import BaseModel, Field
from fast_mcp import FastMCP

app = FastAPI(title="Store API")
mcp = FastMCP(app=app, name="store-mcp")

# 1. Existing FastAPI route reflected automatically via tags=["mcp"]
class Product(BaseModel):
    id: int
    name: str
    price: float

@app.get("/products/{product_id}", tags=["mcp"])
async def get_product(product_id: int) -> Product:
    """Fetch product details by ID."""
    if product_id == 404:
        raise HTTPException(status_code=404, detail="Product not found")
    return Product(id=product_id, name="Smart Widget", price=29.99)

# 2. Custom AI tool with native dependency injection
def verify_token(authorization: str = Header(...)) -> str:
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="Invalid token")
    return authorization.split(" ")[1]

@mcp.tool(name="order_status", description="Check customer order status")
def check_order(order_id: str, user: str = Depends(verify_token)) -> dict:
    return {"order_id": order_id, "customer": user, "status": "Shipped"}

# 3. Mount MCP endpoints (/mcp/sse, /mcp/messages, /mcp/docs)
mcp.mount()

標準的な ASGI サーバーで実行します。

uvicorn main:app --reload

---

主な機能

1. ルートの反映

tags=["mcp"]（route_tag で設定可能）を付けたルートは、mcp.mount() の実行時に自動的に検査されます。

• エンドポイントのドキュメント文字列（Google、Sphinx、NumPy 形式）は、ツールの説明とパラメーターのドキュメントになります。
• Pydantic のリクエストモデル、クエリパラメーター、パス変数は、MCP の入力スキーマになります。
• タグのないエンドポイントは通常の HTTP ルートのままで、LLM に公開されることはありません。

@app.post("/items/create", tags=["mcp"])
async def create_item(item: ItemModel) -> ItemModel:
    """Create a new catalog item.

    Args:
        item: The catalog item specification.
    """
    return item

2. カスタム AI ツール（@mcp.tool）

専用の REST エンドポイントを必要としない、AI に特化したツールを登録できます。

# Bare decorator
@mcp.tool
def calculate_quote(quantity: int, discount: float = 0.0) -> float:
    return quantity * 100.0 * (1.0 - discount)

# Parameterized decorator
@mcp.tool(name="inventory_lookup", description="Lookup stock levels", tags=["inventory"])
async def check_inventory(sku: str) -> dict:
    return {"sku": sku, "in_stock": True, "count": 42}

3. ASGI スコープのブリッジとネイティブ認証

MCP クライアントの SSE ハンドシェイクまたはメッセージ投稿からの受信ヘッダー（Authorization: Bearer ...、Cookie、API キー）は、アクティブなリクエストコンテキストに取り込まれます。

from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()

@mcp.tool
async def user_profile(creds: HTTPAuthorizationCredentials = Depends(security)) -> dict:
    token = creds.credentials
    return {"user": "alice", "token_verified": True}

認証に失敗した場合やヘッダーが省略された場合、fast-mcp は発生した HTTPException(401) を CallToolResult(is_error=True) に変換します。これにより、トランスポートをクラッシュさせることなく、エージェントに対処可能な認証エラーが返されます。

4. 動的な段階的ツール検出

数百のエンドポイントを持つ大規模な FastAPI アプリケーションで、LLM のコンテキストウィンドウが肥大化するのを防ぎます。

mcp = FastMCP(
    app=app,
    dynamic_discovery=True,  # Or set dynamic_discovery_threshold=20
    baseline_tools=["search_tools", "get_system_status"],
    baseline_tag="baseline",
)

• 有効にすると、tools/list にはベースラインツールと search_tools(query: str) メタツールのみが公開されます。
• search_tools(query="invoice") を呼び出すと、プラグイン可能な ToolRouter（デフォルトでは、トークン化された名前、タグ、説明のランキングを使用する依存関係ゼロの KeywordTagRouter）が実行され、一致するツール定義が完全な JSON スキーマとともに返されます。

5. 堅牢なエラーのインターセプトとカスタムシリアライザー

• 例外の捕捉： HTTPException（400、404、422）と Pydantic の検証エラーは、明確で簡潔なメッセージとして isError=True を付けて返されます。
• 出力の最小化： レスポンスはコンパクトな最小化 JSON（{"id":1,"name":"widget"}）としてシリアライズされ、プロンプトトークンを節約します。
• カスタムシリアライザー： 戻り値の型を、用途に合わせた Markdown や要約に整形します。

class Report(BaseModel):
    title: str
    metrics: dict[str, int]

@mcp.serializer(Report)
def format_report(report: Report) -> str:
    md = f"### {report.title}\n"
    for k, v in report.metrics.items():
        md += f"- **{k}**: {v}\n"
    return md

6. デュアル UI：ブラウザーインスペクターとチャット内 MCP アプリ（SEP-1865）

埋め込み型ブラウザーインスペクター

任意のブラウザーで http://localhost:8000/mcp/docs を開くと、登録済みツールの確認、スキーマの表示、テスト呼び出しの対話的な実行ができます。外部の Node.js CLI は不要です。（FastMCP(app, enable_ui=False) で無効にできます）。

チャット内 MCP アプリ（SEP-1865）

最新のデスクトップ AI クライアント（Claude Desktop、Cursor、VS Code）で、リッチな対話型 HTML/JS ウィジェットを直接表示します。

# Built-in server inspector tool
# Agent calling `inspect()` receives an interactive iframe pointed to ui://fast-mcp/inspector

# Authoring custom in-chat widgets:
@mcp.app(
    name="dashboard",
    resource_uri="ui://store/dashboard",
    html="""
    <div style="font-family: sans-serif; padding: 1rem; border-radius: 8px; background: #f0f4f8;">
        <h2>Store Live Metrics</h2>
        <p>Active Users: <strong>1,420</strong></p>
    </div>
    """
)
def live_dashboard() -> str:
    return '<iframe src="ui://store/dashboard" width="100%" height="400"></iframe>'

7. ローカルの stdio CLI ランナーとデスクトップ AI ブリッジ

デスクトップ AI クライアント（Claude Desktop、Cursor）を、ネットワーク設定、ポート競合、外部プロキシを必要とせず、標準入力／出力（stdio）パイプ経由で FastAPI バックエンドまたは FastMCP インスタンスに直接接続します。

コマンドラインの使用方法

# Run stdio runner pointing to FastAPI app or FastMCP instance
fast-mcp stdio main:app

# Or via Python module invocation
python -m fast_mcp stdio main:app

# Target attribute defaults to 'app' or 'mcp' if omitted:
fast-mcp stdio main

# The 'stdio' subcommand can also be omitted as default:
fast-mcp main:app

Claude Desktop の設定（claude_desktop_config.json）

Claude Desktop が FastMCP サーバーを直接起動するように設定します。

{
  "mcpServers": {
    "my-fast-mcp-app": {
      "command": "fast-mcp",
      "args": ["stdio", "main:app"]
    }
  }
}

または、仮想環境を自動的に管理するために uv を使用します。

{
  "mcpServers": {
    "my-fast-mcp-app": {
      "command": "uv",
      "args": ["run", "fast-mcp", "stdio", "main:app"]
    }
  }
}

プログラムからの stdio ランナー

Python からプログラムで stdio モードを実行することもできます。

import asyncio
from fast_mcp import FastMCP, run_stdio

mcp = FastMCP(name="my-stdio-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    asyncio.run(run_stdio(mcp))

---

テストと検証

fast-mcp は httpx.AsyncClient と ASGITransport を使用して、ASGI プロトコルの境界をまたぐ外部動作を検証します。

# Run full test suite
pytest

# Run tests with coverage
pytest --cov=fast_mcp --cov-report=term-missing

---

仕様とアーキテクチャのドキュメント

• 対話型ドキュメントサイト
• AI エージェントのインデックス（llms.txt）
• 仕様：fast-mcp コアフレームワーク（V1）
• GLOSSARY.md
• ADR 0001：アーキテクチャの基盤とハイブリッドスコープ
• ADR 0002：デュアル UI、ASGI スコープのブリッジ、堅牢なエラー処理

---

ライセンス

MIT