Connect an AgentCore Runtime hosted MCP server to Amazon Quick

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

AgentCore Runtime에 호스팅한 MCP 서버를 AgentCore Gateway와 인증 체계를 통해 Amazon Quick에 연결하는 구성과 초기 구축 절차를 설명한다.

📌 핵심 요약

• Amazon Quick은 MCP 통합으로 외부 도구와 전문 하위 에이전트를 활용하며, 기존 MCP 서버의 도구를 재사용해 중복 개발과 개별 커넥터 구축을 줄일 수 있다.
• 연결 대상과 실행 요구에 따라 REST API 또는 AWS Lambda를 AgentCore Gateway에 연결하거나, 관리형 기능이 필요한 MCP 서버를 AgentCore Runtime에 호스팅하는 방식을 선택한다.
• Amazon Quick에서 AgentCore Gateway로 향하는 Inbound Auth는 사용자 접근을 승인하고, Gateway에서 Runtime으로 향하는 Outbound Auth는 AgentCore Identity와 OAuth 2.0을 활용해 시스템 간 인증과 권한 부여를 처리한다.
• 실습에는 Amazon Quick Author 이상 구독, AWS 리소스 생성 권한, Python 3.10+, AWS 자격 증명, 관련 SDK와 MCP 라이브러리, 실행 중인 Docker 데몬 등이 필요하며, 예제 서버는 stateless_http=True와 0.0.0.0:8000/mcp 경로를 사용한다.
• 제공된 본문은 MCP 서버 구현·배포, Gateway용 IAM 역할, 인바운드·아웃바운드용 Amazon Cognito 사용자 풀 설정을 설명하지만, AgentCore Identity의 OAuth 자격 증명 공급자 생성 안내 도중 끝나므로 Amazon Quick 등록과 통합 테스트의 상세 절차는 확인할 수 없다.

🧩 주요 포인트

1. 실행 요구에 따른 구성 선택 → 기존 API, 최소 실행 기능, 관리형 MCP 호스팅의 요구 차이가 Gateway 연결 대상과 Runtime 사용 여부를 결정한다.
2. 인바운드·아웃바운드 인증 분리 → 사용자 접근 승인과 시스템 간 호출 인증을 서로 다른 구간에서 구성하고, 예제에서는 Amazon Cognito 사용자 풀 두 개로 이를 구분한다.
3. 서버 배포와 통합 완료의 구분 → Runtime 배포 이후에도 Gateway 인증 및 Amazon Quick 연결이 필요하며, 제공된 본문만으로는 전체 통합의 완료 여부를 검증할 수 없다.

🧠 상세 정리

1. MCP 통합의 배경과 도구 재사용

MCP 서버는 기반 모델이 파일, 데이터베이스, API 같은 외부 데이터와 도구에 표준화되고 안전한 방식으로 접근하도록 지원한다. 원문은 이러한 접근이 AI 에이전트의 실제 애플리케이션 상호작용을 가능하게 하고, 정확한 맥락 제공을 통해 환각을 줄이며, 상태를 유지하는 여러 차례의 상호작용을 지원한다고 설명한다. Amazon Quick은 MCP 통합을 통해 자율 실행, 실시간 데이터 접근, 전문 AI 하위 에이전트 연결 기능을 활용한다. 이 글이 제시하는 연결 방식의 목적은 이미 MCP 서버에 공개한 공통 도구와 에이전트를 여러 클라이언트가 재사용하게 하여 같은 기능을 다시 개발하는 일을 줄이는 것이다. 고객은 이러한 통합을 통해 사용 사례마다 별도의 커넥터를 구축하지 않고도 Amazon Quick의 채팅 에이전트와 워크플로에서 제품 기능을 사용할 수 있다.

2. 실행 요구에 따른 연결 방식 선택

원문은 보유한 인터페이스와 필요한 실행 기능에 따라 Amazon Quick 연결 방식을 세 가지로 나눈다. 자체 REST API나 Amazon API Gateway에서 실행하는 API가 있다면 Amazon Bedrock AgentCore Gateway를 이용해 해당 API를 Amazon Quick과 직접 통합할 수 있다. 서버리스 구조를 선호하면서 AI 에이전트에 최소한의 실행 기능만 필요하다면 AWS Lambda 함수를 작성해 Gateway로 연결하는 방식을 제시한다. 세션 격리, 확장된 실행 시간, 영속 파일 시스템, 내장 인증, 관측 기능, 향상된 페이로드 지원, 양방향 스트리밍, 평가 기능이 필요하다면 AgentCore Runtime을 관리형 서버리스 MCP 호스팅 환경으로 사용할 수 있다. 이후 본문의 실습은 이 가운데 Runtime에 MCP 서버를 배포하고 Gateway를 거쳐 Amazon Quick에 연결하는 구성에 초점을 맞춘다.

3. 전체 연결 구조와 인증 구간

글 작성 시점의 Amazon Quick은 웹 브라우저나 데스크톱 앱에서 채팅 에이전트 또는 Flows를 통해 AI 에이전트 기능을 제공한다. 외부 MCP 서버의 도구와 하위 에이전트 기능을 사용하려면 Quick 측 커넥터와 AgentCore 측 Gateway를 통해 두 환경을 통합해야 한다. Amazon Quick에서 AgentCore Gateway로 들어오는 구간은 Inbound Auth라고 부르며, 요청을 인증하고 사용자의 MCP 서버 접근을 승인하는 역할을 맡는다. Gateway에서 AgentCore Runtime으로 나가는 구간은 Outbound Auth로 구분하고, AI 에이전트용 접근 관리 서비스인 AgentCore Identity를 활용해 시스템 간 인증과 권한 부여를 처리한다. 예제의 인바운드 인증에는 Amazon Cognito를 사용하지만 다른 자격 증명 공급자도 가능하며, 원문은 아웃바운드 인증에 OAuth 2.0을 사용한다고 설명한다.

4. 실습 전제 조건과 구현 순서

실습을 수행하려면 AWS 계정과 Amazon Quick Author 이상 구독이 필요하며, IAM 역할과 정책 및 AgentCore, Amazon Cognito, Amazon CloudWatch 리소스를 생성할 권한이 있어야 한다. 개발 환경에는 AWS SDK와 Python을 사용할 수 있는 명령줄 환경이 필요하고, AWS 서비스와 AWS CLI 및 Python에 대한 기본 지식도 전제한다. 원문은 Amazon Bedrock에서 Anthropic 모델 접근을 활성화하는 조건과 함께 Python 3.10 이상, 구성된 AWS 자격 증명, Amazon Bedrock AgentCore SDK, MCP 라이브러리, 실행 중인 Docker 데몬을 명시한다. 전체 구현 순서는 원격 MCP 서버 배포, 인바운드·아웃바운드 인증을 포함한 Gateway 연결, Amazon Quick 통합 등록과 채팅 에이전트 연결, 통합 테스트, 리소스 정리로 제시된다. 다만 제공된 본문에서 실제 상세 설명이 이어지는 범위는 서버 배포와 Gateway 인증 구성의 일부까지다.

5. FastMCP 서버 구현과 호환 조건

예제 프로젝트는 MCP 서버 코드를 담는 Python 파일, 의존성을 정의하는 requirements.txt, 패키지 표시용 init.py로 구성된다. 의존성에는 mcp 1.10.0 이상, boto3, bedrock-agentcore, bedrock-agentcore-starter-toolkit 0.1.21 이상, strands-agents가 포함되며, 원문은 uv로 가상환경을 만들고 패키지를 설치하는 명령을 제시한다. 서버는 FastMCP로 생성하고 Python 함수에 @mcp.tool() 데코레이터를 붙여 도구로 공개하며, getOrder는 123을 반환하고 updateOrder는 주문 식별자를 받아 456을 반환하는 모의 구현이다. AgentCore Runtime 호환을 위해 stateless_http=True를 설정하고 streamable-http 전송 방식으로 실행하며, 서비스가 기대하는 서버 주소와 경로는 0.0.0.0:8000/mcp다. 로컬 검증의 구체적인 방법은 연결된 샘플 노트북의 로컬 클라이언트 생성 및 테스트 절을 참고하도록 안내한다.

6. 스타터 키트를 통한 Runtime 배포

서버 구현 이후에는 터미널의 Bedrock 스타터 키트 또는 샘플 노트북에 제시된 Python 스크립트로 AgentCore Runtime에 배포할 수 있으며, 본문의 실습은 스타터 키트를 사용한다. 프로젝트 디렉터리에서 agentcore configure 명령에 진입점 mcp_server.py와 이름 simple_mcp_server를 지정하면 대화형 설정이 시작되고, 원문은 실습에서 기본값을 선택할 수 있다고 설명한다. 이 설정 과정은 컨테이너 실행에 필요한 Dockerfile과 .dockerignore를 생성하고, 런타임 설정 및 배포 매개변수를 저장하는 .bedrock_agentcore.yaml 파일도 만든다. 진입점 매개변수는 실행할 Python 파일을 지정하고 이름 매개변수는 AWS 계정 안에서 리소스 명명과 관리에 사용할 식별자를 부여한다. 구성이 끝나면 agentcore launch로 배포를 시작하며, 배포 이후 Runtime에서 MCP 서버를 확인하는 단계로 이어진다.

7. Gateway 역할과 인바운드 인증 설정

AgentCore Gateway는 Amazon Quick과 배포된 MCP 서버 사이의 안전한 연결 지점으로 구성되며, 원문은 기본 제공되는 종단 간 TLS를 포함해 인바운드와 아웃바운드 인증을 설정한다고 설명한다. 먼저 IAM에서 Amazon Bedrock AgentCore를 사용 사례로 선택해 Gateway가 수임할 역할을 만들고, 예시 이름으로 agentcore-sample-mcpgateway-role을 제시한다. 예시 정책에는 bedrock-agentcore:InvokeAgentRuntime, bedrock-agentcore:InvokeRegistryMcp, secretsmanager:GetSecretValue 작업이 포함되며, 리소스에는 배포한 Runtime과 런타임 엔드포인트의 ARN을 지정하도록 안내한다. 이어 Amazon Cognito에 인바운드 인증용 사용자 풀을 만들고 리소스 서버에 보호된 사용자 지정 범위 invoke를 정의해 Gateway가 요청 권한을 검증하도록 구성한다. 이후 단계에서 사용할 수 있도록 앱 클라이언트의 Client ID와 Client Secret, 사용자 풀의 OpenID 구성 Discovery URL을 기록하도록 설명한다.

8. 아웃바운드 인증과 제공된 설명의 범위

아웃바운드 인증에는 인바운드와 별도의 두 번째 Amazon Cognito 사용자 풀을 생성하며, 이 구성은 Gateway가 AgentCore Runtime에 호스팅된 MCP 서버를 호출할 때 자신을 인증하는 데 사용된다. 인바운드 설정과 마찬가지로 리소스 서버와 보호된 사용자 지정 범위 invoke를 만들고, 후속 구성에 필요한 Client ID, Client Secret, Discovery URL을 확보하도록 안내한다. 따라서 예제는 Quick의 접근 요청을 검증하는 사용자 풀과 Gateway의 서버 호출을 인증하는 사용자 풀을 구분해 서로 다른 인증 구간에 배치한다. 다음 단계로 AgentCore Identity에서 OAuth 자격 증명 공급자를 생성하라는 안내가 등장하지만, 제공된 본문은 해당 안내 도중 문장이 끊긴다. 이에 따라 자격 증명 공급자의 세부 설정, Gateway 엔드포인트 생성, Amazon Quick 등록, 통합 테스트 및 리소스 정리의 구체적인 실행 방법이나 결과는 제공된 자료에서 확인할 수 없다.

🧾 핵심 주장 / 시사점

• MCP 서버에 공개한 도구를 Amazon Quick에서도 재사용하는 구성은 동일 기능의 반복 개발과 사용 사례별 커넥터 구축을 줄이는 데 목적이 있다.
• Gateway 연결 방식의 선택은 기존 API 활용 여부와 필요한 실행 기능에 달려 있으며, Runtime은 관리형 MCP 호스팅 기능이 필요한 경우의 선택지로 제시된다.
• Runtime 배포와 전체 통합 완료는 별개이며, 제공된 본문의 인증 설정만으로 Amazon Quick에서 도구 호출이 성공했다고 판단할 수 없다.

✅ 액션 아이템

• 기존 API와 실행 요구를 기준으로 AgentCore Gateway 연결 대상 및 AgentCore Runtime 사용 여부 검토.
• Amazon Quick Author 이상 구독, Python 3.10+, Docker 데몬과 stateless_http=True 등 실습 조건 확인.
• 제공된 본문에서 누락된 AgentCore Identity 설정 이후의 Amazon Quick 등록·통합 테스트 상세 절차 확인.

❓ 열린 질문

• 현재 연결 대상과 실행 요구에는 REST API, AWS Lambda, AgentCore Runtime 중 어떤 구성이 적합한가?
• Inbound Auth와 Outbound Auth를 구분하는 Amazon Cognito 사용자 풀 두 개의 설정은 각각 완료되었는가?
• 제공된 본문에서 확인할 수 없는 Amazon Quick 등록과 통합 테스트의 상세 절차는 무엇인가?