Amazon Bedrock AgentCore Runtime でカスタム MCP プロキシサーバーをサーバーレス実行可能に
AWS は、Amazon Bedrock AgentCore Runtime上でカスタム MCP プロキシをサーバーレスで実行可能にし、既存のコンプライアンスロジックやオンプレミスシステムとの統合を容易にする新しいデプロイパターンを提供した。
キーポイント
MCP プロキシによるガバナンス強化
Model Context Protocol (MCP) を介して AI エージェントがツールと接続する際、入力値のサニタイズ、監査証跡の生成、機密データの赤化などの制御をプロトコル層で実施可能にする。
Lambda インターセプタとの比較と補完
既存の Lambda インターセプタに加え、内部ライブラリやオンプレミスシステムに密結合したカスタムロジックを再構築せずに再利用できるサーバーレス MCP プロキシのパターンを提案している。
AgentCore Runtime の機能
完全マネージドの計算環境として、自動スケーリング、CloudWatch および OpenTelemetry を活用した組み込み観測性を提供し、MCP サーバーをサーバーレスでデプロイする基盤となる。
ハイブリッド・マルチシステム対応
単一のシステムに依存しないスタンドアロンの MCP サーバーとして実行することで、複数のシステムやハイブリッド環境における制御の実装とポータビリティを向上させる。
影響分析・編集コメントを表示
影響分析
この発表は、エンタープライズ環境において AI エージェントと外部ツールの統合を安全かつ柔軟に行うための重要なインフラストラクチャの進化を示しています。特に、既存のコンプライアンスシステムや独自ロジックを大規模にリファクタリングせずに MCP プロトコル上に適用できる点は、実務における導入障壁を大幅に下げる画期的なアプローチです。これにより、AI エージェントの実運用におけるガバナンスとセキュリティがより現実的なレベルで強化されるでしょう。
編集コメント
Lambda インターセプタが主流となる中で、既存資産の流用やハイブリッド環境対応を可能にする「MCP プロキシ」という別解を示した点は、実務家の視点から非常に価値が高いです。特に大規模組織におけるセキュリティ要件との親和性を高める技術として注目されます。
AI エージェントが Model Context Protocol (MCP) を通じてツールに接続すると、データベースクエリや API 呼び出しからファイル操作、サードパーティ製サービスとの統合に至るまで、多様な機能へのアクセスが可能になります。本番環境では、これらの相互作用には組織のセキュリティポリシーに合致した適切なガバナンス、制御、および観測性が求められます。これには、バックエンドシステムに到達する前にツール入力をサンitize（清浄化）することや、特定の形式で監査証跡を生成すること、プロトコル層で機密データをマスキングすることが含まれます。これらの要件は、内部のガバナンス基準、業界規制、および各本番環境の具体的な状況によって形成されます。この記事では、これらの制御を実装するためのプログラム可能なレイヤーを提供する Amazon Bedrock AgentCore Runtime 上でサーバーレス MCP プロキシを展開する方法をご紹介します。
Amazon Bedrock AgentCore Gateway は、エージェント・ツールの統合に対する集中管理ガバナンスと制御を提供します。これにはセマンティックツールディスカバリ、管理された認証情報、ポリシーの強制が含まれます。ゲートウェイ要求パスにカスタムロジックを組み込む必要がある組織の場合、Gateway は Lambda インターセプタ をサポートしています。これらのインターセプタを使用すると、AWS Lambda 関数としてツール呼び出しごとに検証、変換、またはフィルタリングコードを実行できます。これにより、カスタムロジックを Gateway 設定と併せて自己完結型かつ管理された状態に保つことができます。
しかし、一部の組織は、内部ライブラリやオンプレミスのコンプライアンスシステムと密結合したカスタム MCP フィルタリングロジックに投資しています。彼らは、それを Lambda 関数へリファクタリングすることなく、AgentCore Runtime でそのロジックを再利用したいと考えています。また、他の組織は複数のシステムやハイブリッド環境で運用しており、スタンドアロン型の MCP サーバーとして制御を実行する方が、システム固有のインターセプタよりも移植性が高いと判断しています。このようなケースでは、AgentCore Runtime 上で動作するサーバーレス MCP プロキシが補完的なパターンを提供できます。
AgentCore Runtime は、AI エージェントや MCP サーバーをデプロイするための完全に管理されたコンピューティング環境です。自動スケーリング機能を備えたサーバーレスインフラストラクチャを提供し、Amazon CloudWatch や OpenTelemetry を通じて組み込みの観測性（Observability）を実現します。また、認証と認可には AgentCore Identity を利用できます。Runtime は MCP プロトコルをネイティブにサポートしているため、MCP サーバー、特に MCP トラフィックにカスタム制御を追加する MCP プロキシのホスティングも可能です。
ここでは、MCP トラフィックにプログラム可能な制御を追加できるステートレスな MCP プロキシを AgentCore Runtime で構築・デプロイする方法をご紹介します。このプロキシは Runtime 上でサーバーレスワークロードとして実行され、起動時にアップストリームの MCP サーバーからツールを検出し、カスタムロジックを適用した上で再公開し、リクエストを透過的に転送します。アップストリームとなる MCP サーバーには、AgentCore Runtime で動作する MCP サーバー、セルフホスト型の MCP サーバー、サードパーティ製の MCP サービスなど、お好みの MCP 互換エンドポイントを選択できます。また、このプロキシを Amazon Bedrock AgentCore Gateway に接続することも可能です。これにより、MCP サーバー、Lambda 関数、SaaS 統合全体にわたる Gateway の管理されたツール発見機能、認証情報管理、ポリシー適用の利点を活用できるようになります。
オープンソースの GitHub 実装を基盤として、アーキテクチャの概要を解説し、各レイヤーにおける認証の仕組みを説明します。また、自動化スクリプトによるプロキシのデプロイ方法と、サンプルエージェントを用いたエンドツーエンドフローのテスト手順も紹介します。これにより、AgentCore Runtime を活用して MCP トラフィックにカスタム制御を追加するための動作可能なデプロイパターンが完成します。
ソリューション概要
カスタム MCP プロキシは AgentCore Runtime で実行され、MCP クライアントとアップストリーム MCP サーバーの仲介役として機能します。MCP クライアントは、他の MCP サーバーと同様にプロキシと対話しますが、プロキシが専用のロジックを適用してリクエストをアップストリームサーバーへ転送します。この分離により、アップストリームの MCP サーバーやクライアントを変更することなく、プロトコルレイヤーでカスタム制御を導入することが可能になります。
アーキテクチャコンポーネント
本ソリューションは、MCP を介して連携する 3 つの論理的レイヤーから構成されます。すなわち、MCP クライアント、AgentCore Runtime 上の MCP プロキシ、そしてアップストリーム MCP サーバーです。リクエストフローはこの各レイヤーを順次通過します。具体的には、クライアントが MCP リクエストをプロキシに送信し、プロキシがカスタムロジックを適用してリクエストをアップストリーム MCP サーバーへ転送し、アップストリームサーバーがリクエストを処理した上で、同じ経路を通じてレスポンスを返却します。
アップストリーム MCP サーバーは、AgentCore Runtime 上、自社インフラ上、またはサードパーティサービスとして、あらゆる場所にホストできます。本稿では、事前用意された MCP 互換ツールエンドポイント（登録済みターゲット付き）を提供し、別途 MCP サーバーを構築することなくウォークスルーを最初から最後まで実行できるようにするため、アップストリーム MCP サーバーとして AgentCore Gateway を使用します。このプロキシパターンは他の MCP 互換アップストリームエンドポイントにも適用可能であり、本稿全体を通じて代替案についても議論します。これには、AgentCore Runtime 上で動作するアップストリーム MCP サーバーも含まれます。
以下の図は、リクエストフローと認証フローの両方を含むアーキテクチャを示しています：
図 1: リクエストフローと認証フローを示すアーキテクチャ図。本ウォークスルーでは、アップストリーム MCP サーバーとして AgentCore Gateway を使用します。
Runtime 内の MCP クライアントは、カスタム MCP プロキシをツールサーバーとして扱い、標準的な MCP リクエストを送信してツールの発見と呼び出しを行います。クライアントの視点からは、プロキシは他の MCP サーバーと区別がつきません。AgentCore Runtime は、クライアントワークロードに対して管理されたコンピューティング、自動スケーリング、組み込みの観測機能を提供します。
MCP プロキシは、クライアントとアップストリーム MCP サーバーの間の仲介役として機能します。クライアントから MCP リクエストを受け取り、カスタムロジックを適用した上で、そのリクエストをアップストリームサーバーへ転送します。このプロキシは、クライアント自体と同じサーバーレス管理インフラストラクチャを使用して、Runtime 内で独立した MCP サーバーとして実行されます。
プロキシは標準的な MCP クライアントとしてアップストリーム MCP サーバーに接続します。アップストリームサーバーは、プロキシを他の承認された呼び出し元と区別されない認証済み MCP クライアントとして扱います。ダウンストリームサービスや MCP ツールへのアクセス管理は、アップストリームサーバーが担当します。
ツール自体は、MCP サーバーとしてホストされている場合も、AWS Lambda 関数の場合も、サードパーティの SaaS 統合である場合も、すべてアップストリームサーバーに登録され、同サーバーによって管理されます。ツール統合への完全マネージド型パスを求める組織にとって、AgentCore Gateway は、開発者が大規模にツールを構築・デプロイ・発見・接続するための、シンプルで安全な手段を提供します。
MCP プロキシの動作原理
私たちは FastMCP を用いてプロキシを実装しており、起動時にアップストリーム MCP サーバーからツールをディスカバリーし、ランタイム時にはすべてのクライアントリクエストを転送します。このプロキシは独自のツールを定義しておらず、アップストリームサーバーが何を提供しているかについて事前知識を持ちません。
プロキシプロセスが起動すると、アップストリームサーバーに対して標準的な MCP tools/list リクエストが送信されます。サーバーは利用可能なツールの完全なカタログを返します。各ツールについて、プロキシは同じ名前と説明を持つローカルの FastMCP ツールを動的に登録します。各ツールは、tools/call リクエストをアップストリームサーバーに転送し、そのレスポンスを返すハンドラ関数によってバックされています。プロキシに接続する MCP クライアントは、同じツールカタログを確認でき、アップストリームサーバーに直接接続した場合と同じ結果を得ることができます。
プロキシはあなたが所有しデプロイする標準的な Python MCP サーバーであるため、ツール呼び出しを転送する前やレスポンスを受信した後に、カスタムロジックを挿入することができます。アップストリームサーバーがツールの実行を担当する一方、プロキシはそのネイティブ機能を置き換えることなく、前方にプログラム可能なレイヤーを追加します。
コンポーネント間の認証
認証はアーキテクチャの各層で独立して強制され、フロー全体を通じて明確な信頼境界が作成されます。
- エージェントから MCP プロキシへ：エージェントが MCP プロキシに接続する際、AgentCore Identity を用いて認証と認可が行われます。プロキシは、AgentCore Identity が提供する機能を利用します。これには、エージェント ID の一元管理や安全な資格情報の保存などが含まれます。どのエージェントやプリンシパルがプロキシを呼び出せるかは、AgentCore Runtime 内の他のワークロードで使用するのと同じアイデンティティ・フレームワークを通じて制御できます。
- プロキシからアップストリーム MCP サーバーへ：プロキシは、接続先のアップストリーム MCP サーバーに対して認証を行う必要があります。認証方法は、アップストリームのサーバー要件に依存します。AgentCore Identity は、AWS Identity and Access Management (IAM) を用いた AWS Signature Version 4 (SigV4) および OAuth 2.0 クライアント資格情報に基づく JSON Web Token (JWT) 形式の認可を通じて、AgentCore Runtime でホストされるワークロードに対するインバウンド認可を提供します。JWT ベースの認可を使用する場合、アップストリームサーバーにはディスカバリ URL、許可されたオーディエンス、および許可されたクライアントを設定します。AgentCore Identity は、すべてのリクエストにおいてベアラー・トークンを検証します。プロキシは OAuth 2.0 クライアント資格情報付与を通じてトークンを取得し、Authorization: Bearer ヘッダーとして含めます。
IAM ベースの認可の場合、プロキシは AgentCore Runtime から継承した IAM 実行ロールを用いて AWS SigV4 でリクエストに署名します。具体的な権限はアップストリームサーバーの種類によって異なります。アップストリームの MCP サーバーが AgentCore Runtime でホストされている場合、bedrock-agentcore:InvokeAgentRuntime 権限をスコープ指定して、どの呼び出し元がアクセスできるかを制御します。あるいは、このウォークスルーのようにアップストリームサーバーが AgentCore Gateway の場合、bedrock-agentcore:InvokeGateway 権限を特定のゲートウェイと呼び出し元の ID にスコープ指定します。これにより、信頼されたプロキシのみがツールカタログにアクセスできるようになります。
添付の GitHub プロジェクトでは、デフォルトの認証方式として IAM ベースの認可が使用されています。また、デプロイメントスクリプトでも、この統合に対して JWT ベースの認可をサポートしています。
- ツールへのアップストリームサーバー：アップストリームの MCP サーバーは、AgentCore Identity 資格情報プロバイダーを使用してダウンストリームのツールに認証を行います。これにより、OAuth 2.0 トークン、API キー、および資格情報のローテーションが透過的に管理されます。アウトバウンドの認可動作は、リクエストがプロキシから発信された場合でも、直接クライアントから発信された場合でも同じように機能します。
このアーキテクチャにおける各レイヤーは独立して認証を行います。カスタムロジックは、プロキシを介して MCP プロトコル層で注入されながら、アップストリームサーバーは引き続きツールの実行と独自の認可処理を担当します。その結果、カスタムの制御機能とアップストリームの機能が、それぞれ明確に定義された別々のレイヤーで動作するアーキテクチャが実現されます。
前提条件
本ソリューションを実装するには、以下の要件を満たす必要があります：
- Python 3.12 以降がインストールされた Linux または macOS の開発環境。ローカルマシンまたはクラウドインスタンスのいずれでも構いません。
- AWS Command Line Interface (AWS CLI) がインストールされ、IAM ロールの作成、Amazon Elastic Container Registry (Amazon ECR) との連携、および Amazon Bedrock AgentCore API の呼び出し権限を持つ AWS Identity and Access Management (AWS IAM) プリンシパルの認証情報で設定されていること。AWS アカウントをお持ちでない場合は、「新しい Amazon Web Services アカウントを作成して有効にする方法」をご参照ください。
- 開発環境に AgentCore starter toolkit がインストールされていること。このツールは、エージェントをパッケージ化し、AgentCore Runtime にデプロイします。AgentCore starter toolkit をお持ちでない場合は、Python による Amazon Bedrock AgentCore starter toolkit の入門ガイドをご参照ください。
- 開発環境に Docker がインストールされていること。AgentCore CLI は、Docker を使用して AgentCore Runtime で実行されるコンテナイメージを構築します。
- プロキシが接続する先方の MCP サーバーエンドポイント。本ウォークスルーでは、少なくとも 1 つのターゲットが登録された Amazon Bedrock AgentCore Gateway を使用します。AgentCore Gateway をお持ちでない場合は、「Amazon Bedrock AgentCore ゲートウェイの作成」をご参照ください。ゲートウェイ作成後に Gateway の MCP エンドポイント URL をメモしてください。この URL を使用してプロキシを設定します。
- （先方のサーバーが OAuth によるインバウンド認証を使用している場合）ドメインと、クライアントシークレットを持つクライアント資格証明グラントを使用するアプリクライアントが設定された Amazon Cognito ユーザープール。AgentCore starter toolkit を使用して OAuth 認証付きでゲートウェイを作成した場合、これらのリソースはゲートウェイ作成時に自動的にプロビジョニングされます。
ソリューションのデプロイ
AWS アカウント内でプロジェクトをデプロイするには、以下の手順を実行してください：
- GitHub リポジトリをクローンし、プロジェクトの構造を確認することから始めます。
- deploy_config.json を開き、環境に応じた値を設定してください。図 2：デプロイ設定を示す構成スクリーンショット。gateway_endpoint の値を、アップストリーム MCP サーバー（この例では AgentCore Gateway）の MCP エンドポイント URL に置き換えてください。region は、アップストリームサーバーがデプロイされている AWS リージョンに設定します。gateway_api_id フィールドはオプションです。アップストリームサーバーが AgentCore Gateway であり、その Amazon Resource Name (ARN) を提供する場合、デプロイスクリプトはその特定のリソースに対して IAM 権限をスコープします。これを null のままにすると、スクリプトはアカウント内のすべてのゲートウェイを呼び出す権限を付与します。auth_mode フィールドは、プロキシがアップストリームサーバーに認証する方式を決定し、IAM ベースの認証の場合はデフォルトで "iam" となります。OAuth ベースの認証のために auth_mode を "jwt" に設定する場合、Cognito ユーザープールから取得した値（cognito_user_pool_id、cognito_client_id、および cognito_domain）を Cognito フィールドに設定する必要があります。その後、デプロイスクリプトを実行する際に --cognito-client-secret フラグを通じて Cognito クライアントシークレットを渡します。IAM 認証を使用する場合は、すべての Cognito フィールドを null のままにしてください。
- プロジェクトのルートから自動化されたデプロイスクリプト setup_and_deploy.py を実行します。このスクリプトは、以下の手順を順次実行して完全なデプロイワークフローを自動化します：
前提条件の検証 — AWS CLI、Python、Docker が利用可能であり、AWS 認証情報が設定されていることを確認します。
- IAM 実行ロールの作成 — bedrock-agentcore.amazonaws.com が引き受けることを許可する信頼ポリシーを持つロールを作成します。このロールには、ゲートウェイの呼び出し権限、Amazon CloudWatch Logs への書き込み権限、および Amazon ECR からのイメージプル権限が含まれます。
- AgentCore CLI を使用したエージェントの設定 — MCP プロトコルで agentcore configure を実行し、mcp_proxy/main.py にあるプロキシのエントリーポイントにポイントを合わせます。このステップでは、CLI は ECR リポジトリの選択と認証モードの確認を求めます。
- エージェントを AgentCore Runtime へ起動 — agentcore launch を実行し、アップストリームサーバーのエンドポイントを環境変数 (GATEWAY_ENDPOINT) として渡します。AgentCore Runtime はコンテナイメージを構築し、Amazon ECR にプッシュしてエージェントを開始します。
- MCP プロキシエージェントのステータスを確認します：agentcore status --agent mcp_proxy。出力からエージェント ARN をメモしてください。この ARN は後でプロキシを呼び出すテストクライアントエージェントで使用します。
プロキシ認証方法の構成方法
MCP プロキシとアップストリームサーバー間の認証モードは、アップストリームサーバーへのインバウンド承認がどのように設定されているかによって異なります。AgentCore Identity は、AgentCore にホストされたワークロードに対して IAM および JWT の両方のインバウンド認証をサポートしています。GitHub 上のプロキシコードは、アップストリームサーバーへのアウトバウンド HTTP コールが行われる単一の関数 _send_gateway_request 内で各モードを実装しています。
IAM 承認
プロキシは AWS SigV4 を使用して、アップストリームサーバーへのすべてのアウトバウンドリクエストに署名します。プロキシは AgentCore Runtime で実行されるため、デプロイ時に指定した IAM 実行ロールを継承します。デプロイスクリプトはこのロールに <co
原文を表示
When AI agents connect to tools through the Model Context Protocol (MCP), they gain access to capabilities that range from database queries and API calls to file operations and third-party service integrations. In production, these interactions need proper governance, controls, and observability aligned with an organization’s security policies. This includes sanitizing tool inputs before they reach backend systems, generating audit trails in specific formats, or redacting sensitive data at the protocol layer. These requirements are shaped by internal governance standards, industry regulations, and the specifics of each production environment. This post shows you how to deploy a serverless MCP proxy on Amazon Bedrock AgentCore Runtime that gives you a programmable layer to implement these controls.
Amazon Bedrock AgentCore Gateway provides centralized governance and control for agent-tool integration, including semantic tool discovery, managed credentials, and policy enforcement. For organizations that need to embed custom logic in the Gateway request path, Gateway supports Lambda interceptors. These interceptors let you run validation, transformation, or filtering code as AWS Lambda functions on every tool invocation. This allows you to keep your custom logic self-contained and managed alongside your Gateway configuration.
However, some organizations have invested in custom MCP filtering logic that is tightly coupled with internal libraries or on-premises compliance systems. They want to reuse that logic on AgentCore Runtime without refactoring it into Lambda functions. Others operate across multiple systems or hybrid environments where running controls as a standalone MCP server offers more portability than a system-specific interceptor. In these cases, a serverless MCP proxy running on AgentCore Runtime can provide a complementary pattern.
AgentCore Runtime is a fully managed compute environment for deploying AI agents and MCP servers. It provides serverless infrastructure with automatic scaling, built-in observability through Amazon CloudWatch and OpenTelemetry, and AgentCore Identity for authentication and authorization. Because Runtime natively supports the MCP protocol, it allows you to host MCP servers, including MCP proxies that add custom controls to MCP traffic.
We show you how to build and deploy a stateless MCP proxy on AgentCore Runtime that allows you to add programmable controls to MCP traffic. The proxy runs as a serverless workload on Runtime, discovers tools from an upstream MCP server at startup, re-exposes them with your custom logic applied, and forwards requests transparently. The upstream MCP server can be your choice of MCP-compatible endpoint, including MCP servers running on AgentCore Runtime, self-hosted MCP servers, or third-party MCP services. You can also connect this proxy to Amazon Bedrock AgentCore Gateway. This lets you take advantage of Gateway’s managed tool discovery, credential management, and policy enforcement across MCP servers, Lambda functions, and SaaS integrations.
Using an open source GitHub implementation as a foundation, we walk you through the architecture, explain how authorization works at each layer, deploy the proxy with an automated script, and test the end-to-end flow with a sample agent. By the end, you have a working deployment pattern for adding custom controls to MCP traffic using AgentCore Runtime.
Solution overview
The custom MCP proxy runs on AgentCore Runtime and acts as an intermediary between MCP clients and upstream MCP servers. MCP clients interact with the proxy as they would with other MCP servers; the proxy applies your specialized logic and forwards requests to the upstream server. This separation allows you to introduce custom controls at the protocol layer without modifying the upstream MCP server or the client.
Architecture components
The solution involves three logical layers that work together through MCP: the MCP client, the MCP proxy on AgentCore Runtime, and the upstream MCP server. The request flow moves through these layers sequentially: the client sends MCP requests to the proxy, the proxy applies your custom logic and forwards the request to the upstream MCP server, and the upstream server processes the request and returns the response back through the same path.
The upstream MCP server can be hosted anywhere, including on AgentCore Runtime, on your own infrastructure, or as a third-party service. In this post, we use an AgentCore Gateway as the upstream MCP server because it provides a ready-made, MCP-compatible tool endpoint with registered targets, letting you follow the walkthrough end-to-end without standing up a separate MCP server. The proxy pattern applies to other MCP-compatible upstream endpoints, and we discuss alternatives throughout the post, including upstream MCP servers running on AgentCore Runtime.
The following diagram shows the architecture, including both the request and authentication flows:
Figure 1: Architecture diagram showing the request and authentication flows. This walkthrough uses AgentCore Gateway as the upstream MCP server.
The MCP client in Runtime treats the custom MCP proxy as its tool server, sending standard MCP requests to discover and invoke tools. From the client’s perspective, the proxy is indistinguishable from other MCP servers. AgentCore Runtime provides managed compute, automatic scaling, and built-in observability for the client workload.
The MCP proxy acts as an intermediary between the client and the upstream MCP server. It receives MCP requests from the client, applies your custom logic, and forwards the requests to the upstream server. The proxy runs as a separate MCP server in Runtime, using the same serverless managed infrastructure as the client itself.
The proxy connects to the upstream MCP server as a standard MCP client. The upstream server treats the proxy as an authenticated MCP client, no different from other authorized callers. The upstream server handles access to downstream services and MCP tools.
The tools themselves, whether hosted as MCP servers, AWS Lambda functions, or third-party SaaS integrations, are registered with and managed by the upstream server. For organizations looking for a fully managed path to tool integration, AgentCore Gateway provides a straightforward and secure way for developers to build, deploy, discover, and connect to tools at scale.
How the MCP proxy works
We implement the proxy using FastMCP to discover tools from the upstream MCP server at startup and forward every client request at runtime. The proxy does not define tools of its own and has no prior knowledge of what the upstream server exposes.
When the proxy process starts, it sends a standard MCP tools/list request to the upstream server. The server returns the full catalog of available tools. For each tool, the proxy dynamically registers a local FastMCP tool with the same name and description. Each tool is backed by a handler function that forwards tools/call requests to the upstream server and returns the response. MCP clients connecting to the proxy see the same tool catalog and get the same results as if they were connecting to the upstream server directly.
Because the proxy is a standard Python MCP server that you own and deploy, you can insert custom logic before forwarding a tool call or after receiving the response. The upstream server handles tool execution, while the proxy adds a programmable layer in front without replacing the upstream server’s native capabilities.
Authorization between components
Authorization is enforced independently at each layer of the architecture, creating distinct trust boundaries throughout the flow.
- Agent to MCP proxy: When an agent connects to the MCP proxy, it uses AgentCore Identity for authentication and authorization. The proxy uses the capabilities that AgentCore Identity provides, including centralized management of agent identities and secure credentials storage. You control which agents and principals can invoke the proxy using the same identity framework you use for your other workloads in AgentCore Runtime.
- Proxy to upstream MCP server: The proxy must authenticate to the upstream MCP server it connects to. The authentication method depends on the upstream server’s requirements. AgentCore Identity provides inbound authorization for workloads hosted on AgentCore Runtime through both AWS Identity and Access Management (IAM) using AWS Signature Version 4 (SigV4) and JSON Web Token (JWT)-based authorization using OAuth 2.0 client credentials. With JWT-based authorization, you configure the upstream server with a discovery URL, allowed audiences, and allowed clients. AgentCore Identity validates the bearer token on every request. The proxy obtains tokens through the OAuth 2.0 client credentials grant and includes them as Authorization: Bearer headers.
For IAM-based authorization, the proxy signs requests using AWS SigV4 with the IAM execution role it inherits from AgentCore Runtime. The specific permissions differ by upstream server type. If the upstream MCP server is hosted on AgentCore Runtime, you scope the bedrock-agentcore:InvokeAgentRuntime permission to control which callers can reach it. Alternatively, if the upstream server is an AgentCore Gateway, as in this walkthrough, you scope the bedrock-agentcore:InvokeGateway permission to specific gateways and caller identities. This ensures that only trusted proxies can access the tool catalog.
The accompanying GitHub project uses IAM-based authorization as the default method. The deployment script also supports JWT-based authorization for this integration.
- Upstream server to tools: The upstream MCP server authenticates to downstream tools using AgentCore Identity credential providers, which manage OAuth 2.0 tokens, API keys, and credential rotation transparently. Outbound authorization operates the same way regardless of whether requests originate from the proxy or from a direct client.
Each layer in this architecture authenticates independently. You inject custom logic at the MCP protocol layer through the proxy, while the upstream server continues to handle tool execution and its own authorization. The result is an architecture where custom controls and upstream capabilities operate in separate, well-defined layers.
Prerequisites
To implement the solution, you must have the following:
- A Linux or macOS development environment with Python 3.12 or later installed. It can be a local machine or a cloud instance.
- AWS Command Line Interface (AWS CLI) installed and configured with credentials for an AWS Identity and Access Management (AWS IAM) principal that has permissions to create IAM roles, interact with Amazon Elastic Container Registry (Amazon ECR), and invoke Amazon Bedrock AgentCore APIs. If you don’t have an AWS account, refer to How do I create and activate a new Amazon Web Services account?
- The AgentCore starter toolkit installed on your development environment. This tool packages and deploys agents to AgentCore Runtime. If you don’t have the AgentCore starter toolkit, refer to Get started with the Amazon Bedrock AgentCore starter toolkit in Python.
- Docker installed on your development environment. The AgentCore CLI uses Docker to build the container image that runs on AgentCore Runtime.
- An upstream MCP server endpoint that the proxy will connect to. In this walkthrough, we use an Amazon Bedrock AgentCore Gateway with at least one target registered. If you don’t have an AgentCore Gateway, refer to Create an Amazon Bedrock AgentCore gateway. Note the Gateway MCP endpoint URL after creation. You use this URL to configure the proxy.
- (If your upstream server uses OAuth inbound authorization) An Amazon Cognito user pool with a configured domain and an app client that uses the client credentials grant with a client secret. If you created your Gateway using the AgentCore starter toolkit with OAuth authorization, these resources are provisioned automatically during Gateway creation.
Deploy the solution
Complete the following steps to deploy the project in your AWS account:
- Start by cloning the GitHub repository and reviewing the project structure.
- Open deploy_config.json and set the values for your environment: Figure 2: Configuration screenshot showing deployment settingsReplace the value in gateway_endpoint with the MCP endpoint URL of your upstream MCP server (AgentCore Gateway in this example). Set region to the AWS Region where the upstream server is deployed. The gateway_api_id field is optional. If your upstream server is an AgentCore Gateway and you provide its Amazon Resource Name (ARN), the deployment script scopes the IAM permissions to that specific resource. If you leave it as null, the script grants permissions to invoke all Gateways in the account. The auth_mode field determines how the proxy authenticates to the upstream server and defaults to "iam" for IAM-based authentication. If you set auth_mode to "jwt" for OAuth-based authentication, you must configure the Cognito fields (cognito_user_pool_id, cognito_client_id, and cognito_domain) with values from your Cognito user pool. Then pass the Cognito client secret through the --cognito-client-secret flag when running the deploy script. When using IAM authentication, leave all Cognito fields as null.
- Run the automated deployment script setup_and_deploy.py, from the project root. It automates the full deployment workflow, which performs the following steps in sequence:
Validates prerequisites — checks that the AWS CLI, Python, and Docker are available, and that AWS credentials are configured.
- Creates an IAM execution role — creates a role with a trust policy that allows bedrock-agentcore.amazonaws.com to assume it. The role includes permissions for invoking the Gateway, writing to Amazon CloudWatch Logs, and pulling images from Amazon ECR.
- Configures the agent with the AgentCore CLI — runs agentcore configure with the MCP protocol, pointing to the proxy entrypoint at mcp_proxy/main.py. During this step, the CLI prompts you to select an ECR repository and confirm the authentication mode.
- Launches the agent to AgentCore Runtime — runs agentcore launch and passes the upstream server endpoint as an environment variable (GATEWAY_ENDPOINT). AgentCore Runtime builds the container image, pushes it to Amazon ECR, and starts the agent.
- Check the MCP proxy agent status: agentcore status --agent mcp_proxy. Note the agent ARN from the output. You use this ARN in the test client agent to later invoke the proxy.
How to configure the proxy authentication method
The authentication mode between the MCP proxy and the upstream server depends on how the inbound authorization to the upstream server is configured. AgentCore Identity supports both IAM and JWT inbound authentication for workloads hosted on AgentCore. The proxy code on GitHub implements each mode in a single function _send_gateway_request, where outbound HTTP calls to the upstream server are made.
IAM authorization
The proxy signs every outbound request to the upstream server using AWS SigV4. Because the proxy runs on AgentCore Runtime, it inherits the IAM execution role you specified during deployment. The deployment script grants this role <co
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み