TypeScript MCP Server

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

MCP とは？

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

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

使用方法

MCP サーバーの生成

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

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

CLI
VSCode

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

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

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

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

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - ts#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プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

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

Directoryyour-project/
- Directorysrc/
  - Directorymcp-server/ (or custom name if specified)
    index.ts Exports your server
    server.ts Main server definition
    stdio.ts Entry point for STDIO transport, useful for simple local MCP servers
    http.ts Entry point for Streamable HTTP transport, useful for hosting your MCP server
    Directorytools/
    divide.ts Sample tool
    Directoryresources/
    sample-guidance.ts Sample resource
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- project.json Updated with MCP server serve target

インフラストラクチャ

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 サーバーの操作

ツールの追加

ツールは、AI アシスタントがアクションを実行するために呼び出すことができる関数です。各ツールは tools/ 配下の独自のファイルに存在し、register<Name>Tool 関数をエクスポートします。その後、server.ts からその関数を呼び出します。例えば、tools/my-tool.ts を追加します：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export const registerMyTool = (server: McpServer) => {
  server.registerTool(
    'toolName',
    {
      description: 'tool description',
      // Input schema using Zod
      inputSchema: { param1: z.string(), param2: z.number() },
    },
    async ({ param1, param2 }) => {
      // Tool implementation
      const result = `${param1} ${param2}`;
      return {
        content: [{ type: 'text' as const, text: result }],
      };
    },
  );
};

次に、server.ts の createServer 内に登録します：

import { registerMyTool } from './tools/my-tool.js';

export const createServer = async () => {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });

  registerMyTool(server);

  return server;
};

リソースの追加

リソースは AI アシスタントにコンテキストを提供します。ツールと同様に、各リソースは resources/ 配下の独自のファイルに存在し、server.ts から呼び出される register<Name>Resource 関数をエクスポートします。ファイルから静的リソースを追加したり、動的リソースを追加したりできます：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const fetchSomeData = async (): Promise<string> => 'some dynamic context';

export const registerMyResource = (server: McpServer) => {
  const exampleContext = 'some context to return';

  server.registerResource(
    'resource-name',
    'example://resource',
    {},
    async (uri) => ({
      contents: [{ uri: uri.href, text: exampleContext }],
    }),
  );

  // Dynamic resource
  server.registerResource(
    'dynamic-resource',
    'dynamic://resource',
    {},
    async (uri) => {
      const data = await fetchSomeData();
      return {
        contents: [{ uri: uri.href, text: data }],
      };
    },
  );
};

ツールと同じ方法で、server.ts の createServer 内に登録します：

import { registerMyResource } from './resources/my-resource.js';

export const createServer = async () => {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });

  registerMyResource(server);

  return server;
};

AI アシスタントでの設定

設定ファイル

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

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

ホットリロード

MCP サーバーを開発している間、AI アシスタントが常に最新バージョンのツール/リソースを認識できるように --watch フラグを設定することをお勧めします：

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

アシスタント固有の設定

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

MCP サーバーの実行

ローカル開発

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

このコマンドは tsx --watch を使用して、ファイルが変更されたときにサーバーを自動的に再起動します。

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

このコマンドは tsx --watch を使用して、ファイルが変更されたときにサーバーを自動的に再起動します。

MCP サーバーを 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 ターゲット

ジェネレーターは、Rolldown を使用してデプロイメントパッケージを作成する bundle ターゲットを自動的に設定します：

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

Rolldown の設定は rolldown.config.ts にあり、生成するバンドルごとにエントリーがあります。Rolldown は、定義されている場合、複数のバンドルを並列で作成することを管理します。

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

Package ターゲット

ジェネレーターは <your-server-name>-package ターゲットを設定します。これは、デプロイ可能なコードパッケージを組み立てます：バンドルされた index.js と、AgentCore がパッケージに存在することを要求する AWS Distro for OpenTelemetry のベンダーインストール。生成されたインフラストラクチャは、このディレクトリを .zip としてアップロードします — CDK では AgentRuntimeArtifact.fromCodeAsset 経由で、Terraform では共有アセットバケットにアーカイブされます。

Docker ターゲット

ジェネレーターは <your-server-name>-docker ターゲットを設定します。これは、MCP サーバーのソースディレクトリから Dockerfile をバンドル出力ディレクトリにコピーします。これにより、Dockerfile がバンドルされたアーティファクトと同じ場所に配置され、CDK が AgentRuntimeArtifact.fromAsset を使用して Docker イメージを直接ビルドできるようになります。

複数の MCP サーバーが定義されている場合、すべての MCP サーバーの Docker コンテキストを準備する 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

MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table

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