Mcp Rest Sample

MCP Streamable HTTP を備えた FastAPI バックエンドテンプレート。

説明

このリポジトリは、次の両方を必要とするサービス向けの小規模なバックエンドテンプレートです。

• REST エンドポイントを介した人間／API クライアントからのアクセス
• MCP（Model Context Protocol）のツール、リソース、プロンプトを介したエージェントからのアクセス

このアプリは、1 つのモックドメインを両方のインターフェースで公開します。

• REST：/health、/projects、/projects/{project_id}、チケットのトリアージ、リリースノート
• MCP：Streamable HTTP を使用する /mcp。対応するプロジェクト／チケットのツールとリソースを提供します

モックデータは意図的にメモリ内に保持しています。REST と MCP の境界が明確になってから、データベースを追加してください。

MCP の状況

このテンプレートは MCP Python SDK v2 ベータ版と2026-07-28 リリース候補の方針を対象としています。つまり、次のとおりです。

• 主なトランスポートは Streamable HTTP です。
• このサンプルでは、/mcp はステートレスな HTTP です。
• v2 はまだプレリリースのため、SDK のバージョンを厳密に固定しています。
• これはテンプレートおよび学習用サンプルであり、MCP の本番環境での互換性を保証するものではありません。

認証ディスカバリー

このサンプルでは OAuth や OpenID Connect のディスカバリーを実装していません。一部の MCP クライアントは /mcp を呼び出す前に、次のような .well-known URL を確認する場合があります。

• /.well-known/oauth-protected-resource/mcp
• /mcp/.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server/mcp
• /.well-known/openid-configuration/mcp

このローカルサンプルでは、これらのリクエストが 404 Not Found を返すことがあります。/mcp への JSON-RPC リクエストが 200 OK または 202 Accepted を返す限り、これは想定どおりです。

これを認証付き HTTP MCP サーバーにするには、次を追加してください。

• MCP リソースサーバー向けの OAuth 2.0 保護リソースメタデータ。
• 認可サーバーメタデータ、または文書化された外部認可サーバー。
• 保護リソースメタデータをクライアントに案内する、401 Unauthorized レスポンスの WWW-Authenticate ヘッダー。
• MCP サーバーを対象とするトークンであることを確認する audience チェックを含む、すべての MCP HTTP リクエストでのベアラートークン検証。
• 匿名アクセス、無効なトークン、有効なトークン、メタデータディスカバリー、トークンの audience 不一致を対象とするテスト。

レイアウト

app/
  main.py              # FastAPI app and /mcp route wiring
  mcp_server.py        # MCP tools, resources, prompts
  schemas.py           # Pydantic request/response models
  config.py            # pydantic-settings config
  internal/
    catalog.py         # mock domain logic
  routers/
    health.py
    projects.py
  tests/

ローカルでの実行

cd app
uv sync --python 3.14 --prerelease allow
uv run uvicorn main:app --reload --host 127.0.0.1 --port 8001

次を開きます。

• REST ドキュメント：http://127.0.0.1:8001/docs
• MCP エンドポイント：http://127.0.0.1:8001/mcp

チェック

公開チェックを uv で直接実行します。

cd app
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest
uv audit

ロックファイルに対して実行する、最新の依存関係健全性チェック用コマンドとして uv audit を含めています。表示したままにしてください。ただし、上流のアドバイザリの提供状況と現在の uv のリリース状況は、運用上の状況として考慮してください。

主な注意事項

• REST／MCP レイヤーは薄く保ちます。トランスポート入力を検証し、内部ロジックを呼び出して、型付きモデルを返します。
• MCP で不可逆または破壊的な操作を実行する場合は慎重にしてください。
• 認証、データベース、バックグラウンド処理、外部クライアントは、それぞれ別のレイヤーとして追加してください。