MCP Server Auth Template

mcp-server-auth-template

ポルトガル語で読む

リモート MCP 向けの、本番環境を意識した OAuth 2.1 リソースサーバーのリファレンスです。Microsoft Entra ID と 汎用 OIDC、厳密なトークン／リソース検証、フェイルクローズの認可、段階的なスコープチャレンジ、 ステートレスな MCP 2026-07-28、メタデータのみの OpenTelemetry 証跡を備えています。

このリポジトリは、「MCP ツールを公開するにはどうすればよいか」ではなく、アイデンティティ、認可、トランスポート、可観測性の境界を弱めずに公開するにはどうすればよいかが課題となる場合に使用してください。このサーバーは mcp-client-auth-template と連携し、合成アイデンティティを使用し、本番用の認証情報を必要としない、実行可能なエンドツーエンドのリファレンスを提供します。

このリポジトリが実証すること

連携する実行可能なパスでは、設定上の主張ではなく、実際のリソースサーバーの動作を検証します。

• ✅ RFC 9728 Protected Resource Metadata がリソースサーバーによって公開されます
• ✅ RFC 8707 のリソースバインディングによって、JWT オーディエンスが厳密に制限されます
• ✅ 発行者、署名、有効期限、アルゴリズムと鍵の互換性、呼び出し元の種類がフェイルクローズで検証されます
• ✅ 委任されたスコープと Entra のアプリケーションロールは、別々の認可概念として扱われます
• ✅ 段階的な認可のため、ディスパッチ前に 403 insufficient_scope が返されます
• ✅ オーディエンスが誤ったトークンは 401 で拒否され、MCP SDK のデフォルトに依存しない明示的なトークンリソースポリシーが適用されます
• ✅ tools/list はプリンシパルごとにフィルタリングされ、範囲を限定した private キャッシュヒントのみを含みます
• ✅ 保護されたツールは、匿名でのカタログ検索時に表示されません
• ✅ MCP 2026-07-28 はステートレスで、Mcp-Session-Id を発行しません
• ✅ 汎用 OIDC と Microsoft Entra ID は、プロバイダー固有の情報を漏らさず、単一のアプリケーション境界を共有します
• ✅ W3C トレースコンテキストはサーバーに届きますが、OAuth／MCP の機密情報はテレメトリに含まれません
• ✅ リリース成果物、コンテナーの証跡、SBOM、来歴が実行可能なゲートで検証されます

連携する OAuth／MCP の動作を要件ごとに確認するには、明示的な証跡の不足点や MCP Authorization Interest Group／Tool Scopes Working Group 向けの議題も含む、認可実装者レポートをご覧ください。

アーキテクチャ

flowchart LR
    Client["MCP client"] -->|"OAuth 2.1 / OIDC"| AS["Authorization server<br/>Entra ID or generic OIDC"]
    Client -->|"MCP 2026-07-28<br/>resource-bound bearer"| Admission["Transport admission"]
    Admission --> AuthN["Token verification"]
    AuthN --> AuthZ["Tool authorization"]
    AuthZ --> Tools["MCP tools"]
    Server["This resource server"] --- Admission

    Server -->|"OIDC discovery + cached JWKS"| AS
    Server -.->|"W3C trace context + OTLP"| Collector["OpenTelemetry Collector"]
    Collector --> Tempo["Tempo"]
    Tempo --> Grafana["Grafana"]

認可サーバーは、ログイン、同意、クライアント登録、トークン発行を担当します。このリポジトリは保護対象リソースを担当し、トランスポートの受け入れ、メタデータの公開、アクセストークンの検証、リクエスト単位のプリンシパル構築、ツールの認可とディスパッチを行います。

各レイヤーの境界と認可シーケンスの詳細については、アーキテクチャをご覧ください。

5分間での検証

コンパニオンクライアントが、リポジトリをまたぐ実行可能なリファレンスフローを管理します。両方のリポジトリを兄弟ディレクトリとしてクローンしたら、このサーバーをソースから直接検証できます。

cd ../mcp-client-auth-template
./scripts/run_reference_demo.sh \
  --server-root ../mcp-server-auth-template

このフローでは、このチェックアウトから実際のサーバーを起動し、決定論的なローカル OIDC プロバイダーを使用して、CIMD を優先する Authorization Code + PKCE、認証済みの whoami、範囲を限定したスコープの段階的引き上げ、誤ったオーディエンスの拒否、およびステートレスな MCP の動作を検証します。

公開イメージを観測可能な状態で検証するには、次を実行します。

cd ../mcp-client-auth-template
./scripts/run_observability_demo.sh --keep

観測フローでは、クライアントとサーバーをまたぐ単一の分散トレース、Collector による肯定的な受信、Tempo からの取得、Grafana のプロビジョニング、およびテレメトリーのプライバシーに関するアサーションを検証します。

証拠の正確な範囲については、検証ガイドを参照してください。

視覚的な証拠

以下のターミナルでの実行証拠は、ソースレベルのペア型リファレンスフローから取得したものです。

トレースのスクリーンショットは、観測フローが正常に完了した際に取得したもので、mcp-server-auth-template のスパンに焦点を当てています。

認証プロファイル

プロファイル	想定用途	主な動作
Entra 委任	対話型のエンタープライズユーザー	scp、テナント／アプリケーション識別子、発行者、オーディエンス、サブジェクトを検証します
Entra アプリケーション	プロバイダー固有のアプリ専用デプロイ	idtyp=app を明示的に要求し、roles と委任スコープを分離します
汎用 OIDC 委任	標準ベースの対話型クライアント	発行者／オーディエンス／署名／有効期限と OAuth スコープを検証します
汎用 OIDC クライアント資格情報	決定論的なペアプロファイルでの無人サービス	事前登録されたマシントークンと段階的な OAuth スコープを受け入れます

MCP_SERVER_AUTH_PROVIDER=entra または generic を設定して、アダプターを切り替えます。サンプルの whoami ツールは検証済みの呼び出し元の ID を返します。health は追加の mcp:tools:health スコープを必要とし、ディスパッチ前の 403 insufficient_scope チャレンジを示します。

クイックスタート

前提条件：Python 3.13 または 3.14、および uv。

git clone https://github.com/brunovicco/mcp-server-auth-template.git
cd mcp-server-auth-template
cp .env.example .env
uv sync --frozen --all-groups
uv run uvicorn mcp_server_auth_template.entrypoints.mcp_server:create_app --factory --reload

.env の Entra または汎用 OIDC の設定ブロックを構成してから、MCP クライアントで http://localhost:8000/mcp を指定します。

エンドポイント	目的	認証
/mcp	MCP Streamable HTTP	Bearer トークン
/.well-known/oauth-protected-resource	認可サーバーの検出メタデータ	公開
/livez	プロセスの稼働状態	公開、最小限のレスポンス
/readyz	MCP のライフサイクル準備状態	公開、最小限のレスポンス

本番環境に近い形式で実行するには、次を実行します。

uv run python -m mcp_server_auth_template.entrypoints.serve

ループバックの外部にサービスを公開する前に、本番環境の運用を参照してください。

Official MCP Registry

このサーバーは Official MCP Registry に次の名前で公開されています。

io.github.brunovicco/[email protected]

server.json では、公開されている GHCR イメージを、実際の streamable-http トランスポートを使用する OCI パッケージとして記述しています。ホストされた remotes エンドポイントを提供するとは記載していません。公開は、セキュアなリリースパイプラインと、イミュータブルなイメージ、所有権メタデータ、および永続化された Registry のレスポンスを公開前に検証する専用の Registry ワークフローによって制御されています。

Official MCP Registry と 認可実装者レポートを参照してください。

セキュリティ特性

この実装は、意図的にフェイルクローズ方式を採用しています。

• 発行者と対象者の厳密な検証、上限を設けたクロックチェック、アルゴリズムと鍵の互換性確認、キャッシュされた JWKS の更新；
• 明示的な validate_token_resource=False ポリシー：プロバイダーの対象者（Entra API クライアント ID、api:// 識別子）はトークン検証器によって強制され、SDK の URL 文字列一致では検証されません（ADR-0027）；
• プリンシパルに依存する検出結果は、認可コンテキストをまたいで共有されません（ADR-0028）；
• 安全でないスキーム、リダイレクト、圧縮、過大なボディ、プライベート／予約済みの宛先、混在する DNS 応答、DNS リバインディングに対する、強化された検出／JWKS の外向き通信；
• 認証とツールのディスパッチに先立ち、Host、Origin、ヘッダー、エンベロープ、ボディサイズ、同時実行数を検査してリクエストを受け入れます；
• 委任 ID とアプリケーション ID は区別されます。拡張機能のネゴシエーションだけで認可が付与されることはありません；
• ベアラートークンとデコード済みクレームはリクエスト内でのみ使用され、ログへの記録や永続化は行われません；
• トレースには、認証情報、任意のヘッダーや URL、MCP 引数／結果、ボディ、バゲージ、例外テキストを含めません。

これは透明性のあるリファレンス実装であり、セキュリティ認証ではありません。この境界を適用する前に、プライバシーとデータの取り扱いと、docs/adr/ 以下のアーキテクチャ決定をお読みください。

MCP 2026-07-28

ベースライン：MCP 仕様 2026-07-28 および MCP Python SDK >=2.2,<3。

対になるテンプレートは、最新のステートレスプロファイルを実行可能な動作として実証します。

• server/discover とリクエストごとの _meta が、レガシーな initialize／initialized ハンドシェイクを使わずに、プロトコルバージョン、クライアント ID、機能を伝達します；
• 最新のリクエストでは MCP-Protocol-Version、Mcp-Method、Mcp-Name を使用します；
• レスポンスで Mcp-Session-Id は発行されません；
• Protected Resource Metadata によって認可サーバーの検出を行います；
• RFC 8707 の resource によって、アクセストークンの対象者を正確にバインドします；
• server/discover と tools/list が SEP-2549 のキャッシュヒント（ttlMs=30000、cacheScope=private）を含みます；
• 実行時の 403 insufficient_scope は、以前の許可を維持し、ディスパッチされていない操作の再試行を上限付きで 1 回だけ許可します；
• マシン間アクセスは io.modelcontextprotocol/oauth-client-credentials を通じたオプトイン方式です。

互換性と、対応するクライアントのリポジトリ間 E2E の証拠をご覧ください。

オブザーバビリティ

a2a-otel-kit は、MCP ASGI 境界で W3C トレースコンテキストを引き継ぎます。A2A_OTEL_ENABLED=true が設定され、完全な OTLP トレースエンドポイントが構成されていない限り、エクスポートによるネットワーク通信は発生しません。スパンにはメタデータのみが含まれ、強化された HTTP リクエスト受け入れ処理の内側、認証とツールのディスパッチの外側に配置されます。

LLM とアプリケーションのオブザーバビリティをご覧ください。

エンジニアリングの証拠

• lint、format、厳格な Mypy、アーキテクチャ、テスト／カバレッジ、Bandit、依存関係の監査、サプライチェーン管理、ガバナンス、ベンダー提供コントラクトの検証を対象とする、決定論的な品質ゲート；
• デフォルトで読み取り専用の権限を使用し、リリース権限を分離した、SHA 固定の GitHub Actions；
• CycloneDX のソース／ランタイムインベントリ、完全な脆弱性の証拠、フェイルクローズ方式の例外ポリシー；
• SHA-256 マニフェストと GitHub ビルド来歴を備えた、許可リスト方式のバイト単位で再現可能な Python リリース成果物；
• 不変のダイジェスト、来歴、SBOM 証明書を備えた、ポリシー承認済みの GHCR 公開；
• MCP SDK 2.2.0 および最新の互換性がある 2.x に対する Python 3.13／3.14 のテスト。MCP SDK の非推奨警告をテスト失敗に昇格させ、MCP 3 による破壊的変更を早期に検出します；
• ローカル鍵と合成 ID を使用したオフライン JWT フィクスチャ；
• セキュリティ、プロトコル、運用、互換性、オブザーバビリティ、サプライチェーンに関する決定を記録した ADR。

デモと本番環境の違い

参照実装の証拠	本番環境への導入
付属デモでの合成ローカル OIDC	登録と同意の審査を経たエンタープライズ認可サーバー
ループバック／ローカルの参照ネットワーク	TLS で保護されたサービスネットワークと、明示的なプロキシ管理
ローカルの Collector／Tempo／Grafana	組織が管理するテレメトリーパイプラインと保持ポリシー
合成署名鍵と ID	管理対象の鍵、シークレット、プロバイダー固有の制御
参照用の whoami／health ツール	明示的な認可ポリシーと副作用の制御を備えたドメインツール

参照設定は境界を示すものであり、本番環境のデフォルトではありません。

リポジトリの構成

src/                    resource-server implementation
tests/                  unit, contract and security evidence
scripts/                quality, governance and release automation
docs/                   architecture, operations, privacy and security
examples/                deployment/reference configuration
.github/workflows/      CI, compatibility and release workflows

ローカルのエディターおよびコーディングエージェントの状態は、意図的に公開リポジトリから除外されています。

ドキュメント

ドキュメント	用途
検証	ソースレベルおよび観測可能なペアでの証明
アーキテクチャ	コンテキスト、レイヤー、依存関係のルール、リクエストのシーケンス
互換性	サポート対象バージョンと実行可能なクライアント／サーバーの契約
運用	事前確認、プローブ、シャットダウン、コンテナー、Kubernetes
プライバシー	データの一覧、保持、ログ記録、トレース、外部プロセッサー
サプライチェーン	依存関係のポリシー、CI の信頼境界、脅威、例外
可観測性	OpenTelemetry とオプションの Langfuse 設定
開発	ローカル環境、チェック、コンテナーのワークフロー
アーキテクチャ上の決定	重要な決定の根拠とトレードオフ

テストと品質

uv lock --check
uv sync --frozen --all-groups
uv run pytest
uv run python scripts/quality_gate.py

品質ゲートが完了の定義です。リンティング、フォーマット、アーキテクチャ、厳密な型付け、テスト／カバレッジ、Bandit、依存関係の監査、サプライチェーン制御、ガバナンス、ベンダー提供の契約検証を対象としています。

対象範囲と本番環境への導入

このリポジトリは参照用テンプレートであり、ホスト型の ID サービスではありません。具体的なデプロイでは、TLS 終端、変更不可のイメージ公開、シークレットの配信、プロバイダー固有の登録、ネットワークポリシー、キャパシティプランニング、監視の管理責任、実際の IdP 検証を別途用意する必要があります。 チェックインされた .invalid および全ゼロの値はプレースホルダーであり、本番環境の事前確認で失敗します。

ライセンス

MIT