AgentCore Gateway에서 MCP Server로

connection 제너레이터는 MCP 서버(TypeScript 또는 Python)를 AgentCore Gateway의 대상으로 등록할 수 있습니다.

연결되면 Gateway는 MCP 서버의 도구를 단일 MCP 엔드포인트로 집계하고, Cedar 정책 엔진에 대해 호출을 평가하며, MCP 서버로 나가는 트래픽에 IAM SigV4로 서명합니다.

사전 요구 사항

이 제너레이터를 사용하기 전에 다음이 필요합니다:

1. agentcore-gateway 프로젝트
2. infra: agentcore 및 auth: iam으로 생성된 MCP 서버 컴포넌트(ts#mcp-server 또는 py#mcp-server)

Gateway는 protocol: mcp를 가져야 하고 MCP 서버는 auth: iam을 가져야 합니다 — 제너레이터는 둘 다 검증합니다. Gateway가 SigV4로 나가는 트래픽에 서명하기 때문에 IAM이 아닌 MCP 서버는 연결할 수 없습니다.

사용법

제너레이터 실행

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

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

Gateway 프로젝트를 소스로, MCP 서버 프로젝트를 대상으로 선택합니다. MCP 서버 프로젝트에 여러 컴포넌트가 포함된 경우 targetComponent를 지정하여 명확히 합니다.

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

제너레이터 출력

제너레이터는 새 소스 파일을 생성하는 대신 기존 프로젝트를 함께 연결합니다. 다음 파일이 수정됩니다:

• 디렉터리packages/<gateway>

  • project.json Gateway의 dev 타겟이 MCP 서버의 <mcp>-dev에 대한 종속성을 얻습니다
  • local-dev.ts ATTACHED_MCP_SERVERS가 업데이트되어 로컬 게이트웨이가 MCP 서버를 집계합니다

Gateway 프로젝트의 dev 타겟은 MCP 서버의 <mcp>-dev 타겟에 대한 종속성을 얻으므로 Gateway를 로컬에서 실행하면 MCP 서버도 시작됩니다. MCP 서버는 Gateway 프로젝트의 local-dev.ts에도 등록되어 로컬 게이트웨이가 해당 도구를 집계합니다.

스택에 MCP 서버 대상 추가하기

제너레이터는 Gateway를 인스턴스화하는 스택이나 모듈을 알 수 없기 때문에 MCP 서버 대상을 인프라에 자동으로 연결할 수 없습니다. gateway.addMcpServer(server)에 대한 단일 호출을 직접 추가하세요.

CDK

Gateway를 인스턴스화하는 스택에서 MCP 서버를 대상으로 등록합니다:

packages/infra/src/stacks/application-stack.ts

const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the MCP server as a target of the Gateway. The target name
// defaults to the MCP server's `mcpServerName` (its class name in
// kebab-case, e.g. `MyMcpServer` -> `my-mcp-server`).
myGateway.addMcpServer(myMcpServer);

Gateway 대상 이름(기본적으로 MCP 서버의 mcpServerName)은 Cedar 액션 이름의 접두사로 사용됩니다 — 액션 형식은 AgentCore::Action::"<targetName>___<toolName>"입니다. 정책 작성 섹션을 참조하세요. 대상 이름을 짧고 안정적으로 유지하세요. 나중에 변경하면 이전 이름을 참조하는 Cedar 정책이 무효화됩니다.

기본 대상 이름을 재정의하려면 gatewayTargetName을 전달하세요:

myGateway.addMcpServer(myMcpServer, { gatewayTargetName: 'my-mcp' });

구성은 iamCredentialProvider.service = 'bedrock-agentcore'로 대상을 구성하여 Gateway가 자체 실행 역할을 사용하여 나가는 호출에 서명하도록 합니다.

Terraform

Gateway를 인스턴스화하는 Terraform 파일에서 MCP 서버 대상을 연결합니다:

packages/infra/src/main.tf

module "my_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
}

module "my_gateway" {
  source              = "../../common/terraform/src/app/gateways/my-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

# Register the MCP server as a target of the Gateway
resource "aws_bedrockagentcore_gateway_target" "my_mcp_server" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-mcp-server"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.my_mcp_server.invocation_url
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

대상 name(위의 my-mcp-server)은 Cedar 액션 이름의 접두사로 사용됩니다 — 정책 작성 섹션을 참조하세요. policy_dependencies는 이 대상의 액션을 참조하는 Cedar 정책이 대상이 등록한 후에 생성되도록 보장합니다.

로컬 개발

다음 명령으로 Gateway를 로컬에서 실행하면:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

로컬 게이트웨이와 할당된 로컬 포트의 모든 연결된 MCP 서버가 시작됩니다. 로컬 게이트웨이는 연결된 서버의 도구를 집계하는 단일 MCP 엔드포인트를 노출합니다. TypeScript 또는 Python 게이트웨이 연결 제너레이터를 통해 Gateway에 연결된 에이전트는 LOCAL_DEV=true로 실행할 때 이를 가리킵니다.

로컬 충실도

로컬 개발은 로컬 대체 게이트웨이를 사용합니다 — Gateway 프로젝트에서 시작된 경량 MCP 집계기이며, AgentCore Gateway 서비스가 아닙니다. 결과적으로 Cedar 정책은 로컬에서 평가되지 않습니다. 모든 에이전트는 연결된 모든 MCP 서버의 모든 도구를 볼 수 있습니다. Cedar 정책을 실행하려면 대신 에이전트의 serve 타겟을 실행하여(TypeScript / Python 에이전트 연결 가이드 참조) 로컬에서 실행 중인 에이전트가 배포된 Gateway를 호출하도록 하세요.

도구 이름은 배포된 Gateway의 네임스페이스와 일치하도록 로컬에서 여전히 <target-name>___<tool-name>으로 접두사가 붙으므로 에이전트의 시스템 프롬프트와 참조하는 Cedar 액션 이름이 로컬 및 배포된 실행에서 일관되게 유지됩니다.