타입스크립트 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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

생성기 출력

생성기는 기존 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 서버 실행

검사기(Inspect)

생성기는 <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 전송을 직접 사용해 서버를 실행하려면 <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을 선택한 경우 관련 CDK 또는 Terraform 인프라스트럭처가 생성되며, 이를 사용하여 MCP 서버를 Amazon Bedrock AgentCore Runtime에 배포할 수 있습니다.

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
}

번들 타겟

제너레이터는 Rolldown을 사용하여 배포 패키지를 생성하는 bundle 타겟을 자동으로 구성합니다:

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

Rolldown 구성은 rolldown.config.ts에서 확인할 수 있으며, 생성할 각 번들별로 엔트리가 존재합니다. 정의된 경우 Rolldown은 여러 번들을 병렬로 생성하는 작업을 관리합니다.

팁

rolldown.config.ts에서 Rolldown 구성을 조정할 수 있습니다. 예를 들어 파일 경로에 의존하는 종속성이 있어 번들링이 불가능한 경우, external 모듈 목록에 추가할 수 있습니다.

번들 타겟은 Bedrock AgentCore 런타임에서 호스팅하기 위한 Streamable HTTP MCP 서버의 진입점으로 http.ts를 사용합니다.

Docker 타겟

생성기는 MCP 프로토콜 계약에 따라 포트 8000에서 번들된 Streamable HTTP MCP 서버를 실행하는 <your-server-name>-docker 타겟을 구성합니다.

팁

도커 이미지는 태그(예: my-scope-my-project-mcp-server:latest)를 사용하여 빌드되며, CDK 컨스트럭트의 Dockerfile은 이를 상속받아 MCP 서버 프로젝트와 함께 배치될 수 있습니다.

여러 MCP 서버가 정의된 경우 모든 서버의 도커 빌드를 실행하는 docker 타겟도 생성됩니다.

관측 가능성

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

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

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