AgentCore Gateway에서 MCP Server로

connection 생성기는 MCP 서버(TypeScript 또는 Python)를 AgentCore Gateway의 대상으로 등록할 수 있습니다.

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

전제 조건

이 생성기를 사용하기 전에 다음이 필요합니다:

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 서버는 연결할 수 없습니다.

사용법

생성기 실행

VSCode

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

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

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>-serve-local이 MCP 서버의 <mcp>-serve-local에 대한 종속성을 얻음
  • serve-local.ts ATTACHED_MCP_SERVERS가 로컬 gateway가 MCP 서버를 집계하도록 업데이트됨

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

스택에 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');

// MCP 서버를 Gateway의 대상으로 등록합니다. 대상 이름은
// 기본적으로 MCP 서버 구성의 id를 kebab-case로 변환한 것입니다 (`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]
}

# MCP 서버를 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 = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(module.my_mcp_server.agent_core_runtime_arn)}/invocations?qualifier=DEFAULT"
      }
    }
  }

  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>

로컬 gateway와 할당된 로컬 포트의 모든 연결된 MCP 서버가 시작됩니다. 로컬 gateway는 연결된 서버의 도구를 집계하는 단일 MCP 엔드포인트를 노출합니다. TypeScript 또는 Python gateway-connection 생성기를 통해 Gateway에 연결된 에이전트는 SERVE_LOCAL=true로 실행할 때 이를 가리킵니다.

로컬 충실도

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

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