Amazon Bedrock AgentCore Runtime の「コードの直接デプロイ」で MCPサーバー が使えずにハマった話

はじめに

2025年11月に Amazon Bedrock AgentCore Runtime でコードの直接デプロイがサポートされました。Python ファイルや依存ライブラリを固めた zip ファイルをアップロードするだけでランタイムにデプロイできます。

「直接デプロイ」でデプロイして動かしてみると、エージェントに渡す MCPClient を作成する処理で FileNotFoundError: [Errno 2] No such file or directory: 'uvx' というエラーが出てハマったのでどのように解決したかを紹介します。

def setup_aws_documentation_client():
    return MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="uvx",
                args=["awslabs.aws-documentation-mcp-server@latest"],
            )
        )
    )

環境

• Python 3.12
• uv

調査

Get started with Amazon Bedrock AgentCore Runtime direct code deployment の 「Direct code deployment concepts」を見ると、Runtime の OS は Amazon Linux 2023 のようです。そして、Amazon Linux 2023 には uv は入っていなさそうです。

したがって、何らかの形で uv の実行可能ファイルを zip に含めてデプロイすればよさそうです。
以下のようにして依存ライブラリをダウンロードすると、deployment_package/bin配下に uv や uvx があったのでこれを使います。

# pyproject.toml に uv が追加される
uv add uv 

# deployment_package 配下に依存関係のファイルをダウンロード
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.12 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml

あとは Get started with Amazon Bedrock AgentCore Runtime direct code deployment の Step5 の手順に沿って zip ファイルを作成します。

cd deployment_package
zip -r ../deployment_package.zip .
cd ..
zip -r deployment_package.zip main.py

コード上では uvx ではなく bin/uvxと書く必要があります。

def setup_aws_documentation_client():
    return MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="bin/uvx",
                args=["awslabs.aws-documentation-mcp-server@latest"],
            )
        )
    )

まとめ

agentcore configure で Dockerfile を作った上でコンテナをデプロイする方式だと（ベースイメージがghcr.io/astral-sh/uv:python3.13-bookworm-slimなので当然ですが）何なく使えていたはずなので、ハマってしまいました。

• uv の実行可能ファイルを依存関係に含める
• コード上で参照するときは bin/uvx とする