Skip to content

TypeScriptのMCPサーバー

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

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

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

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

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#mcp-server
  5. 必須パラメータを入力
    • クリック Generate
    パラメータ デフォルト 説明
    project 必須 string - The project to add an MCP server to
    computeType string BedrockAgentCoreRuntime The type of compute to host your MCP server. Select None for no hosting.
    name string - The name of your MCP server (default: mcp-server)
    iacProvider string Inherit The preferred IaC provider. By default this is inherited from your initial selection.

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

    • Directoryyour-project/
      • Directorysrc/
        • Directorymcp-server/ (カスタム名を指定した場合はそれを使用)
          • index.ts サーバーのエクスポート
          • server.ts メインサーバー定義
          • stdio.ts STDIOトランスポート用エントリポイント(簡易ローカルMCPサーバー向け)
          • http.ts ストリーミング可能なHTTPトランスポート用エントリポイント(MCPサーバーホスティング向け)
          • Directorytools/
            • add.ts サンプルツール
          • Directoryresources/
            • sample-guidance.ts サンプルリソース
          • Dockerfile MCPサーバーホスティング用エントリポイント(computeTypeNoneの場合は除外)
      • package.json binエントリとMCP依存関係を更新
      • project.json MCPサーバーserveターゲットを更新

    このジェネレータは選択した 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
      • Directorycore
        • Directoryagent-core
          • runtime.ts Bedrock AgentCore ランタイムにデプロイする汎用 CDK コンストラクト

    ツールはAIアシスタントが呼び出せるアクション実行関数です。server.tsファイルに新しいツールを追加できます:

    server.tool("toolName", "ツールの説明",
    { param1: z.string(), param2: z.number() }, // Zodを使用した入力スキーマ
    async ({ param1, param2 }) => {
    // ツールの実装
    return {
    content: [{ type: "text", text: "結果" }]
    };
    }
    );

    リソースはAIアシスタントにコンテキストを提供します。ファイルからの静的リソースや動的リソースを追加できます:

    const exampleContext = '返されるコンテキスト';
    server.resource('resource-name', 'example://resource', async (uri) => ({
    contents: [{ uri: uri.href, text: exampleContext }],
    }));
    // 動的リソース
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
    const data = await fetchSomeData();
    return {
    contents: [{ uri: uri.href, text: data }],
    };
    });

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

    {
    "mcpServers": {
    "your-mcp-server": {
    "command": "npx",
    "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
    }
    }

    MCPサーバーを開発中は、--watch フラグを設定することでAIアシスタントが常に最新のツール/リソースを認識するようにできます:

    {
    "mcpServers": {
    "your-mcp-server": {
    "command": "npx",
    "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
    }
    }

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

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

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

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

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

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

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

    このコマンドはtsx --watchを使用し、ファイル変更時にサーバーを自動再起動します。

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

    Terminal window
    pnpm nx run your-project:your-server-name-serve-http

    このコマンドはtsx --watchを使用し、ファイル変更時にサーバーを自動再起動します。

    Bedrock AgentCore RuntimeへのMCPサーバーデプロイ

    Section titled “Bedrock AgentCore RuntimeへのMCPサーバーデプロイ”

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

    ジェネレーター実行時に選択したnameに基づいて命名されたCDKコンストラクトが生成されます(デフォルトは<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');
    }
    }

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

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    export class ExampleStack extends Stack {
    constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
    }
    }

    grantInvokeメソッドを使用して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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
    }
    }

    以下はCognito認証を設定する方法を示します。

    JWT認証を設定するには、MCPサーバーコンストラクトにauthorizerConfigurationプロパティを渡します。CognitoユーザープールとクライアントでMCPサーバーを保護する例:

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    export class ExampleStack extends Stack {
    constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
    authFlows: {
    userPassword: true,
    },
    });
    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
    authorizerConfiguration: {
    customJwtAuthorizer: {
    discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
    allowedClients: [client.userPoolClientId],
    },
    },
    });
    }
    }

    ジェネレーターは自動的に Rolldown を使用する bundle ターゲットを設定します。このターゲットはデプロイメントパッケージの作成に使用されます:

    Terminal window
    pnpm nx run <project-name>:bundle

    Rolldownの設定はrolldown.config.tsに記述され、生成するバンドルごとにエントリを定義します。Rolldownは定義された複数のバンドルを並行して作成する処理を管理します。

    バンドルターゲットはBedrock AgentCore RuntimeでホストするストリーミングHTTP MCPサーバーのエントリポイントとしてhttp.tsを使用します。

    ジェネレータは<your-server-name>-dockerターゲットを設定し、MCPプロトコル契約に従ってポート8000でバンドルされたストリーミングHTTP MCPサーバーを実行します。

    複数のMCPサーバーを定義している場合、すべてのMCPサーバーのdockerビルドを実行するdockerターゲットも生成されます。

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

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

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