타입스크립트 MCP 서버

대형 언어 모델(LLM)에 컨텍스트를 제공하기 위한 TypeScript 모델 컨텍스트 프로토콜(MCP) 서버를 생성하고, 선택적으로 Amazon Bedrock AgentCore에 배포합니다.

MCP란?

모델 컨텍스트 프로토콜(MCP)은 AI 어시스턴트가 외부 도구 및 리소스와 상호작용할 수 있도록 하는 개방형 표준입니다. LLM이 다음을 수행할 수 있는 일관된 방법을 제공합니다:

• 작업 수행 또는 정보 검색을 위한 도구(함수) 실행
• 컨텍스트 또는 데이터 제공을 위한 리소스 접근

사용 방법

MCP 서버 생성

TypeScript MCP 서버를 두 가지 방법으로 생성할 수 있습니다:

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#mcp-server
5. 필수 매개변수 입력
6. 클릭 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

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

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

팁

먼저 MCP 서버를 추가할 프로젝트를 생성하기 위해 ts#project 생성기를 사용하세요.

옵션

매개변수	타입	기본값	설명
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	CDK	The preferred IaC provider

생성기 출력

생성기는 기존 TypeScript 프로젝트에 다음 파일들을 추가합니다:

• 디렉터리your-project/

  • 디렉터리src/

    • 디렉터리mcp-server/ (사용자 지정 이름 지정 가능)

      • index.ts 서버를 내보냄
      • server.ts 주요 서버 정의
      • stdio.ts STDIO 전송을 위한 진입점 (단순 로컬 MCP 서버에 유용)
      • http.ts Streamable HTTP 전송을 위한 진입점 (MCP 서버 호스팅에 유용)
      • 디렉터리tools/

        • add.ts 샘플 도구
      • 디렉터리resources/

        • sample-guidance.ts 샘플 리소스
      • Dockerfile MCP 서버 실행을 위한 진입점 (computeType이 None으로 설정된 경우 제외)
  • package.json bin 항목 및 MCP 종속성 업데이트
  • project.json MCP 서버 실행 타겟 업데이트

인프라

참고

computeType을 None으로 선택한 경우 생성기는 인프라 코드를 생성하지 않습니다.

이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소

      • …
    • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소

      • …
    • index.ts app의 구축 요소를 익스포트하는 진입점
  • project.json 프로젝트 빌드 대상 및 구성

참고

이 프로젝트는 ts#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈

      • …
    • 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈

      • …
  • project.json 프로젝트 빌드 대상 및 구성

참고

이 프로젝트는 terraform#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

MCP 서버를 배포하기 위해 다음 파일들이 생성됩니다:

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리app

    • 디렉터리mcp-servers

      • 디렉터리<project-name>

        • <project-name>.ts MCP 서버 배포를 위한 CDK construct
        • Dockerfile CDK construct에서 사용되는 Passthrough docker 파일
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.ts Bedrock AgentCore Runtime에 배포하기 위한 일반적인 CDK construct

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리app

    • 디렉터리mcp-servers

      • 디렉터리<project-name>

        • <project-name>.tf MCP 서버 배포를 위한 모듈
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.tf Bedrock AgentCore Runtime에 배포하기 위한 일반적인 모듈

MCP 서버 작업

도구 추가

도구는 AI 어시스턴트가 호출할 수 있는 함수입니다. server.ts 파일에 새 도구를 추가할 수 있습니다:

server.tool("toolName", "tool description",
  { param1: z.string(), param2: z.number() }, // Zod를 사용한 입력 스키마
  async ({ param1, param2 }) => {
    // 도구 구현
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

주의

현재 MCP SDK는 Zod v3만 지원합니다. 다른 생성기에서 Zod v4 사용을 허용하기 위해 Zod v3 종속성이 zod-v3로 설치됩니다. MCP 도구 스키마에서는 다음과 같이 Zod를 임포트해야 합니다:

import { z } from 'zod-v3';

MCP SDK의 이슈가 해결되면 추가 zod-v3 종속성을 제거하고 zod에서 임포트할 수 있습니다.

리소스 추가

리소스는 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 어시스턴트와 연동 설정

설정 파일

MCP를 지원하는 대부분의 AI 어시스턴트는 유사한 설정 방식을 사용합니다. MCP 서버 정보가 포함된 설정 파일을 생성하거나 업데이트해야 합니다:

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

주의

서버 연결 시 ENOENT npx 오류가 발생하면 터미널에서 which npx를 실행해 얻은 전체 경로를 지정해야 할 수 있습니다.

핫 리로드

MCP 서버 개발 중에는 --watch 플래그를 설정하여 AI 어시스턴트가 항상 최신 도구/리소스 버전을 인식하도록 할 수 있습니다:

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

참고

새 도구나 리소스를 추가한 경우 AI 어시스턴트에서 MCP 서버를 새로고침해야 할 수 있습니다.

어시스턴트별 설정

특정 AI 어시스턴트와 MCP 연동 설정은 다음 문서를 참조하세요:

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

팁

Amazon Q Developer과 같은 일부 AI 어시스턴트는 워크스페이스 수준의 MCP 서버 설정을 지원하며, 특정 프로젝트와 관련된 MCP 서버를 정의할 때 특히 유용합니다.

MCP 서버 실행

인스펙터

생성기는 <your-server-name>-inspect 타겟을 구성하며, 이는 STDIO 전송을 사용해 MCP 서버에 연결하도록 설정된 MCP 인스펙터를 시작합니다.

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

이 명령은 http://localhost:6274에서 인스펙터를 시작합니다. “Connect” 버튼을 클릭하여 시작하세요.

STDIO

MCP 서버를 테스트하고 사용하는 가장 쉬운 방법은 인스펙터를 사용하거나 AI 어시스턴트와 연동하는 것입니다(STDIO 전송 사용).

STDIO 전송을 직접 사용해 <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

이 명령은 파일 변경 시 서버를 자동 재시작하는 tsx --watch를 사용합니다.

Streamable HTTP

Streamable HTTP 전송으로 로컬에서 MCP 서버를 실행하려면 <your-server-name>-serve-http 타겟을 사용하세요.

pnpm

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

yarn

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

npm

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

bun

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

이 명령은 파일 변경 시 서버를 자동 재시작하는 tsx --watch를 사용합니다.

Bedrock AgentCore 런타임에 MCP 서버 배포

인프라스트럭처 코드

생성기 실행 시 computeType으로 BedrockAgentCoreRuntime을 선택한 경우, Amazon Bedrock AgentCore Runtime에 MCP 서버를 배포하는 데 사용할 수 있는 관련 CDK 또는 Terraform 인프라가 생성됩니다.

CDK

생성기 실행 시 선택한 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');
  }
}

Terraform

생성기 실행 시 선택한 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 서버 빌드 및 배포에는 Docker가 필요합니다. 다음 오류를 방지하려면 Docker가 설치되어 실행 중인지 확인하세요:

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

인증

IAM

기본적으로 MCP 서버는 IAM 인증을 사용하여 보호됩니다. 인수 없이 배포하면 됩니다:

CDK

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

Terraform

# 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 인증

다음은 에이전트에 Cognito 인증을 구성하는 방법을 보여줍니다.

CDK

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

Terraform

JWT 인증을 구성하려면 MCP 서버 모듈의 customJWTAuthorizer 변수를 다음과 같이 수정할 수 있습니다:

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

  # 사용자 풀 및 클라이언트 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
}

번들 타겟

Bedrock AgentCore 런타임용 MCP 서버를 빌드하기 위해 <your-mcp-server>-bundle 타겟이 프로젝트에 추가됩니다. 이 타겟은:

• esbuild을 사용해 MCP 서버를 단일 JavaScript 파일로 번들링합니다(Streamable HTTP MCP 서버용 진입점으로 http.ts 사용).
• MCP 프로토콜 계약에 따라 포트 8000에서 이 번들 서버를 실행하는 Dockerfile에서 도커 이미지를 빌드합니다.

팁

도커 이미지는 태그(예: my-scope-my-project-mcp-server:latest)로 빌드되며, CDK 구성의 Dockerfile이 이를 상속받아 MCP 서버 프로젝트와 동일 위치에 배치할 수 있습니다.

관측 가능성

MCP 서버는 Dockerfile에 자동 계측을 구성하여 AWS Distro for Open Telemetry(ADOT)를 사용해 관측 가능성을 자동으로 구성합니다.

트레이스는 CloudWatch AWS 콘솔에서 메뉴의 “GenAI Observability”를 선택해 확인할 수 있습니다. 트레이스 데이터가 표시되려면 트랜잭션 검색을 활성화해야 합니다.

자세한 내용은 AgentCore 관측 가능성 문서를 참조하세요.