Build interactive MCP Apps using Amazon Bedrock AgentCore

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore에서 MCP Apps를 배포하면 MCP Apps 확장을 지원하는 ChatGPT·Claude 등 여러 AI 호스트에 대화형 HTML 위젯과 기존 비즈니스 기능을 제공할 수 있다.

📌 핵심 요약

• MCP Apps는 Model Context Protocol(MCP)을 확장해 AI 호스트 안에서 대화형 HTML 위젯을 표시하며, 특정 호스트에 종속되지 않는 서비스 제공을 목표로 한다.
• 예제 Unicorn Rentals는 유니콘 목록 조회와 예약에 시각적 응답을 사용하고, 활성 예약 조회와 반납에는 텍스트로 응답한다.
• AgentCore runtime은 MCP 서버를 서버리스·세션 격리 환경에서 실행하고, AgentCore Gateway는 외부 AI 호스트가 접근하는 단일 엔드포인트를 제공한다.
• 예제의 Gateway는 인바운드 요청에 No Auth를 사용하고 AWS WAF로 IP 허용 목록·관리형 규칙·요청 속도 제한을 적용한다. runtime 호출은 Gateway의 IAM 실행 역할로 제한한다.
• TypeScript MCP 서버가 도구와 HTML 리소스를 제공하고, AWS Lambda와 Amazon DynamoDB가 비즈니스 로직과 데이터 저장을 담당한다. 배포에는 Node.js 22+, AWS CLI V2.0 이상, AWS CDK CLI 등이 필요하며 deploy.sh 실행 후 GatewayResourceUrl로 호스트를 연결한다.

🧩 주요 포인트

1. MCP Apps 확장을 지원하는 호스트가 공통 규격을 해석하므로, 하나의 MCP 서버로 여러 AI 호스트에 대화형 경험을 제공할 수 있다.
2. Unicorn Rentals는 요청에 따라 위젯과 텍스트를 구분하므로, 모든 응답에 시각적 인터페이스를 붙일 필요가 없다.
3. MCP 서버와 AWS Lambda의 역할 분리, AgentCore Gateway와 runtime의 접근 제어 분리는 프로토콜 처리·업무 처리·접근 경계를 각각 설계할 수 있게 한다.

🧠 상세 정리

1. AI 호스트 안에서 제공하는 대화형 서비스

글은 고객이 ChatGPT와 Claude 같은 AI 호스트를 통해 디지털 서비스에 접근하면서, 기업에도 일반 텍스트를 넘어 풍부한 사용자 인터페이스를 제공할 방법이 필요해졌다는 문제에서 출발한다. 동시에 서비스가 특정 호스트 하나에 결합되지 않아야 한다는 요구를 제시하며, 이를 위한 조합으로 MCP Apps와 Amazon Bedrock AgentCore를 소개한다. MCP Apps는 MCP를 확장해 호스트 내부에 대화형 HTML 위젯을 표시하고, AgentCore는 다양한 프레임워크와 모델을 사용하는 에이전트의 구축·연결·최적화를 지원한다. 이 예제에서는 runtime이 안전한 서버리스·세션 격리 실행 환경을 제공하고 Gateway가 단일 접근 엔드포인트를 맡으며, 동일한 대화형 경험의 제공 범위는 MCP Apps 확장을 지원하는 호스트로 한정된다.

2. Unicorn Rentals의 네 단계 이용 흐름

Unicorn Rentals 시연은 사용자가 자연어로 유니콘 전체 목록을 요청하면 호스트가 이미지, 이름, 설명, 시간당 요금, 이용 가능 여부를 담은 대화형 카드를 표시하는 것으로 시작한다. 이어 Stardust를 예약하고 싶다고 말하면 앱이 예약을 기록하고 예약 ID, 날짜, 시간당 요금, 예약한 유니콘을 즉시 확인해 준다. 활성 예약을 조회할 때는 현재 대여와 이용 시간, 그때까지 발생한 비용을 텍스트로 반환하며, 이는 모든 요청에 풍부한 시각적 인터페이스가 필요한 것은 아니라는 설명으로 이어진다. 마지막으로 반납을 요청하면 이용 시간과 시간당 요금을 기준으로 총비용을 계산해 대화에 표시하며, 이 전체 흐름은 Gateway 뒤의 단일 AgentCore runtime MCP 서버가 제공한다.

3. 호스트 등록과 업무 요청의 처리 경로

앱 등록 시 사용자는 MCP Server URL을 포함한 앱 정보를 제공하고, AI 호스트는 Gateway가 노출한 URL에 tools/list와 resources/list를 호출해 도구와 리소스를 발견한다. AWS WAF가 요청을 검사하고 Gateway가 IAM 실행 역할로 runtime을 호출하면 MCP 앱이 등록된 도구 또는 리소스 목록을 반환하며, 호스트는 이를 이후 사용을 위해 캐시할 수 있다. 실제 이용 단계에서는 호스트가 자연어 요청을 list_unicorns 같은 도구의 tools/call 메시지로 변환하고, 요청은 WAF와 Gateway를 거쳐 MCP 앱에 도달한다. MCP 앱은 업무 처리를 AWS Lambda에 위임하고 Lambda는 Amazon DynamoDB에서 조회나 예약 작업을 수행한 뒤 결과를 돌려주며, MCP 앱은 이를 MCP 형식으로 감싸 호스트에 반환한다. 이때 MCP 서버는 얇은 프로토콜 어댑터로 동작하고 업무 계층은 MCP를 알 필요가 없으므로, 실제 구현에서는 기존 Amazon ECS·Amazon EKS 등의 서비스를 HTTP 호출이나 SDK 클라이언트로 연결할 수도 있다.

4. 도구 응답과 분리된 HTML 위젯 렌더링

위젯 렌더링은 도구에 ui://widget/unicorn-list 같은 리소스 URI가 연결된 경우에만 시작되며, 도구 호출 뒤에 별도 단계로 진행된다. view_bookings와 return_unicorn처럼 연결된 위젯이 없는 도구는 텍스트만 반환하고 이 단계를 완전히 건너뛰므로, 동일한 서버가 시각적 응답과 텍스트 응답을 함께 제공할 수 있다. 위젯이 필요하면 호스트는 resources/read 요청을 보내고, Gateway를 거쳐 이를 받은 MCP 앱은 URI를 해석해 자체 완결적인 HTML을 반환하며 호스트는 성능 개선을 위해 해당 데이터를 캐시할 수 있다. 이후 호스트는 샌드박스 iframe에서 HTML을 렌더링하면서 MCP Apps 수명주기를 통해 도구 응답의 구조화된 데이터를 주입하고, 위젯에 필요한 이미지는 Amazon S3를 원본으로 사용하는 Amazon CloudFront에서 가져온다.

5. TypeScript 서버의 도구와 리소스 구현

예제 MCP 앱은 공식 @modelcontextprotocol/sdk와 대화형 위젯 제공을 위한 @modelcontextprotocol/ext-apps 확장을 사용하는 TypeScript 애플리케이션이며, AgentCore runtime이 내부적으로 관리하는 Express.js HTTP 서버로 실행된다. list_unicorns, book_unicorn, view_bookings, return_unicorn 같은 도구는 registerAppTool에 이름, 설정, 처리 함수를 전달해 등록하며 호스트의 도구 검색과 호출 요청에 대응한다. 도구 설정의 _meta.ui.resourceUri는 응답을 표시할 위젯을 가리키고, 도구 호출 응답의 structuredContent는 호스트가 렌더링 중 위젯에 주입할 데이터 페이로드를 담는다. 위젯은 registerAppResource에 리소스 이름과 URI, HTML을 반환하는 처리 함수를 제공해 MCP 리소스로 등록되므로, 업무 데이터 반환과 표시용 HTML 제공이 서로 구분된다.

6. AgentCore runtime의 배포와 실행 역할

빌드 과정은 MCP 앱 코드를 zip 파일로 묶고, 배포 단계는 이를 Amazon S3 버킷에 올린 뒤 해당 파일을 참조하는 AgentCore runtime 리소스를 생성한다. runtime 설정에는 NODE_22 실행 환경, 진입점, MCP 프로토콜 모드가 포함되며, MCP 모드 지정은 AgentCore에 서버의 프로토콜 유형을 알려 관련 최적화를 활성화한다. 글은 runtime을 MCP 앱 배포와 실행을 위한 안전한 서버리스 환경으로 설명하고, 들어오는 요청량에 따라 자동 확장되며 세션이 격리된다는 점을 강조한다. 또한 리소스 기반 정책으로 runtime을 호출할 수 있는 주체를 제한하는데, 이 솔루션은 AgentCore Gateway의 실행 역할만 허용하고 다른 주체는 거부하도록 구성해 서버 실행과 접근 제어를 함께 다룬다.

7. Gateway의 인증 연결과 WAF 보호

AgentCore runtime은 호출 인증으로 IAM의 SigV4와 OAuth를 지원하지만, 이 예제는 외부 AI 호스트가 접근할 수 있도록 runtime 앞에 AgentCore Gateway를 배치한다. Gateway는 인바운드 요청을 No Auth로 받아들이고 자신의 IAM 실행 역할과 SigV4를 사용해 runtime을 호출하므로, 외부 호출자가 AWS 자격 증명을 직접 처리할 필요가 없다. 공개 접근 경로의 보호는 AWS WAF가 담당하며, IP 허용 목록과 관리형 위협 탐지 규칙, 요청 속도 제한을 Gateway 엔드포인트에 적용한다. 따라서 예제의 보안 구성을 이해할 때는 외부 호스트에서 Gateway까지의 No Auth 설정, WAF의 요청 검사, Gateway에서 runtime으로 이어지는 IAM 인증, runtime 리소스 정책의 호출 주체 제한을 각각 구분해서 봐야 한다.

8. 배포 전제조건과 AI 호스트 연결

배포 전제조건은 AgentCore runtime 배포 권한을 갖춘 AWS 계정, Node.js 22 이상, 설치와 설정을 마친 AWS CLI V2.0 이상, 전역 설치된 AWS CDK CLI다. 사용자는 aws-samples의 sample-agentcore-mcp-apps 저장소를 복제하고 해당 디렉터리에서 bash deploy.sh를 실행하며, 이 단일 스크립트가 빌드와 CDK 스택 배포를 조정한다. 배포 후 출력되는 GatewayResourceUrl은 AI 호스트 연결에 필요하고, 저장소에는 특정 호스트의 연결을 위한 상세 설정 안내가 포함되어 있다고 설명한다. 제공된 본문은 ChatGPT에서 Developer mode를 켜고 새 플러그인을 생성해 이름을 UnicornRentals로 입력하는 절차까지 제시하지만, 설명 입력 부분에서 잘려 있어 이후 연결 단계와 결과는 이 자료만으로 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 여러 호스트에 대한 재사용성은 MCP Apps 공통 규격에서 나오지만, 실제 대화형 경험은 각 호스트의 MCP Apps 확장 지원을 전제로 한다.
• 도구가 반환하는 구조화된 데이터와 별도로 제공되는 HTML 리소스를 연결하는 방식이 업무 결과를 대화형 UI로 표현하는 핵심이다.
• 업무 로직을 MCP와 분리하면 기존 서비스를 연결할 여지가 생기며, 외부 접근 경로와 runtime 호출 권한 역시 별도의 경계로 관리할 수 있다.

✅ 액션 아이템

• 연결 대상 ChatGPT·Claude의 MCP Apps 확장 지원 여부 확인.
• Unicorn Rentals의 구분을 참고해 요청별 대화형 HTML 위젯과 텍스트 응답의 적용 범위 검토.
• 배포 전 Node.js 22+, AWS CLI V2.0 이상, AWS CDK CLI와 Gateway의 No Auth·AWS WAF·runtime IAM 접근 제어 구성 확인.

❓ 열린 질문

• 연결하려는 ChatGPT·Claude는 MCP Apps 확장을 지원하는가?
• Unicorn Rentals처럼 위젯과 텍스트를 구분할 때 어떤 요청에 대화형 HTML 위젯이 필요한가?
• AgentCore Gateway의 No Auth와 AWS WAF 보호, runtime의 IAM 실행 역할 제한이 목표 서비스의 접근 제어 요구에 부합하는가?