Python MCP Server

大規模言語モデル（LLM）にコンテキストを提供するための Python Model Context Protocol (MCP) サーバーを生成し、オプションで Amazon Bedrock AgentCore にデプロイします。

MCP とは？

Model Context Protocol (MCP) は、AI アシスタントが外部ツールやリソースと対話できるようにするオープン標準です。LLM が以下を行うための一貫した方法を提供します：

アクションを実行したり情報を取得したりするツール（関数）を実行する
コンテキストやデータを提供するリソースにアクセスする

使用方法

MCP Server の生成

Python MCP サーバーは 2 つの方法で生成できます：

このジェネレーターを実行@aws/nx-plugin:py#mcp-server

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:py#mcp-server

$ yarn nx g @aws/nx-plugin:py#mcp-server

$ npx nx g @aws/nx-plugin:py#mcp-server

$ bunx nx g @aws/nx-plugin:py#mcp-server

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - py#mcp-server
必須パラメータを入力
クリック Generate

コマンドを組み立てる6

project必須

authinfra = agentcore | agentcore-ecr

iac

infra

name

preferInstallDependencies

true

--dry-run変更されるファイルを確認するためにドライランを実行することもできます

オプション

ジェネレーターオプション6 オプション

project必須string: MCP サーバーを追加するプロジェクト
authenuminfra = agentcore | agentcore-ecrデフォルト: iam: MCPサーバーへの認証に使用する方法。infraが設定されている場合にのみ適用されます（infraがnoneの場合は無視されます）。
iamcognito
iacenumデフォルト: inherit: 優先するIaCプロバイダー。デフォルトでは初期選択から継承されます。
inheritcdkterraform
infraenumデフォルト: agentcore: MCP サーバーをホストするインフラストラクチャのタイプ。agentcore は最速のビルドとデプロイサイクルのために、コードを zip として AgentCore 管理ランタイムにデプロイします。agentcore-ecr は OS レベルの制御や確立されたコンテナパイプラインのために、代わりにコンテナイメージをビルドしてホストします。ホスティングが不要な場合は none を選択してください。
agentcoreagentcore-ecrnone
namestring: MCP サーバーの名前（デフォルト: mcp-server）
preferInstallDependenciesbooleanデフォルト: true: ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、既存の Python プロジェクトに以下のファイルを追加します：

Directoryyour-project/
- Directoryyour_module/
  - Directorymcp_server/ (or custom name if specified)
    __init__.py Python package initialization
    server.py Main server definition with sample tools and resources
    stdio.py Entry point for STDIO transport, useful for simple local MCP servers
    http.py Entry point for Streamable HTTP transport, useful for hosting your MCP server
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with MCP dependencies
- project.json Updated with MCP server serve targets

インフラストラクチャ

infra オプションは、Amazon Bedrock AgentCore Runtime 上でコードをパッケージ化してホストする方法を選択します：

agentcore (デフォルト) は直接コードデプロイを使用します：ビルドされたコードは .zip としてパッケージ化され、S3 にアップロードされ、AgentCore が管理する言語ランタイム上で実行されます。コンテナイメージのビルド、ECR リポジトリの管理、イメージのプッシュが不要なため、ビルドとデプロイのサイクルが大幅に高速化されます。
agentcore-ecr は、提供される Dockerfile から arm64 コンテナイメージをビルドし、ワークスペース内の他のすべてのコンテナと並んで、共有 core/asset-ecr レジストリからホストします。オペレーティングシステムイメージを制御する必要がある場合（例えば、ネイティブシステムライブラリをインストールする場合）や、確立されたコンテナパイプラインがある場合に選択してください。このオプションは、Trivy イメージスキャンターゲットも提供します（下記の Image Scanning を参照）。
none はインフラストラクチャを一切生成しないため、プロジェクトはローカルでのみ実行できます。

このジェネレーターは、選択した iac に基づいてインフラストラクチャをコードとして提供するため、関連する CDK コンストラクトまたは Terraform モジュールを含む packages/common にプロジェクトを作成します。

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用のコンストラクト
    …
  - Directorycore/ app 内のコンストラクトによって再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用の Terraform モジュール
    …
  - Directorycore/ app 内のモジュールによって再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

MCP Server をデプロイするために、以下のファイルが生成されます：

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directorymcp-servers
    Directory<mcp-server-name>
    <mcp-server-name>.ts CDK construct for deploying your MCP Server

Directorypackages/common/terraform/src
- Directoryapp
  - Directorymcp-servers
    Directory<mcp-server-name>
    <mcp-server-name>.tf Module for deploying your MCP Server
- Directorycore
  - Directoryagent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - Directoryagent-core-code (when infra is agentcore)
    runtime.tf Packages your MCP Server’s code and delegates to agent-core
  - Directoryagent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your MCP Server’s image and delegates to agent-core

infra に none を選択した場合、CDK コンストラクトや Terraform モジュールは生成されません — MCP サーバーはローカルの STDIO / HTTP 使用のみに設定されます。認証するホストされたエンドポイントがないため、このモードでは auth オプションは無視されます。

アーキテクチャ

Bedrock AgentCore Runtime にデプロイされると、サーバーのコードは zip としてパッケージ化され、AgentCore マネージドランタイムで実行されます。AI アシスタントは AgentCore Runtime データプレーンエンドポイントを呼び出し、streamable HTTP transport を介して tools/* および resources/* の呼び出しをサーバーに転送します。

Loading the diagram…

infra: agentcore-ecr の場合、MCP サーバーはコンテナイメージにビルドされ、Amazon ECR にプッシュされ、AgentCore Runtime で実行されます。これにより、ランタイム環境に対する OS レベルの制御が可能になりますが、上記の zip パッケージングよりもビルドとデプロイのサイクルが長くなります。

Loading the diagram…

infra: none の場合、AWS インフラストラクチャは生成されません。MCP サーバーはローカルの STDIO および HTTP トランスポート専用に構成され、同じマシン上で実行されている AI アシスタントによって使用されます。

Loading the diagram…

MCP Server の操作

ツールの追加

ツールは、AI アシスタントがアクションを実行するために呼び出すことができる関数です。Python MCP サーバーは MCP Python SDK (FastMCP) ライブラリを使用しており、デコレーターベースのシンプルなアプローチでツールを定義できます。

server.py ファイルに新しいツールを追加できます：

@mcp.tool(description="Your tool description")
def your_tool_name(param1: str, param2: int) -> str:
    """Tool implementation with type hints"""
    # Your tool logic here
    return f"Result: {param1} with {param2}"

FastMCP ライブラリは以下を自動的に処理します：

関数の型ヒントに基づく型検証
MCP プロトコル用の JSON スキーマ生成
エラーハンドリングとレスポンスのフォーマット

リソースの追加

リソースは AI アシスタントにコンテキストを提供します。@mcp.resource デコレーターを使用してリソースを追加できます：

@mcp.resource("example://static-resource", description="Static resource example")
def static_resource() -> str:
    """Return static content"""
    return "This is static content that provides context to the AI"

@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
def dynamic_resource(item_id: str) -> str:
    """Return dynamic content based on parameters"""
    # Fetch data based on item_id
    data = fetch_data_for_item(item_id)
    return f"Dynamic content for {item_id}: {data}"

AI アシスタントとの設定

設定ファイル

MCP をサポートするほとんどの AI アシスタントは、同様の設定アプローチを使用します。MCP サーバーの詳細を含む設定ファイルを作成または更新する必要があります：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "my_module.mcp_server.stdio"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/your/project/.venv"
      }
    }
  }
}

アシスタント固有の設定

特定の AI アシスタントで MCP を設定するには、以下のドキュメントを参照してください：

MCP Server の実行

ローカル開発

MCP サーバー（およびローカルデータベースなど、それに接続されているすべてのもの）をローカルで実行するには、プロジェクトの dev ターゲットを使用します：

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

プロジェクトに複数のコンポーネント（MCP サーバー、エージェントなど）を追加している場合、これによりすべてが起動します。この MCP サーバーのみを実行するには、その <your-server-name>-dev ターゲットを指定します：

pnpm nx your-server-name-dev your-project

yarn nx your-server-name-dev your-project

npx nx your-server-name-dev your-project

bunx nx your-server-name-dev your-project

Inspector

ジェネレーターは <your-server-name>-inspect という名前のターゲットを設定します。これは MCP サーバーをローカルで起動し（<your-server-name>-dev ターゲット経由で、ローカルデータベースなどの接続された依存関係を含む）、Streamable HTTP トランスポート経由で接続するように事前設定された MCP Inspector を起動します。

pnpm nx your-server-name-inspect your-project

yarn nx your-server-name-inspect your-project

npx nx your-server-name-inspect your-project

bunx nx your-server-name-inspect your-project

これにより、インスペクターが http://localhost:6274 で起動します。「Connect」ボタンをクリックして開始してください。

STDIO

MCP サーバーをテストして使用する最も簡単な方法は、インスペクターを使用するか、AI アシスタントで設定することです（上記参照）。

ただし、<your-server-name>-serve-stdio ターゲットを使用して、STDIO トランスポートでサーバーを直接実行することもできます。

pnpm nx your-server-name-serve-stdio your-project

yarn nx your-server-name-serve-stdio your-project

npx nx your-server-name-serve-stdio your-project

bunx nx your-server-name-serve-stdio your-project

このコマンドは uv run を使用して、STDIO トランスポートで MCP サーバーを実行します。

Streamable HTTP

Streamable HTTP トランスポートを使用して MCP サーバーをローカルで実行したい場合は、<your-server-name>-serve ターゲットを使用できます。

pnpm nx your-server-name-serve your-project

yarn nx your-server-name-serve your-project

npx nx your-server-name-serve your-project

bunx nx your-server-name-serve your-project

このコマンドは uv run uvicorn --reload を使用して、HTTP トランスポートで MCP サーバーを実行し、ファイルが変更されると自動的に再起動します。

各 MCP サーバーには 8000 から始まる独自のポートが割り当てられるため、同じワークスペース内で複数のサーバーを並行して実行できます。サーバーがリッスンするポートは、project.json 内の <your-server-name>-serve ターゲットから確認してください。

MCP Server を Bedrock AgentCore Runtime にデプロイする

Infrastructure as Code

infra に agentcore または agentcore-ecr を選択した場合、関連する CDK または Terraform インフラストラクチャが生成され、MCP サーバーを Amazon Bedrock AgentCore Runtime にデプロイするために使用できます。

CDK
Terraform

MCP サーバー用の CDK コンストラクトが生成されます。名前はジェネレーター実行時に選択した name に基づいて付けられるか、デフォルトでは <ProjectName>McpServer となります。

この CDK コンストラクトを CDK アプリケーションで使用できます:

import { MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the MCP server to your stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Terraform モジュールが生成されます。名前はジェネレーター実行時に選択した name に基づいて付けられるか、デフォルトでは <ProjectName>-mcp-server となります。

共有の runtime_config_appconfig モジュールの出力を、そのパッケージングが使用する共有アーティファクトストアと共に MCP サーバーモジュールに渡します。デフォルトの agentcore パッケージングでは、サーバーのコードが共有アセットバケットにステージングされるため、Lambda および API モジュールがすでに行っているように、デプロイメントごとに core/asset-bucket モジュールを一度インスタンス化します:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

agentcore-ecr では、サーバーのイメージが代わりに共有アセットレジストリに公開されるため、バケットの代わりに core/asset-ecr の出力を渡します。1つのレジストリがワークスペース内のすべてのコンテナにサービスを提供するため、MCP サーバーは独自のリポジトリを必要としません:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

認証

ジェネレーターは、MCP サーバーの認証を設定するための auth オプションを提供します。MCP サーバーを生成する際に、IAM（デフォルト）または Cognito 認証を選択できます。

IAM

デフォルトでは、MCP サーバーは IAM 認証を使用して保護されます。引数なしでデプロイするだけです:

CDK
Terraform

import { MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

grantInvokeAccess メソッドを使用して、Bedrock AgentCore Runtime 上の MCP サーバーを呼び出すアクセス権を付与できます。例えば、py#agent ジェネレーターで生成されたエージェントに MCP サーバーを呼び出させたい場合があります:

import { MyProjectAgent, MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');

    mcpServer.grantInvokeAccess(agent);
  }
}

# MCP Server
module "my_project_mcp_server" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

MCP サーバーを呼び出すアクセス権を付与するには、module.my_project_mcp_server.agent_core_runtime_arn 出力を参照する次のようなポリシーを追加する必要があります:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_mcp_server.agent_core_runtime_arn,
    "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
  ]
}

Cognito 認証

Cognito 認証を選択すると、ジェネレーターは MCP サーバーを Cognito を使用するように設定します。

CDK
Terraform

生成されたコンストラクトは、Cognito 認証を設定する identity プロパティを受け入れます:

import { MyProjectMcpServer, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      identity,
    });
  }
}

UserIdentity コンストラクトは ts#website#auth ジェネレーターを使用して生成できます。または、独自の CDK UserPool と UserPoolClient を作成することもできます。

生成されたモジュールは、Cognito 認証用の user_pool_id と user_pool_client_ids 変数を受け入れます:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Bundle と Docker ターゲット

Bedrock AgentCore Runtime 用に MCP サーバーをビルドするために、プロジェクトに bundle ターゲットが追加されます。これは以下を行います：

uv export を使用して Python 依存関係を requirements.txt ファイルにエクスポートする
uv pip install を使用してターゲットプラットフォーム（aarch64-manylinux_2_28）用の依存関係をインストールする

<your-server-name>-package ターゲットも追加されます。これは、デプロイ可能なコードパッケージをアセンブルします：aarch64 依存関係バンドル、Python モジュールツリー、およびルート main.py エントリポイント。生成されたインフラストラクチャは、このディレクトリを .zip としてアップロードします — CDK では AgentRuntimeArtifact.fromCodeAsset 経由で、Terraform では共有アセットバケットにアーカイブされます。

MCP サーバー専用の docker ターゲットも追加されます。これは Dockerfile とバンドルされたアーティファクトを docker コンテキストディレクトリにコピーします。これにより、Dockerfile がビルド出力と同じ場所に配置され、CDK が AgentRuntimeArtifact.fromAsset を使用して Docker イメージを直接ビルドできるようになります。

イメージスキャン

このプロジェクト用にビルドされた Docker イメージは、ECR ホスト版 Trivy イメージから実行される Trivy を使用して脆弱性をスキャンできます。

プロジェクトに trivy ターゲットが追加され、ビルドされたイメージをスキャンし、HIGH または CRITICAL の深刻度の脆弱性が見つかった場合は非ゼロで終了します。生成された Dockerfile は、生成時点でこれらの深刻度の既知の修正可能な脆弱性がないベースイメージを使用し、バンドルされたツール（npm など）をアップグレードしてその状態を維持します。

スキャンはイメージビルドと同じコンテナエンジン（docker または finch）を使用するため、追加のツールは必要ありません。スキャンはキャッシュされません。これは、読み取るイメージがディスク上ではなくコンテナエンジン内に存在するためです — そのため、常に実際のイメージをスキャンし、もはや存在しないイメージに対してキャッシュされた合格を報告するのではなく、明確に失敗します。したがって、各実行はイメージごとに数十秒かかり、Trivy の脆弱性データベースを更新するため、ネットワークアクセスが必要です。提供される trivy ルートスクリプトは、ワークスペース内のすべてのイメージをスキャンします：

pnpm trivy

yarn trivy

npm run trivy

bun trivy

スキャンは --ignore-unfixed で実行されるため、利用可能な修正がない脆弱性はビルドを失敗させません。これは、Dockerfile 内のツールをアップグレードすることでアクションできないためです — これらはビルドのスキャン出力に報告されません。新しい脆弱性が開示されると、スキャンの結果は時間の経過とともに変わる可能性があるため、フラグなしで trivy image <your-image> を実行してイメージを定期的に確認し、修正が公開されたら新しいベースイメージに対して再ビルドする（または利用可能なパッチを適用するコンテナステップを追加する）ことをお勧めします。

Trivy の検出結果の抑制

特定の脆弱性を抑制したい場合があります。たとえば、まだ修正が利用できず、リスクを許容可能と評価した場合などです。

脆弱性 ID（1 行に 1 つ）をプロジェクトのルート（つまり project.json の隣）にある .trivyignore ファイルに追加します：

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

検出結果のフィルタリングの詳細については、Trivy フィルタリングドキュメントを参照してください。

可観測性

MCPサーバーは、Dockerfileで自動計装を設定することにより、AWS Distro for Open Telemetry (ADOT) を使用したオブザーバビリティで自動的に構成されます。

トレースはCloudWatch AWSコンソールで確認できます。メニューから「GenAI Observability」を選択してください。トレースが表示されるようにするには、Transaction Searchを有効にする必要があることに注意してください。

詳細については、AgentCoreのオブザーバビリティに関するドキュメントを参照してください。

接続

connection ジェネレーターを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合します。このプロジェクトに関連する接続は以下の通りです：

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

Python Agent to MCPConnect a Python Agent to an MCP server

Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway