Add secure Web Search to Claude Desktop with Amazon Bedrock AgentCore

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore Gateway의 관리형 Web Search를 Claude Desktop에 연결하고, AWS IAM Identity Center와 Amazon Cognito를 통한 JWT 인증으로 AWS 내부에서 검색과 인증을 처리하는 구성 방법을 설명한다.

📌 핵심 요약

• Amazon Bedrock을 사용하는 Claude Desktop은 통합 웹 검색이 없으면 학습 지식의 기준 시점에 제한된다. Web Search는 수백억 개 문서에 걸친 Amazon 웹 인덱스를 사용하는 완전 관리형 MCP 호환 기능이며, 원문은 검색 요청이 AWS 인프라 내부에 머물고 외부 API 키가 필요하지 않다고 설명한다.
• AWS IAM Identity Center가 SAML로 사용자를 인증하고, Amazon Cognito가 OAuth 2.0 authorization code grant 흐름에서 JWT를 발급하며, AgentCore Gateway가 요청마다 JWT를 검증한다. 이 구성은 기존 기업 SSO와 신원 거버넌스를 활용한다.
• 사전 조건은 IAM 역할 및 AgentCore 리소스 생성 권한, AWS Organizations 관리 계정의 관리자 접근 권한, 구성된 AWS IAM Identity Center SSO, Amazon Bedrock을 추론 제공자로 설정한 Claude Desktop, AWS CLI v2, Python 3.10 이상, 최신 Boto3이다. Web Search 지원 리전은 us-east-1, eu-west-1, ap-northeast-1이다.
• 구성은 Cognito 사용자 풀 생성, IAM Identity Center SAML 애플리케이션 및 사용자·그룹 할당, Cognito SAML 공급자 등록, 클라이언트 시크릿을 갖는 앱 클라이언트 생성, JWT 인증을 적용한 MCP Gateway 및 Web Search 대상 연결 순서로 진행된다.
• Claude Desktop에서는 Streamable HTTP, Gateway URL, Bring your own client 방식의 OAuth, Cognito Client ID와 Client Secret을 설정한다. 제공된 source_body는 Client Secret 입력 설명 도중 끝나므로 이후 연결 완료 절차와 검증 결과는 확인할 수 없다.

🧩 주요 포인트

1. 학습 지식의 기준 시점 제약 → 관리형 Web Search 연결을 통해 최근 문서, 현재 가격, 날씨 등 최신 정보 조회 경로를 추가한다.
2. AWS IAM Identity Center의 SAML 인증과 Amazon Cognito의 JWT 발급 분리 → 기존 기업 SSO를 AgentCore Gateway가 검증하는 토큰 기반 접근으로 연결한다.
3. 지원 리전·권한·클라이언트 설정에 의존하는 통합 → 검색 기능 도입에는 인증 체인과 MCP 연결을 함께 구성해야 하며, 잘린 원문만으로 연결 성공까지 판단할 수 없다.

🧠 상세 정리

1. 최신 정보 조회의 한계와 관리형 Web Search

원문은 Amazon Bedrock을 사용하는 Claude Desktop이 강력한 AI 지원을 제공하지만, 통합 웹 검색이 없으면 응답에 활용할 지식이 모델의 학습 기준 시점에 제한된다는 문제에서 출발한다. 최근 문서 업데이트, 현재 가격, 날씨처럼 최신 정보가 필요할 때 모델이 스스로 이를 가져올 수 없다는 것이 제시된 제약이다. Amazon Bedrock AgentCore는 프레임워크나 모델에 관계없이 에이전트를 대규모로 구축·연결·최적화하는 플랫폼이며, 그 기능인 AgentCore Gateway를 통해 Claude Desktop에 Web Search를 연결할 수 있다고 설명한다. Web Search는 수백억 개 문서에 걸친 Amazon 웹 인덱스를 기반으로 하는 완전 관리형 MCP 호환 기능이다. 원문은 모든 검색 요청 트래픽이 AWS 인프라에 머물며, 별도의 외부 API 키를 관리하거나 검색 요청을 경계 밖으로 보낼 필요가 없다고 강조한다.

2. 기업 SSO와 JWT를 연결하는 인증 구조

인증 구조는 AWS에서 운영되는 기업들이 AWS 계정의 SSO 접근에 AWS IAM Identity Center를 사용한다는 배경을 바탕으로 설계된다. 이 구성에서는 IAM Identity Center를 AgentCore Gateway의 인증 원천으로 사용해, Claude Desktop이 기업에서 관리하는 신원 흐름을 통해 Web Search를 호출하도록 한다. IAM Identity Center는 SAML로 사용자를 인증하고, Amazon Cognito는 OAuth 2.0 authorization code grant 흐름을 사용하는 연동 계층으로서 JWT를 발급한다. AgentCore Gateway는 각 요청에서 이 JWT를 검증하므로, 사용자 인증과 Gateway의 토큰 검증을 서로 연결할 수 있다. 원문은 전체 인증 체인이 AWS 내부에 유지되고 별도의 사용자 자격 증명이나 제3자 신원 제공자가 필요하지 않으며, 기존 조직의 신원 거버넌스에도 부합한다고 설명한다.

3. 필수 권한·도구와 지원 리전

실습에는 IAM 역할과 Amazon Bedrock AgentCore 리소스를 생성할 권한이 있는 AWS 계정이 필요하며, IAM Identity Center 설정을 위해 AWS Organizations 관리 계정에 대한 관리자 접근 권한도 요구된다. AWS IAM Identity Center는 AWS 계정에 대한 SSO 접근이 미리 구성되어 있어야 하고, Claude Desktop 역시 Amazon Bedrock을 추론 제공자로 사용하도록 설정되어 있어야 한다. 실행 도구로는 설치와 구성이 완료된 AWS CLI v2, Python 3.10 이상, 최신 버전으로 업데이트된 Boto3 SDK가 제시된다. 원문에서 Web Search가 현재 지원되는 리전은 미국 동부 버지니아 북부의 us-east-1, 유럽 아일랜드의 eu-west-1, 아시아 태평양 도쿄의 ap-northeast-1이다. 따라서 Gateway를 이 세 리전 중 하나에 생성하는 것이 실습의 명시적인 조건이며, 인증 설정과 별개로 리전 선택도 먼저 확인해야 한다.

4. Cognito 사용자 풀과 SAML 연동 식별자

첫 단계는 대상 AWS 계정에서 AgentCore Gateway의 OpenID Connect 토큰 발급자 역할을 할 Amazon Cognito 사용자 풀을 생성하는 것이다. 예시 사용자 풀 이름은 agentcore-websearch-pool이며, 이메일을 필수이자 변경 가능한 속성으로 두고 자동 검증 속성과 사용자 이름 속성에도 사용하도록 설정한다. 사용자 이름의 대소문자 구분은 비활성화하고, 예시 명령의 MFA 설정은 OFF로 지정되어 있다. 이어 사용자 풀 ID를 확인하고 전역적으로 고유한 접두사를 갖는 Cognito 도메인을 생성하며, 이후 단계에 사용할 사용자 풀 ID와 도메인 주소를 보관한다. SAML 연결에 필요한 Audience는 urn:amazon:cognito:sp:<user-pool-id>이고, ACS URL은 Cognito 도메인의 /saml2/idpresponse 경로이므로 다음 IAM Identity Center 애플리케이션 설정에 이 값을 사용한다.

5. IAM Identity Center SAML 애플리케이션과 Cognito 연결

두 번째 단계는 AWS Organizations 관리 계정의 IAM Identity Center에서 Cognito와 연동할 SAML 2.0 애플리케이션을 만드는 것이다. 표시 이름은 AgentCore Web Search로 설정하고, 메타데이터 값을 직접 입력하는 방식을 선택해 앞서 확보한 ACS URL과 Audience를 등록한 뒤 SAML 메타데이터 XML 파일을 내려받는다. 생성 후에는 Subject를 ${user:subject}에 매핑하고 형식을 Persistent로 지정하며, Email은 ${user:email}에 매핑하고 형식을 Basic으로 지정한다. Web Search 접근을 허용할 사용자나 그룹을 이 애플리케이션에 할당하는 과정도 포함된다. 이후 대상 계정으로 돌아와 내려받은 메타데이터를 사용해 Cognito 사용자 풀에 IAMIdentityCenterIdP라는 SAML 신원 제공자를 등록하고, 이메일 속성을 연결함으로써 IAM Identity Center와 Cognito 사이의 인증 연동을 구성한다.

6. OAuth 앱 클라이언트와 로컬 콜백 설정

네 번째 단계에서는 Cognito 사용자 풀에 agentcore-websearch-client라는 앱 클라이언트를 만들고 클라이언트 시크릿을 생성한다. Claude Desktop은 이 클라이언트를 통해 OAuth 흐름을 시작하며, 사용자는 IAM Identity Center에서 인증을 거쳐 AgentCore Gateway에 사용할 JWT를 받게 된다. 지원 신원 제공자는 앞서 등록한 IAMIdentityCenterIdP로 지정하고, 허용 OAuth 흐름은 code, 범위는 openid·email·profile로 설정한다. 콜백 URL은 http://localhost:53280/callback으로 지정되어 있으며, 생성 결과에서 Client ID와 Client Secret을 기록하도록 안내한다. 이 두 값은 뒤의 Claude Desktop 연결 설정에 사용되고, Client ID는 Gateway의 허용 클라이언트 설정에도 사용되므로 인증 체인의 양쪽을 연결하는 구성 요소가 된다.

7. JWT 기반 Gateway 생성과 Web Search 대상 연결

다섯 번째 단계의 Python 예시는 bedrock-agentcore.amazonaws.com이 대상 계정 조건 아래에서 수임할 IAM 실행 역할을 만들고, Gateway 조회·구성 번들 버전 조회·Web Search 호출 권한을 연결한다. Gateway는 MCP 프로토콜과 지원 버전 2025-03-26을 사용하며, 인증 유형을 CUSTOM_JWT로 지정하고 Cognito의 OIDC 검색 URL 및 허용 Client ID를 설정한다. 생성 후에는 15초 간격으로 최대 40회 상태를 확인해 READY가 되기를 기다리고, FAILED 상태나 약 10분의 대기 한도를 넘긴 경우 종료하도록 작성되어 있다. READY가 확인되면 web-search 관리형 커넥터를 web-search-tool이라는 대상으로 추가하고, 자격 증명 제공 유형을 GATEWAY_IAM_ROLE로 지정한다. 예시는 환경의 실제 값으로 자리표시자를 바꾸도록 안내하지만 IAM 권한 정책의 리소스 ARN에는 us-east-1이 고정되어 있어, 앞서 제시된 세 지원 리전과 코드의 리전 표기를 함께 살펴볼 필요가 있다.

8. Claude Desktop 연결 설정과 제공된 자료의 범위

마지막으로 제시된 단계는 Amazon Bedrock용 Claude Desktop의 구성 창을 열고 Connectors and Extensions에서 Add server를 선택한 뒤 Blank 서버를 추가하는 것이다. 서버 이름은 websearchtool로 지정하고, 전송 방식은 Streamable HTTP, URL은 앞서 생성한 AgentCore Gateway의 리소스 URL로 설정한다. OAuth 방식은 Bring your own client를 선택하며, Cognito 앱 클라이언트 생성 결과에서 얻은 Client ID와 Client Secret을 입력하도록 안내한다. 이 설정은 앞에서 준비한 Gateway 주소와 OAuth 클라이언트 정보를 Claude Desktop의 관리형 MCP 서버 연결에 적용하는 지점이다. 다만 제공된 source_body는 Client Secret 입력 설명의 마지막 부분에서 잘려 있어, 이후 사용자 인증 진행이나 연결 완료 확인, 실제 검색 실행 결과에 관한 내용은 이 자료로 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 이 통합의 핵심은 최신 정보 조회 경로를 추가하는 동시에, 검색 요청과 인증 체인을 AWS 내부에서 처리하도록 연결하는 데 있다.
• AWS IAM Identity Center와 Amazon Cognito는 각각 사용자 인증과 JWT 발급을 맡으며, AgentCore Gateway의 요청별 검증을 통해 기존 SSO를 검색 도구 접근에 적용한다.
• 외부 API 키가 필요 없다는 설명과 Cognito Client Secret을 설정한다는 절차는 함께 성립한다. 외부 검색 서비스의 키 관리 필요성이 없어져도 OAuth 앱 클라이언트 구성은 필요하다.

✅ 액션 아이템

• us-east-1, eu-west-1, ap-northeast-1 중 사용할 리전과 IAM 권한, AWS CLI v2, Python 3.10 이상, 최신 Boto3 등 사전 조건 충족 여부를 확인한다.
• AWS IAM Identity Center의 SAML 인증, Amazon Cognito의 JWT 발급, AgentCore Gateway의 JWT 검증으로 이어지는 인증 체인과 사용자·그룹 접근을 구성한다.
• Claude Desktop에 Streamable HTTP, Gateway URL, Bring your own client, Cognito Client ID와 Client Secret을 적용하고, 잘린 source_body 이후의 연결 완료 절차를 추가 확인한다.

❓ 열린 질문

• Gateway를 생성할 리전은 us-east-1, eu-west-1, ap-northeast-1 중 어디인가?
• 기존 AWS IAM Identity Center SSO와 AWS Organizations 관리 계정의 관리자 접근 권한 등 사전 조건은 충족되어 있는가?
• Client Secret 입력 설명에서 끝난 source_body 이후에 Claude Desktop 연결을 완료하고 실제 Web Search 동작을 확인하는 절차는 무엇인가?