Skip to content
@aws/nx-plugin
Blog

Pythonの MCPサーバー

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

MCPとは？

Section titled “MCPとは？”

Model Context Protocol (MCP) はAIアシスタントが外部ツールやリソースと相互作用するためのオープンスタンダードです。LLMが以下を行うための一貫した方法を提供します：

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

使用方法

Section titled “使用方法”

MCPサーバーの生成

Section titled “MCPサーバーの生成”

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

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

    オプション

    Section titled “オプション”
    パラメータ 型 デフォルト 説明
    project 必須 string - MCP サーバーを追加するプロジェクト
    computeType string BedrockAgentCoreRuntime MCP サーバーをホストするコンピュートのタイプ。ホスティングなしの場合は None を選択してください。
    name string - MCP サーバーの名前（デフォルト: mcp-server）
    auth string IAM MCPサーバーへの認証に使用する方法。IAM（デフォルト）またはCognitoから選択します。
    iacProvider string Inherit 優先する IaC プロバイダー。デフォルトでは初期選択から継承されます。

    ジェネレータ出力

    Section titled “ジェネレータ出力”

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

    • Directoryyour-project/
      • Directoryyour_module/
        • Directorymcp_server/ （カスタム名指定時はその名前）
          • __init__.py Pythonパッケージ初期化ファイル
          • server.py サンプルツールとリソースを含むメインサーバー定義
          • stdio.py STDIOトランスポート用エントリポイント（簡易ローカルMCPサーバー向け）
          • http.py ストリーミング可能なHTTPトランスポート用エントリポイント（MCPサーバーホスティング向け）
          • Dockerfile MCPサーバーホスティング用Dockerfile（computeTypeがNoneの場合は生成されない）
      • pyproject.toml MCP依存関係が追加された設定ファイル
      • project.json MCPサーバー実行ターゲットが追加された設定ファイル

    インフラストラクチャ

    Section titled “インフラストラクチャ”

    このジェネレータは選択した iacProvider に基づいてInfrastructure as Codeを生成するため、packages/common に関連するCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを作成します。

    共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

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

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

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directorymcp-servers
          • Directory<project-name>
            • <project-name>.ts MCP サーバーをデプロイするための CDK コンストラクト
            • Dockerfile CDK コンストラクトで使用されるパススルー Dockerfile

    MCPサーバーの操作

    Section titled “MCPサーバーの操作”

    ツールの追加

    Section titled “ツールの追加”

    ツールはAIアシスタントが呼び出せるアクション実行関数です。Python MCPサーバーはMCP Python SDK (FastMCP)ライブラリを使用し、デコレータベースのツール定義を提供します。

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

    @mcp.tool(description="Your tool description")
    def your_tool_name(param1: str, param2: int) -> str:
        """型ヒント付きのツール実装"""
        # ツールロジックをここに記述
        return f"Result: {param1} with {param2}"

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

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

    リソースの追加

    Section titled “リソースの追加”

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

    @mcp.resource("example://static-resource", description="静的リソース例")
    def static_resource() -> str:
        """静的なコンテンツを返す"""
        return "AIにコンテキストを提供する静的コンテンツ"
    

    @mcp.resource("dynamic://resource/{item_id}", description="動的リソース例")
    def dynamic_resource(item_id: str) -> str:
        """パラメータに基づく動的コンテンツを返す"""
        # item_idに基づくデータ取得
        data = fetch_data_for_item(item_id)
        return f"{item_id}の動的コンテンツ: {data}"

    AIアシスタントとの連携設定

    Section titled “AIアシスタントとの連携設定”

    設定ファイル

    Section titled “設定ファイル”

    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"
          }
        }
      }
    }

    アシスタント固有の設定

    Section titled “アシスタント固有の設定”

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

    MCPサーバーの実行

    Section titled “MCPサーバーの実行”

    インスペクタ

    Section titled “インスペクタ”

    ジェネレータは<your-server-name>-inspectターゲットを設定します。このターゲットはSTDIOトランスポートを使用してMCPサーバーに接続するMCP Inspectorを起動します。

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

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

    STDIO

    Section titled “STDIO”

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

    STDIOトランスポートで直接サーバーを実行するには<your-server-name>-serve-stdioターゲットを使用します。

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

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

    ストリーミング可能HTTP

    Section titled “ストリーミング可能HTTP”

    ストリーミング可能HTTPトランスポートでローカル実行する場合は<your-server-name>-serveターゲットを使用します。

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

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

    Bedrock AgentCore Runtimeへのデプロイ

    Section titled “Bedrock AgentCore Runtimeへのデプロイ”

    インフラストラクチャー as Code

    Section titled “インフラストラクチャー as Code”

    computeTypeにBedrockAgentCoreRuntimeを選択した場合、関連するCDKまたはTerraformのインフラストラクチャーコードが生成されます。これを使用してMCPサーバーをAmazon Bedrock AgentCore Runtimeにデプロイできます。

    MCPサーバー用のCDKコンストラクトが生成されます。ジェネレーター実行時に選択したnameに基づいて命名されます（デフォルトは<ProjectName>McpServer）。

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

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

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        // スタックにMCPサーバーを追加
        new MyProjectMcpServer(this, 'MyProjectMcpServer');
      }
    }

    認証

    Section titled “認証”

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

    IAM

    Section titled “IAM”

    デフォルトではMCPサーバーはIAM認証で保護されます。引数なしでデプロイできます：

    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#strands-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);
      }
    }

    Cognito認証

    Section titled “Cognito認証”

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

    生成されたコンストラクトは、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#react-website#authジェネレーターを使用して生成できます。また、独自のCDK UserPoolとUserPoolClientを作成することもできます。

    バンドルとDockerターゲット

    Section titled “バンドルとDockerターゲット”

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

    • uv exportを使用してPython依存関係をrequirements.txtにエクスポート
    • ターゲットプラットフォーム（aarch64-manylinux2014）向けにuv pip installで依存関係をインストール

    また、MCPサーバー固有のdockerターゲットが追加されます。このターゲットは：

    オブザーバビリティ

    Section titled “オブザーバビリティ”

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

    トレースは CloudWatch AWS コンソールのメニューで「GenAI Observability」を選択すると確認できます。トレースが表示されるためには、Transaction Search の有効化が必要なことにご注意ください。

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