TypeScript MCP Server

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

MCP とは？

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

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

使用方法

MCP サーバーの生成

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

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

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

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

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

ジェネレーターの出力

ジェネレーターは、既存の 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 Entry point for hosting your MCP server (excluded when infra is set to None)
- project.json Updated with MCP server serve target

インフラストラクチャ

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

ツールの追加

ツールは、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",
    inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
  },
    async ({ param1, param2 }) => {
      // Tool implementation
      return {
        content: [{ type: "text", 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';

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 }],
    };
  });
};

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 を選択した場合、関連する 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 ターゲット

ジェネレーターは、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 を使用します。

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 ルートスクリプトは、ワークスペース内のすべてのイメージをスキャンします：

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