Máy chủ MCP TypeScript

Tạo một máy chủ Model Context Protocol (MCP) TypeScript để cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLMs), và tùy chọn triển khai nó lên Amazon Bedrock AgentCore.

MCP là gì?

Model Context Protocol (MCP) là một tiêu chuẩn mở cho phép các trợ lý AI tương tác với các công cụ và tài nguyên bên ngoài. Nó cung cấp một cách nhất quán để LLMs có thể:

• Thực thi các công cụ (hàm) để thực hiện các hành động hoặc truy xuất thông tin
• Truy cập các tài nguyên cung cấp ngữ cảnh hoặc dữ liệu

Cách sử dụng

Tạo một Máy chủ MCP

Bạn có thể tạo một máy chủ MCP TypeScript theo hai cách:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#mcp-server
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

You can also perform a dry-run to see what files would be changed

pnpm

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

yarn

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

npm

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

bun

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

Mẹo

Đầu tiên hãy sử dụng generator ts#project để tạo một dự án để thêm máy chủ MCP của bạn vào.

Tùy chọn

Parameter	Type	Default	Description
project Required	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.

Kết quả của Generator

Generator sẽ thêm các tệp sau vào dự án TypeScript hiện có của bạn:

• Thư mụcyour-project/

  • Thư mụcsrc/

    • Thư mụcmcp-server/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • index.ts Xuất máy chủ của bạn
      • server.ts Định nghĩa máy chủ chính
      • stdio.ts Điểm vào cho STDIO transport, hữu ích cho các máy chủ MCP cục bộ đơn giản
      • http.ts Điểm vào cho Streamable HTTP transport, hữu ích cho việc lưu trữ máy chủ MCP của bạn
      • Thư mụctools/

        • add.ts Công cụ mẫu
      • Thư mụcresources/

        • sample-guidance.ts Tài nguyên mẫu
      • Dockerfile Điểm vào cho việc lưu trữ máy chủ MCP của bạn (loại trừ khi computeType được đặt thành None)
  • package.json Được cập nhật với mục bin và các phụ thuộc MCP
  • project.json Được cập nhật với target serve của máy chủ MCP

Cơ sở hạ tầng

Ghi chú

Nếu bạn chọn None cho computeType, generator sẽ không tạo bất kỳ infrastructure as code nào.

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Ghi chú

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Ghi chú

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Để triển khai MCP Server của bạn, các tệp sau được tạo ra:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.ts CDK construct để triển khai MCP Server của bạn
        • Dockerfile Tệp docker passthrough được sử dụng bởi CDK construct
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.ts CDK construct chung để triển khai lên Bedrock AgentCore Runtime

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai MCP Server của bạn
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.tf Module chung để triển khai lên Bedrock AgentCore Runtime

Làm việc với Máy chủ MCP của bạn

Thêm Công cụ

Công cụ là các hàm mà trợ lý AI có thể gọi để thực hiện các hành động. Bạn có thể thêm các công cụ mới trong tệp server.ts:

server.tool("toolName", "tool description",
  { param1: z.string(), param2: z.number() }, // Input schema sử dụng Zod
  async ({ param1, param2 }) => {
    // Triển khai công cụ
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Chú ý

MCP SDK hiện tại chỉ hỗ trợ Zod v3. Để cho phép Zod v4 được sử dụng trong các generator khác, phụ thuộc vào Zod v3 được cài đặt dưới tên zod-v3. Đối với các schema công cụ MCP, bạn sẽ cần import Zod như sau:

import { z } from 'zod-v3';

Khi vấn đề này với MCP SDK được giải quyết, bạn có thể xóa phụ thuộc zod-v3 bổ sung và chỉ cần import từ zod.

Thêm Tài nguyên

Tài nguyên cung cấp ngữ cảnh cho trợ lý AI. Bạn có thể thêm các tài nguyên tĩnh từ tệp hoặc tài nguyên động:

const exampleContext = 'some context to return';

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

// Tài nguyên động
server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
  const data = await fetchSomeData();
  return {
    contents: [{ uri: uri.href, text: data }],
  };
});

Cấu hình với Trợ lý AI

Tệp Cấu Hình

Hầu hết các trợ lý AI hỗ trợ MCP đều sử dụng phương pháp cấu hình tương tự. Bạn sẽ cần tạo hoặc cập nhật tệp cấu hình với thông tin chi tiết về MCP server của bạn:

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

Chú ý

Nếu bạn nhận được lỗi như ENOENT npx khi kết nối với server của bạn, bạn có thể cần chỉ định đường dẫn đầy đủ đến npx, bạn có thể lấy đường dẫn này bằng cách chạy lệnh which npx trong terminal của bạn.

Hot Reload

Trong khi phát triển MCP server của bạn, bạn có thể muốn cấu hình cờ --watch để trợ lý AI luôn thấy các phiên bản mới nhất của tools/resources:

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

Ghi chú

Nếu bạn thêm tools hoặc resources mới, bạn có thể cần làm mới MCP server của bạn trong trợ lý AI.

Cấu Hình Theo Trợ Lý Cụ Thể

Vui lòng tham khảo tài liệu sau để cấu hình MCP với các Trợ Lý AI cụ thể:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Mẹo

Một số Trợ Lý AI, chẳng hạn như Amazon Q Developer, cho phép bạn chỉ định cấu hình MCP server ở cấp độ workspace, điều này đặc biệt hữu ích để xác định các MCP server liên quan cho một dự án cụ thể.

Chạy Máy chủ MCP của bạn

Inspector

Generator cấu hình một target có tên <your-server-name>-inspect, khởi động MCP Inspector với cấu hình để kết nối với máy chủ MCP của bạn bằng STDIO transport.

pnpm

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

yarn

yarn nx run your-project:your-server-name-inspect

npm

npx nx run your-project:your-server-name-inspect

bun

bunx nx run your-project:your-server-name-inspect

Điều này sẽ khởi động inspector tại http://localhost:6274. Bắt đầu bằng cách nhấp vào nút “Connect”.

STDIO

Cách dễ nhất để kiểm tra và sử dụng máy chủ MCP là bằng cách sử dụng inspector hoặc cấu hình nó với một trợ lý AI (như trên).

Tuy nhiên, bạn có thể chạy máy chủ của mình với STDIO transport trực tiếp bằng cách sử dụng target <your-server-name>-serve-stdio.

pnpm

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

yarn

yarn nx run your-project:your-server-name-serve-stdio

npm

npx nx run your-project:your-server-name-serve-stdio

bun

bunx nx run your-project:your-server-name-serve-stdio

Lệnh này sử dụng tsx --watch để tự động khởi động lại máy chủ khi các tệp thay đổi.

Streamable HTTP

Nếu bạn muốn chạy máy chủ MCP của mình cục bộ bằng Streamable HTTP transport, bạn có thể sử dụng target <your-server-name>-serve.

pnpm

pnpm nx run your-project:your-server-name-serve

yarn

yarn nx run your-project:your-server-name-serve

npm

npx nx run your-project:your-server-name-serve

bun

bunx nx run your-project:your-server-name-serve

Lệnh này sử dụng tsx --watch để tự động khởi động lại máy chủ khi các tệp thay đổi.

Triển khai Máy chủ MCP của bạn lên Bedrock AgentCore Runtime

Cơ sở hạ tầng dưới dạng mã (Infrastructure as Code)

Nếu bạn đã chọn BedrockAgentCoreRuntime cho computeType, cơ sở hạ tầng CDK hoặc Terraform tương ứng sẽ được tạo ra, bạn có thể sử dụng để triển khai MCP server của mình lên Amazon Bedrock AgentCore Runtime.

CDK

Một CDK construct được tạo cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc <ProjectName>McpServer theo mặc định.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

import { MyProjectMcpServer } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Thêm MCP server vào stack của bạn
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Terraform

Một Terraform module được tạo cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc <ProjectName>-mcp-server theo mặc định.

Bạn có thể sử dụng terraform module này trong một dự án Terraform:

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Chú ý

Docker là bắt buộc để xây dựng và triển khai MCP server của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Xác thực

IAM

Theo mặc định, MCP server của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần tham số nào:

CDK

import { MyProjectMcpServer } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

Bạn có thể cấp quyền truy cập để gọi MCP của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvoke. Ví dụ, bạn có thể muốn một agent được tạo bằng trình tạo py#strands-agent gọi MCP server của bạn:

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

Terraform

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Để cấp quyền truy cập gọi agent của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output 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}/*"
  ]
}

Xác thực Cognito JWT

Phần dưới đây minh họa cách cấu hình xác thực Cognito cho agent của bạn.

CDK

Để cấu hình xác thực JWT, bạn có thể truyền thuộc tính authorizerConfiguration vào MCP server construct của mình. Đây là một ví dụ cấu hình Cognito user pool và client để bảo mật MCP server:

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

Terraform

Để cấu hình xác thực JWT, bạn có thể chỉnh sửa MCP Server module của mình để cấu hình biến customJWTAuthorizer như sau:

packages/common/terraform/src/app/mcp-servers/my-project-mcp-server/my-project-mcp-server.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Thay thế bằng user pool và client ids của bạn hoặc expose dưới dạng biến
  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
}

Bundle Target

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

pnpm

pnpm nx run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Mẹo

Bạn có thể điều chỉnh cấu hình cho Rolldown trong rolldown.config.ts, ví dụ nếu bạn có các dependency phụ thuộc vào đường dẫn file và không thể được bundle, bạn có thể thêm chúng vào danh sách các module external.

Bundle target sử dụng http.ts làm điểm vào cho máy chủ MCP Streamable HTTP để lưu trữ trên Bedrock AgentCore Runtime.

Docker Target

Generator cấu hình một target <your-server-name>-docker chạy máy chủ MCP Streamable HTTP đã được đóng gói trên cổng 8000 theo MCP protocol contract.

Mẹo

Docker image được xây dựng bằng cách sử dụng một tag (ví dụ my-scope-my-project-mcp-server:latest), mà Dockerfile của CDK construct kế thừa từ đó, cho phép Dockerfile của bạn được đặt cùng vị trí với dự án máy chủ MCP của bạn.

Một target docker cũng được tạo ra để chạy docker build cho tất cả các máy chủ MCP nếu bạn có nhiều máy chủ được định nghĩa.

Khả năng quan sát

MCP server của bạn được tự động cấu hình với khả năng quan sát bằng cách sử dụng AWS Distro for Open Telemetry (ADOT), thông qua việc cấu hình auto-instrumentation trong Dockerfile của bạn.

Bạn có thể tìm thấy các trace trong CloudWatch AWS Console, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các trace được hiển thị, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, vui lòng tham khảo tài liệu AgentCore về khả năng quan sát.