TypeScriptのMCPサーバー

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

MCPとは？

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

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

使用方法

MCPサーバーの生成

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

VSCode
CLI

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

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

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

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

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

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

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

オプション

パラメータ	型	デフォルト	説明
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プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレータの出力

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

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

インフラストラクチャ

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

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

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 サーバーをデプロイするために、以下のファイルが生成されます：

CDK
Terraform

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

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

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

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

MCPサーバーの操作

ツールの追加

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

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

リソースの追加

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

const exampleContext = '返されるコンテキスト';

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

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

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

設定ファイル

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を設定するには、各製品のドキュメントを参照してください：

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

インスペクタ

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

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アシスタントと連携させることです（上記参照）。

STDIOトランスポートで直接サーバーを実行するには、<your-server-name>-serve-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を使用し、ファイル変更時にサーバーを自動再起動します。

ストリーミング可能HTTP

ストリーミング可能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を使用し、ファイル変更時にサーバーを自動再起動します。

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

インフラストラクチャー 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) {
    // スタックにMCPサーバーを追加
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

ジェネレーター実行時に選択したnameに基づいて命名されたTerraformモジュールが生成されます（デフォルトは<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サーバー
module "my_project_mcp_server" {
  # common/terraformプロジェクト内の生成モジュールへの相対パス
  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認証を選択すると、ジェネレーターはCognito認証を使用するようにMCPサーバーを設定します。

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

バンドルターゲット

ジェネレーターは自動的に 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は定義された複数のバンドルを並行して作成する処理を管理します。

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

Dockerターゲット

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

複数のMCPサーバーを定義している場合、すべてのMCPサーバーのdockerコンテキストを準備するdockerターゲットも生成されます。

イメージスキャン

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

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

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

Trivy検出結果の抑制

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

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

# 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 MCPTypeScript AgentをMCPサーバーに接続する

Python Agent to MCPPython AgentをMCPサーバーに接続する

MCP Server to Relational DatabaseTypeScript MCP ServerをAuroraリレーショナルデータベースに接続する

MCP Server to TypeScript DynamoDBTypeScript MCP ServerをDynamoDBテーブルに接続する

AgentCore Gateway to MCP ServerAgentCore GatewayでMCPサーバーを集約する