TypeScriptのMCPサーバー
大規模言語モデル(LLM)にコンテキストを提供するTypeScript Model Context Protocol(MCP)サーバーを生成し、オプションでAmazon Bedrock AgentCoreにデプロイします。
MCPとは?
Section titled “MCPとは?”Model Context Protocol(MCP)は、AIアシスタントが外部ツールやリソースと相互作用するためのオープンスタンダードです。LLMが以下を一貫した方法で行えるようにします:
- アクション実行や情報取得のためのツール(関数)を実行
- コンテキストやデータを提供するリソースにアクセス
MCPサーバーの生成
Section titled “MCPサーバーの生成”TypeScript MCPサーバーは2つの方法で生成できます:
- インストール 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-serveryarn nx g @aws/nx-plugin:ts#mcp-servernpx nx g @aws/nx-plugin:ts#mcp-serverbunx nx g @aws/nx-plugin:ts#mcp-server変更されるファイルを確認するためにドライランを実行することもできます
pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-runyarn nx g @aws/nx-plugin:ts#mcp-server --dry-runnpx nx g @aws/nx-plugin:ts#mcp-server --dry-runbunx nx g @aws/nx-plugin:ts#mcp-server --dry-run| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| 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. |
ジェネレータの出力
Section titled “ジェネレータの出力”ジェネレータは既存の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サーバーホスティング用エントリポイント(
computeTypeがNoneの場合は除外)
- package.json binエントリとMCP依存関係を更新
- project.json MCPサーバーserveターゲットを更新
インフラストラクチャ
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 プロジェクトのビルドターゲットと設定
Directorypackages/common/terraform
Directorysrc
Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール
- …
Directorycore/
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 コンストラクト
Directorypackages/common/terraform/src
Directoryapp
Directorymcp-servers
Directory<project-name>
- <project-name>.tf MCP サーバーをデプロイするためのモジュール
Directorycore
Directoryagent-core
- runtime.tf Bedrock AgentCore ランタイムにデプロイする汎用モジュール
MCPサーバーの操作
Section titled “MCPサーバーの操作”ツールの追加
Section titled “ツールの追加”ツールはAIアシスタントが呼び出せるアクション実行関数です。server.tsファイルに新しいツールを追加できます:
server.tool("toolName", "ツールの説明", { param1: z.string(), param2: z.number() }, // Zodを使用した入力スキーマ async ({ param1, param2 }) => { // ツールの実装 return { content: [{ type: "text", text: "結果" }] }; });リソースの追加
Section titled “リソースの追加”リソースは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 }], };});AIアシスタントとの連携設定
Section titled “AIアシスタントとの連携設定”設定ファイル
Section titled “設定ファイル”MCPをサポートするほとんどのAIアシスタントは、同様の設定方法を使用します。MCPサーバーの詳細を記載した設定ファイルを作成または更新する必要があります:
{ "mcpServers": { "your-mcp-server": { "command": "npx", "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"] } }}ホットリロード
Section titled “ホットリロード”MCPサーバーを開発中は、--watch フラグを設定することでAIアシスタントが常に最新のツール/リソースを認識するようにできます:
{ "mcpServers": { "your-mcp-server": { "command": "npx", "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"] } }}アシスタント固有の設定
Section titled “アシスタント固有の設定”特定のAIアシスタントでMCPを設定するには、各製品のドキュメントを参照してください:
MCPサーバーの実行
Section titled “MCPサーバーの実行”インスペクタ
Section titled “インスペクタ”ジェネレータは<your-server-name>-inspectターゲットを設定し、MCP InspectorをSTDIOトランスポートでMCPサーバーに接続する構成で起動します。
pnpm nx run your-project:your-server-name-inspectyarn nx run your-project:your-server-name-inspectnpx nx run your-project:your-server-name-inspectbunx nx run your-project:your-server-name-inspectこれによりhttp://localhost:6274でインスペクタが起動します。「Connect」ボタンから開始してください。
MCPサーバーをテストする最も簡単な方法は、インスペクタを使用するかAIアシスタントと連携させることです(上記参照)。
STDIOトランスポートで直接サーバーを実行するには、<your-server-name>-serve-stdioターゲットを使用します。
pnpm nx run your-project:your-server-name-serve-stdioyarn nx run your-project:your-server-name-serve-stdionpx nx run your-project:your-server-name-serve-stdiobunx nx run your-project:your-server-name-serve-stdioこのコマンドはtsx --watchを使用し、ファイル変更時にサーバーを自動再起動します。
ストリーミング可能HTTP
Section titled “ストリーミング可能HTTP”ストリーミング可能HTTPトランスポートでローカルにMCPサーバーを実行するには、<your-server-name>-serve-httpターゲットを使用します。
pnpm nx run your-project:your-server-name-serve-httpyarn nx run your-project:your-server-name-serve-httpnpx nx run your-project:your-server-name-serve-httpbunx nx run your-project:your-server-name-serve-httpこのコマンドはtsx --watchを使用し、ファイル変更時にサーバーを自動再起動します。
Bedrock AgentCore RuntimeへのMCPサーバーデプロイ
Section titled “Bedrock AgentCore RuntimeへのMCPサーバーデプロイ”インフラストラクチャー as Code
Section titled “インフラストラクチャー as Code”computeTypeにBedrockAgentCoreRuntimeを選択した場合、関連する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'); }}ジェネレーター実行時に選択したnameに基づいて命名されたTerraformモジュールが生成されます(デフォルトは<ProjectName>-mcp-server)。
このTerraformモジュールをTerraformプロジェクトで使用できます:
# MCPサーバーmodule "my_project_mcp_server" { # common/terraformプロジェクト内の生成モジュールへの相対パス source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"}デフォルトでは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); }}# MCPサーバーmodule "my_project_mcp_server" { # common/terraformプロジェクト内の生成モジュールへの相対パス source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"}起動権限を付与するには、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 JWT認証
Section titled “Cognito JWT認証”以下は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], }, }, }); }}JWT認証を設定するには、MCPサーバーモジュールのcustomJWTAuthorizer変数を以下のように設定:
data "aws_region" "current" {}
locals { aws_region = data.aws_region.current.name
# ユーザープールIDとクライアントIDに置き換え、または変数として公開 user_pool_id = "xxx" user_pool_client_ids = ["yyy"]}
module "agent_core_runtime" { source = "../../../core/agent-core" agent_runtime_name = "MyProjectMcpServer" docker_image_tag = "my-scope-my-project-agent:latest" server_protocol = "MCP" customJWTAuthorizer = { discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration", allowedClients = local.user_pool_client_ids } env = var.env additional_iam_policy_statements = var.additional_iam_policy_statements tags = var.tags}バンドルターゲット
Section titled “バンドルターゲット”ジェネレーターは自動的に Rolldown を使用する bundle ターゲットを設定します。このターゲットはデプロイメントパッケージの作成に使用されます:
pnpm nx run <project-name>:bundleyarn nx run <project-name>:bundlenpx nx run <project-name>:bundlebunx nx run <project-name>:bundleRolldownの設定はrolldown.config.tsに記述され、生成するバンドルごとにエントリを定義します。Rolldownは定義された複数のバンドルを並行して作成する処理を管理します。
バンドルターゲットはBedrock AgentCore RuntimeでホストするストリーミングHTTP MCPサーバーのエントリポイントとしてhttp.tsを使用します。
Dockerターゲット
Section titled “Dockerターゲット”ジェネレータは<your-server-name>-dockerターゲットを設定し、MCPプロトコル契約に従ってポート8000でバンドルされたストリーミングHTTP MCPサーバーを実行します。
複数のMCPサーバーを定義している場合、すべてのMCPサーバーのdockerビルドを実行するdockerターゲットも生成されます。
オブザーバビリティ
Section titled “オブザーバビリティ”お客様の MCP サーバーは、Dockerfile で自動計装を構成することにより、AWS Distro for Open Telemetry (ADOT) を使用したオブザーバビリティが自動的に設定されます。
トレースは CloudWatch AWS コンソールのメニューで「GenAI Observability」を選択すると確認できます。トレースが表示されるためには、Transaction Search の有効化が必要なことにご注意ください。
詳細については、AgentCore ドキュメントのオブザーバビリティ項目を参照してください。