Python MCP Server

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

MCP とは？

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

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

使用方法

MCP Server の生成

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

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

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

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

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

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

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

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

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	MCP サーバーを追加するプロジェクト
name	string	-	MCP サーバーの名前（デフォルト: mcp-server）
auth	iam \| cognito	iam	MCPサーバーへの認証に使用する方法。infraが設定されている場合にのみ適用されます（infraがnoneの場合は無視されます）。
iac	inherit \| cdk \| terraform	inherit	優先するIaCプロバイダー。デフォルトでは初期選択から継承されます。
infra	agentcore \| none	agentcore	MCPサーバーをホストするインフラストラクチャのタイプ。ホスティングが不要な場合はnoneを選択してください。
preferInstallDependencies	boolean	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 Entry point for hosting your MCP server (excluded when infra is set to None)
- pyproject.toml Updated with MCP dependencies
- project.json Updated with MCP server serve targets

インフラストラクチャ

このジェネレーターは、選択した 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

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

Bedrock AgentCore Runtime にデプロイされると、MCP サーバーはコンテナイメージにビルドされ、Amazon ECR にプッシュされ、AgentCore Runtime で実行されます。AI アシスタントは AgentCore Runtime データプレーンエンドポイントを呼び出し、streamable HTTP transport を介して tools/* および resources/* の呼び出しをサーバーに転送します。

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

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 トランスポート（通常はポート 8000）で MCP サーバーを実行し、ファイルが変更されると自動的に再起動します。

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

Infrastructure as Code

infra に agentcore を選択した場合、関連する 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 サーバーモジュールに渡します:

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
}

MCP サーバーをビルドおよびデプロイするには Docker が必要です。次のようなエラーを回避するために、Docker がインストールされ起動していることを確認してください:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

認証

ジェネレーターは、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）用の依存関係をインストールする

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

イメージスキャン

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

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

スキャンはイメージビルドと同じコンテナエンジン（docker または finch）を使用するため、追加のツールは必要ありません。スキャンはイメージが変更された場合にのみ再実行されるため、変更されていないイメージは再スキャンされません。提供される 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