AWS 기술 블로그

Claude에서 사내 데이터를 안전하게: 한국일보의 Amazon Bedrock AgentCore Gateway 기반 사내 MCP 게이트웨이 구축기

들어가며

한국일보는 2026년 10월 27일부터 사내 MCP(Model Context Protocol) 게이트웨이 HAI Connector를 운영하고 있습니다. 구성원은 회사 Microsoft 365 계정으로 로그인해 Claude(claude.ai, Claude Code)에서 기사 검색, 홈페이지 행동 로그 분석, 클라우드 비용 조회, Google Analytics와 Search Console 조회 기능을 사용할 수 있습니다. 게이트웨이는 Amazon Bedrock AgentCore Gateway 위에 만들었고, 외부에서 호스팅하는 MCP 서버를 포함해 타깃 9개를 하나의 MCP 엔드포인트로 통합합니다.

게이트웨이가 하는 일은 네 가지입니다.

  • 로그인: 회사 Microsoft 365 계정을 통해 claude.ai와 Claude Code에서 연결합니다

  • 권한: 역할에 따라 보이는 도구와 읽을 수 있는 데이터를 다르게 합니다

  • 감사: 모든 호출의 판정과 결과를 로그로 남깁니다

  • 확장: 다른 팀이 PR로 자기 시스템의 도구를 추가합니다

게이트웨이를 구성할 때 보안 측면에서 고려할 점이 있었습니다. 같은 게이트웨이를 사용하더라도 사람마다 보이는 도구와 읽을 수 있는 데이터가 달라야 했습니다. 이 글은 해당 요구를 AgentCore Gateway의 인바운드 인증 위에 어떻게 구현했는지, 무엇을 검토하고 골랐는지 설명합니다. 이어서 도메인 지식을 권한대로 주는 방식, claude.ai 같은 상용 클라이언트와 외부 MCP 서버를 연결하며 겪은 문제와 해결 방안, 그리고 다른 팀이 도구를 추가하는 운영 체계를 다룹니다.

이 글에서 게이트웨이(HAI Connector)는 서비스 전체를, AgentCore Gateway는 그 기반이 되는 AWS 관리형 리소스를, 커넥터는 claude.ai 같은 클라이언트에 등록한 연결을 뜻합니다.

그림 1. HAI Connector 전체 구성
그림 1. HAI Connector 전체 구성

1. 문제 정의: 왜 MCP 게이트웨이인가

팀마다 MCP 서버를 만들 경우

Claude에서 사내 데이터를 쓰려는 요구가 늘면서 기사 검색과 클라우드 비용 조회 MCP 서버가 이미 따로 운영되고 있었고, 행동 로그 같은 다른 시스템에도 같은 요구가 이어졌습니다. 이대로 늘어나면 네 가지 문제가 생깁니다.

  • 커넥터가 시스템 수만큼 늘어납니다. 사용자는 Claude에 커넥터를 하나씩 추가하고 로그인해야 하고, 관리자는 조직 커넥터를 하나씩 검토해 등록해야 합니다

  • 인증과 인가를 서버마다 다시 만듭니다. 구현 수준이 서버마다 달라지고, 한 곳이라도 허술하면 그 서버를 통해 사내 데이터가 유출될 수 있습니다

  • 권한 변경도 서버 수만큼 해야 합니다. 입사, 퇴사, 부서 이동이 생길 때마다 서버마다 반영해야 합니다

  • 누가 어떤 데이터를 조회했는지 한 곳에서 볼 수 없습니다. 감사 로그 형식도 서버마다 다릅니다

그래서 MCP 게이트웨이 하나를 두기로 했습니다. 사용자는 커넥터 하나에 한 번 로그인하고, 인증, 인가, 감사는 게이트웨이 한 곳에서 처리합니다. 각 팀은 인증을 따로 만들지 않고 도구 로직만 만들어 게이트웨이 뒤에 붙입니다. 요구사항을 정리하며 굳힌 원칙은 세 가지입니다.

  • 인증은 회사 Microsoft 365 계정(Microsoft Entra ID)으로 합니다

  • 데이터베이스에 직접 붙지 않고 API를 거칩니다. 행동 로그만 Amazon Athena 직결을 예외로 둡니다

  • 권한은 도구 단위로, 사람이 아니라 역할에 줍니다

인증만으로는 어려운 세밀한 제어

Amazon Bedrock AgentCore Gateway는 AWS Lambda 함수, 기존 MCP 서버, API를 타깃으로 등록해 하나의 MCP 엔드포인트로 통합하는 관리형 서비스입니다. 들어오는 요청은 인바운드 인증에서 토큰을 검증받고, 요청과 응답 사이에는 Lambda 인터셉터를 둘 수 있습니다. 한국일보의 타깃은 직접 만든 Lambda 도구와 MCP 서버 두 종류입니다.

AgentCore Gateway의 인바운드 인증(Custom JWT, JSON Web Token)은 토큰의 서명, 발급자, 대상, 범위를 검증합니다. 서명을 바꾼 토큰이나 서명이 없는 토큰은 AgentCore Gateway에서 막힙니다. 여기까지가 “이 사람이 조직 구성원인가”에 대한 답이고, 필요한 판단은 그다음이었습니다.

질문 답하는 곳
이 토큰이 유효한가 AgentCore Gateway 인바운드 인증
이 사람에게 이 도구가 보여야 하는가 직접 만들어야 함
이 사람이 이 도구를 호출해도 되는가 직접 만들어야 함
이 사람이 이 데이터를 읽어도 되는가 직접 만들어야 함

AgentCore Gateway 사례에는 에이전트가 기계 간(M2M) 토큰으로 AgentCore Gateway를 호출하는 구성이 많습니다. 한국일보의 클라이언트는 claude.ai와 Claude Code라서, 사람이 직접 로그인하고 그 사람의 권한으로 도구를 씁니다. 이 때문에 Entra ID 사용자 토큰을 인바운드 인증에 그대로 쓰고, 역할은 Entra 앱 역할로 부여해 토큰의 roles 클레임으로 받습니다. AgentCore Gateway는 “어느 에이전트인가”가 아니라 “어느 사람이, 어떤 역할인가”를 알게 됩니다.

초기에는 IAM role과 데이터 권한만으로 접근을 제한하는 방안도 검토했습니다. 이 방식은 권한 없는 호출을 거부하지만 tools/list에는 권한 없는 도구가 그대로 보입니다. 쓸 수 없는 도구가 목록에 있으면 모델이 그 도구를 골라 실패하고, 도구 이름과 인자 구조가 권한 없는 사람에게 드러납니다. 목록과 호출을 함께 다룰 계층이 필요했습니다.

도구 분할과 판정 위치의 트레이드오프

설계 초기에 가장 오래 고민한 것은 도구를 어떻게 나누고, 인가를 어디서 판정할지였습니다. 당시에는 MCP 도구가 사내 데이터베이스에 직접 접속하는 구성을 전제로 두 가지 안을 비교했습니다.

방식 도구 수 데이터베이스 계정 수 예) 권한이 5개일 때 문제점
권한마다 도구를 따로 둠 권한 수만큼 권한 수만큼 도구 5개, 계정 5개 비슷한 도구가 늘수록 모델이 엉뚱한 도구를 고를 수 있음
데이터베이스별 도구 하나에서 계정을 고름 데이터베이스 수만큼(적음) 권한 조합만큼(2ⁿ−1) 도구 1개, 계정 31개 여러 권한을 가진 사람을 위해 조합마다 계정이 필요

어느 쪽이든 트레이드오프가 있었습니다. 도구가 많아져 모델이 헷갈리는 쪽과, 계정이 많아져 사람이 관리하기 어려워지는 쪽 중 하나를 받아들여야 했습니다. 특정 사람에게 권한을 하나씩 더 주는 일이 잦을수록 이 부담은 커집니다. 첫 번째 방식에서는 그 사람의 도구 목록이 길어지고, 두 번째 방식에서는 새 조합에 맞는 계정을 또 만들어야 합니다.

두 안은 권한을 도구 수나 데이터베이스 계정 수로 표현한다는 전제가 같았습니다. 한국일보는 판정을 게이트웨이의 인터셉터에 맡겨 권한과 도구 수를 분리했습니다. 같은 시스템의 도구를 권한별로 복제하지 않고, 도구는 시스템 단위(기사 검색, 행동 로그, 비용 조회 등)로 하나씩 둡니다. 사람마다 달라지는 것은 도구 개수가 아니라 보이는 도구 목록입니다. 모델은 사용자의 역할에 허용된 도구만 보게 되고, 누군가에게 권한을 더 주는 일은 Entra ID에서 그 사람의 역할을 바꾸는 것으로 끝납니다. 도구도 계정도 새로 만들 필요가 없습니다.

데이터 권한도 같은 원칙으로 다뤘습니다. 행동 로그를 Amazon Athena로 조회하는 도구는 하나뿐입니다. 대신 요청 인터셉터가 JWT에서 호출자의 역할을 확인하고 그에 맞는 IAM role을 지정해 전달하며, 도구는 그 IAM role로 조회합니다. IAM role마다 읽을 수 있는 데이터 범위가 달라서, 같은 도구를 써도 역할에 따라 보이는 데이터가 다릅니다. IAM role은 클라이언트나 모델이 고를 수 없고 인터셉터만 지정합니다. 결과적으로 권한 조합마다 데이터베이스 계정을 만드는 대신 역할마다 IAM role을 하나씩 두며, IAM role은 임시 자격 증명으로 동작하므로 따로 관리할 비밀번호도 없습니다.

2. 인터셉터와 권한표로 인가

AgentCore Gateway는 요청이 타깃에 가기 전과 응답이 클라이언트로 돌아가기 전에 AWS Lambda 인터셉터를 부를 수 있습니다. 한국일보는 이 두 지점에 인가 절차를 추가했습니다.

요청 판정 판정하는 곳
tools/call (도구 호출) 권한이 없으면 거부 요청 인터셉터, 타깃 호출 전
tools/list (도구 목록) 권한 밖 도구를 목록에서 제거 응답 인터셉터, 클라이언트 응답 전

두 인터셉터는 같은 권한표와 판정 함수를 공유하므로 목록 조회와 호출의 기준이 같습니다. 권한 없는 호출은 요청 인터셉터에서 차단됩니다. 거부된 호출에서는 대상 Lambda 실행 로그가 0건이었고, 권한 있는 사용자의 호출에서는 로그가 기록되었습니다.

그림 2. tools/list는 응답 인터셉터, tools/call은 요청 인터셉터에서 판정하며, 둘 다 동일한 권한표와 판정 함수 사용
그림 2. tools/list는 응답 인터셉터, tools/call은 요청 인터셉터에서 판정하며, 둘 다 동일한 권한표와 판정 함수 사용

권한 정보는 기존 시스템에

권한 정보를 위한 별도 저장소는 만들지 않았습니다. 대시보드의 권한 관리 화면도 자체 데이터 없이 아래 두 원본을 직접 수정합니다.

정보 저장 위치 관리
사람 → 역할 Entra 앱 역할 할당(사람 또는 기존 부서 그룹에) 게이트웨이 운영자(대시보드에서 Graph API로 할당)
역할 → 도구, 데이터 접근 IAM role Amazon S3의 permissions.json 게이트웨이 운영자

권한표에는 사용자를 적지 않습니다. 누가 어떤 역할인지는 Entra에서 정하므로, 권한표는 역할과 도구의 관계가 바뀔 때만 수정하면 됩니다. 권한표의 구성은 아래와 같습니다(역할과 도구 이름은 예시).

역할 쓸 수 있는 도구 데이터 접근 IAM role
analyst account___*, news___*, logs___* 행동 로그용 role
general (기본 역할) account___*, news___* 없음
  • 도구 이름은 AgentCore Gateway 명명 규칙에 따라 <타깃>___<도구> 형식이므로 `account___*`처럼 접두사 와일드카드 한 줄로 한 시스템의 도구 전체를 허용할 수 있습니다.

  • 역할이 할당되지 않았거나, 할당된 역할이 모두 권한표에 없으면 기본 역할(general)을 적용합니다.

  • 권한표의 어떤 역할에도 없는 도구는 호출을 거부합니다. 그래서 새 타깃을 연결해도 권한표의 역할에 추가하기 전에는 쓸 수 없습니다.

권한 변경은 배포 없이 반영

인터셉터는 60초마다 ETag 조건부 요청으로 권한표를 다시 읽으므로, 수정한 권한표를 S3에 올리면 각 실행 환경에 약 60초 안에 반영됩니다. 실제로 권한표에서 한 역할의 허용 도구 범위를 좁히자, 재로그인 없이 같은 토큰으로 요청해도 tools/list 응답에서 해당 도구가 빠졌고 그 도구의 호출도 거부되었습니다. 이 과정에서 Lambda는 재배포하지 않았습니다.

3. 세 가지 보안 설계

권한 밖 도구는 목록에도 보이지 않도록 설정

응답 인터셉터는 tools/list 응답에서 권한 밖 도구를 제거합니다. 본인 권한을 조회하는 도구도 호출한 사용자의 역할과 허용 도구 패턴만 반환합니다. 다른 역할의 이름이나 IAM role ARN(Amazon 리소스 이름)은 노출하지 않습니다.

데이터 계층에서 한 번 더 검증

행동 로그 도구는 모델이 작성한 SQL을 Athena에서 실행합니다. 이때 사용자 역할에 맞는 IAM role을 수임해 실행합니다. 어떤 role을 수임할지는 권한표에서 역할과 타깃별로 지정하고, 테이블 단위 접근 권한은 각 IAM role에 부여합니다. 따라서 인터셉터 판정을 통과하더라도 해당 role로 볼 수 없는 테이블은 IAM 단계에서 거부됩니다. 이를 통해 권한별 테이블 조회 범위를 제어할 수 있습니다.

사용자 정보는 항상 덮어쓰도록 설정

요청 인터셉터는 토큰에서 읽은 사용자와 역할을 도구 인자에 넣어 Lambda 도구에 전달합니다. 문제는 클라이언트도 같은 이름의 인자를 보내는 게 가능하다는 점입니다.

이를 검증하고자 낮은 권한의 토큰으로 다른 팀의 신원과 수임할 role을 인자에 직접 넣어 요청해 보았습니다. 도구는 토큰의 원래 권한으로 실행되었고, 감사 로그에도 토큰의 신원이 기록되었습니다. 인터셉터가 클라이언트가 보낸 값과 관계없이 항상 덮어쓰기 때문입니다.

이 동작을 “값이 없을 때만 넣는다”와 같은 조건부로 바꾸면 위조된 값이 그대로 통과합니다. 그래서 클라이언트가 보낸 role 값을 버리는 동작을 단위 테스트로 고정했습니다. 신원 정보는 직접 만든 Lambda 도구에만 전달하고, MCP 서버 타깃에는 전달하지 않습니다.

감사 로그는 인터셉터가 Amazon CloudWatch Logs에 JSON 한 줄로 기록합니다. 호출자, 도구, 인자, 판정 결과, 결과 상태를 남기고, 토큰과 결과 본문은 남기지 않습니다.

그림 3. 인증 및 인가 통제 절차
그림 3. 인증 및 인가 통제 절차

4. 검토했던 대안: AgentCore Policy(Cedar)

AgentCore에는 Cedar 기반 정책 엔진인 AgentCore Policy가 있습니다. 먼저 이 기능을 시험했는데, Cedar forbid 정책만으로도 목록에서 도구를 숨기고 호출을 차단할 수 있었습니다. 그럼에도 아래 이유로 권한표 방식을 선택했습니다.

기준 AgentCore Policy (2026년 9월 시험 기준) 권한표 + 인터셉터
배열 클레임 비교 역할 이름을 정확히 비교하는 정책을 구성하지 못함. 부분 문자열 비교(like)만 동작 역할 이름을 정확히 비교
권한 변경 정책 수정 권한표 파일 수정, 약 60초 안 반영
신원 주입 정책만으로는 불가, 별도 인터셉터 필요 판정하는 인터셉터가 함께 처리하고, 감사 로그도 같은 위치에서 기록
자연어로 정책 생성 생성된 정책을 사람이 전부 검증해야 함 해당 없음

역할은 토큰에 배열(roles)로 담겨 옵니다. 시험은 초기 인증 구성이었던 Amazon Cognito의 그룹 클레임으로 진행했습니다. 그런데 토큰에서는 배열이던 값이 정책에서는 문자열로 노출되어, 역할 이름을 정확히 비교하는 정책을 구성할 수 없었습니다. 동작하는 like는 부분 문자열 비교라서 editorial 역할에 대한 조건이 editorial-interns 역할에도 일치했습니다. 자연어 정책 생성은 모호한 요청을 거부하는 판단은 정확했지만, 생성된 정책은 사람이 전부 검증해야 했습니다. 위 결과는 2026년 9월 시험 기준이며, 이후 동작은 달라졌을 수 있습니다.

권한 정보를 위한 저장소를 새로 만들지 않은 것도 같은 판단입니다. 사람과 역할은 회사가 이미 관리하는 Entra ID에, 역할과 도구는 JSON 파일 하나에 둡니다. 관리 화면은 이 둘을 고칠 뿐이라, 지켜야 할 원본이 늘지 않습니다.

5. 도메인 지식은 목차부터, 권한대로

홈페이지 행동 로그 도구는 모델이 쓴 SQL을 Amazon Athena에서 실행합니다. 모델이 올바른 SQL을 쓰려면 테이블 스키마만으로는 부족합니다. 이벤트의 의미, 봇 제외 규칙, 지표 계산식 같은 도메인 지식이 필요합니다. 그런데 이 지식을 한 번에 주면 컨텍스트의 상당 부분을 차지합니다.

검색 대신 목차를 사용

벡터 검색(RAG)과 키워드 검색(BM25)도 검토했지만, 모델이 목차를 보고 필요한 주제를 직접 고르는 방식을 택했습니다. 행동 로그의 규칙들이 서로 연결되어 있기 때문입니다. 예를 들어 체류 시간은 서비스 개편 전후로 계산식이 다릅니다. 이렇게 연결된 규칙은 검색으로 꺼낸 조각에 한쪽만 담길 수 있고, 그러면 모델은 다른 쪽이 있다는 것을 알기 어렵습니다. 따라서 목차를 먼저 보여 주어 모델이 어떤 주제가 있는지 알고 필요한 문서를 고를 수 있게 했습니다.

도메인 지식은 주제별 마크다운 문서와 질문, SQL 예시로 나누어 정리했습니다. 각 문서의 머리말에는 언제 읽어야 하는지를 설명하는 한 줄과 다루는 테이블 목록을 적어 둡니다. 모델은 아래 순서로 지식을 참고하며, 각 도구를 언제 호출할지는 도구 설명(description)에 적어 두었습니다.

  1. 컨텍스트 도구를 인자 없이 호출하면 핵심 문서 하나와 목차를 받습니다. 목차는 “체류 시간과 열독 시간 질문. 개편 전후로 계산식이 다르다”처럼 주제마다 한 줄입니다

  2. 질문에 맞는 주제가 있으면 해당 주제 이름으로 그 문서만 읽습니다

  3. 예시 도구에서 질문 목록만 받고, 비슷한 질문의 번호로 SQL을 받아 출발점으로 씁니다

  4. 쿼리를 실행합니다

그림 4. 사용자 IAM role 기준의 문서·예시 필터링
그림 4. 사용자 IAM role 기준의 문서·예시 필터링

핵심 문서(스키마, 업무 규칙, 이벤트와 필드 사전)는 나누지 않고 한 번에 제공합니다. 컬럼은 모든 행에 있지만, 실제로 값이 채워지는지는 이벤트마다 다르기 때문입니다. 예를 들어 성별은 로그인 이벤트에만 채워집니다. 모델이 스키마만 보고 기사 조회 이벤트에 성별 조건을 걸면, 쿼리는 오류 없이 0행을 반환합니다. 또한 목차와 테이블 목록에 없는 데이터는 없다고 답하라는 지시도 함께 넣어 둡니다.

모델이 작성한 SQL은 실행 전에 한 번 더 검사합니다. 파티션 조건이 없는 전체 스캔과 행 수 제한(LIMIT)이 없는 SELECT *는 거부하고, 모델이 쿼리를 고칠 수 있도록 거부 사유를 함께 반환합니다. SQL을 파싱할 수 없는 경우에도 실행하지 않습니다. 이와 별도로 전용 Athena 작업 그룹에는 쿼리당 스캔 용량 상한을 설정했습니다.

데이터 권한에 맞춘 문서 공개 범위

행동 로그 도구는 사용자 역할에 맞는 IAM role로 쿼리를 실행하므로, 볼 수 없는 테이블을 조회하면 IAM이 거부합니다. 데이터는 이렇게 보호됩니다.

하지만 도메인 지식 문서(주제별 마크다운 문서와 질문, SQL 예시)는 Lambda 패키지 안에 함께 들어 있는 파일입니다. Lambda는 AWS 서비스를 거치지 않고 이 파일을 바로 읽기 때문에, 문서에는 IAM 권한이 적용되지 않습니다. 따로 처리하지 않으면 도구를 호출한 사용자는 역할과 관계없이 모든 문서를 받게 됩니다. 그러면 데이터를 조회하지는 못해도, 볼 수 없는 테이블이 있다는 사실과 그 테이블의 구조와 의미는 알게 됩니다. 데이터 권한을 나눈 의미가 줄어드는 것입니다.

그래서 문서의 공개 기준을 데이터 권한에 맞췄습니다.

  • 문서: 도구가 호출한 사용자의 role로 AWS Glue Data Catalog에 요청해, 문서 머리말에 적힌 테이블에 접근할 수 있는지 확인합니다. 모든 테이블에 접근할 수 있을 때만 그 문서를 응답에 포함합니다.

  • 예시: SQL에서 사용하는 테이블을 추출해 같은 기준으로 확인합니다.

  • 목차: 호출할 때마다 확인을 통과한 문서로만 새로 만들기 때문에 볼 수 없는 주제는 목차에도 나오지 않습니다.

  • 이름으로 직접 요청한 경우: 권한 밖 주제와 존재하지 않는 주제에 글자 하나까지 같은 응답을 반환합니다. “권한 없음”이라고 답하면 그 주제가 있다는 사실이 드러나기 때문입니다.

예를 들어 회원 속성 테이블에 접근할 수 없는 역할의 사용자에게는 “회원 속성 분석” 관련 문서가 응답과 목차에서 모두 빠집니다. 이 이름으로 직접 요청해도 존재하지 않는 주제와 같은 응답을 받습니다. 즉, 문서용 권한 판정을 따로 두지 않고 데이터 권한을 그대로 확인하므로, 테이블 권한을 바꾸면 문서 공개 범위도 함께 바뀝니다.

핵심 문서는 가장 기본이 되는 로그 테이블 하나만 다루도록 제한했습니다. 다른 테이블 내용이 섞이면 그 테이블에 접근할 수 없는 사용자는 핵심 문서 전체를 받지 못하기 때문입니다.

지식 문서는 배포 전에 형식 검사

이 방식은 문서 머리말의 테이블 목록이 정확해야 제대로 동작하므로, 문서를 수정하면 PR 테스트에서 형식과 테이블 선언을 검사하고, 테스트를 통과해야만 배포됩니다. 검사 항목은 다음과 같습니다.

  • 본문에 나오는 테이블이 모두 머리말에 적혀 있는가

  • 핵심 문서가 기본 테이블만 다루는가

  • 다른 주제를 참조할 때, 참조하는 주제가 현재 문서보다 더 넓은 권한을 요구하지 않는가

  • 예시 SQL이 실행 전 쿼리 검사를 통과하는가

다만 테스트는 형식만 검사할 뿐, 문서 내용이 정확한지는 판단하지 못하므로, 계산식 같은 내용은 사람이 예시 SQL을 직접 실행해 확인합니다.

권한표는 약 60초 안에 반영되지만, 지식 문서는 Lambda와 함께 배포되므로 수정하려면 재배포가 필요합니다. 도메인 지식은 자주 바뀌지 않으므로, 코드와 같은 리뷰 절차를 거치는 편이 낫다고 판단했습니다.

6. 상용 클라이언트와 연결하며 겪은 문제

게이트웨이에 붙는 클라이언트는 claude.ai와 Claude Code 같은 상용 클라이언트입니다. 클라이언트도, 관리형 AgentCore Gateway도 한국일보가 고칠 수 없는 영역이라, 둘의 동작이 어긋나는 곳은 게이트웨이 쪽에서 맞춰야 했습니다.

1시간마다 끊기는 연결

증상: claude.ai 조직 커넥터로 게이트웨이를 연결하면 약 1시간마다 연결이 끊깁니다. 그때마다 사용자가 커넥터를 다시 연결해야 합니다.

원인: 토큰 갱신 실패와 만료 토큰에 대한 403 응답, 두 문제가 겹쳤습니다.

해결: AgentCore Gateway 앞에 Amazon CloudFront 프록시를 두었습니다. 갱신 요청은 수정해서 전달하고, 만료된 토큰은 AgentCore Gateway로 보내기 전에 401로 응답합니다.

연결이 끊긴 시간대에 인터셉터 감사 로그에는 커넥터 요청이 한 건도 없었습니다. 요청이 인터셉터에 도달하기 전, AgentCore Gateway 인증 단계에서 이미 거부됐다는 뜻입니다. 토큰이 만료된 뒤 연결이 자동으로 복구되지 않은 원인은 두 가지였습니다.

  1. 클라이언트의 토큰 갱신 요청에 scope가 없었습니다. 커넥터와 API가 같은 Entra 앱 등록을 쓰는 구성에서는, Entra ID가 이 요청을 “앱이 자기 자신에게 토큰을 요청”한 것으로 보고 거부합니다. Entra ID는 refresh token 하나로 여러 API의 토큰을 받는 구조라 갱신에도 scope가 사실상 필수입니다. 같은 refresh token에 scope만 넣으면 갱신이 성공했습니다. 이 동작은 공개 이슈로도 보고돼 있습니다

  2. AgentCore Gateway가 만료된 토큰에 403(insufficient_scope)을 반환했습니다. 만료 직후에도, 몇 분 뒤에도 같았습니다. 반면 claude.ai는 401을 받아야 토큰 갱신을 시도합니다.

두 문제 모두 AgentCore Gateway 설정으로는 바꿀 수 없었습니다. 또한 AgentCore Gateway가 401을 반환하더라도 이어지는 갱신 요청이 여전히 실패하므로, 두 문제를 함께 해결해야 했습니다. 이를 위해 게이트웨이 앞에 전용 CloudFront 배포를 두었습니다.

구성 요소 하는 일
CloudFront Functions (viewer-request) OAuth 메타데이터를 직접 응답합니다. 토큰이 없거나 만료 60초 전이면 AgentCore Gateway로 보내지 않고 401을 반환합니다
토큰 중계 AWS Lambda 메타데이터에 token endpoint로 지정된 함수입니다. 갱신 요청에 scope가 없으면 채우고, resource 파라미터는 제거한 뒤 Entra ID로 전달합니다.
그 밖의 요청 AgentCore Gateway로 그대로 전달합니다. 로그인은 Entra ID로 직접 갑니다

만료 토큰은 응답을 고치지 않고, AgentCore Gateway로 보내기 전에 엣지에서 판정합니다. 오리진이 오류 상태 코드(400 이상)를 반환하면 CloudFront Functions의 viewer-response가 실행되지 않기 때문입니다. 이 방식 덕분에 Lambda@Edge 없이 구성할 수 있었습니다. 엣지 Function은 서명은 확인하지 않고 만료 시각(exp)만 봅니다. 엣지는 거부만 담당하고, 통과한 토큰의 검증은 AgentCore Gateway가 맡습니다.

적용 후 커넥터를 연결하고 75분 뒤 자동 갱신이 성공했고, 2시간이 넘도록 재연결 없이 도구를 호출할 수 있었습니다. 이 프록시는 커스텀 도메인을 연결하는 지점 역할도 합니다. 커넥터 아이콘은 등록한 주소의 도메인에서 가져오므로, 회사 도메인을 쓰면 회사 로고가 표시됩니다. 처음에는 아이콘 하나 때문에 프록시를 두는 것은 과하다고 판단해 보류했지만, 결국 같은 프록시가 토큰 문제의 해법이 되었습니다.

그림 5. 프록시 도입 전: 토큰 갱신 실패와 403 응답으로 연결 끊김 / 도입 후: 토큰 중계 Lambda가 갱신 요청을 보완하고, 엣지가 만료 토큰에 401 반환
그림 5. 프록시 도입 전: 토큰 갱신 실패와 403 응답으로 연결 끊김 / 도입 후: 토큰 중계 Lambda가 갱신 요청을 보완하고, 엣지가 만료 토큰에 401 반환

비어 버린 도구 목록

증상: claude.ai가 커넥터를 “연결됨”으로 보여 주지만 쓸 수 있는 도구가 0개입니다. 수동으로 “도구 새로고침”을 눌러야 목록이 돌아옵니다.

원인: claude.ai의 백그라운드 동기화는 tools/list 응답을 약 5초만 기다립니다. 그 안에 응답이 없으면 요청을 취소하고 빈 도구 목록을 저장합니다. 그런데 응답 인터셉터의 첫 tools/list가 콜드 스타트로 6.1~6.9초 걸렸습니다.

해결: 두 인터셉터의 메모리를 128MB에서 512MB로 올리고, AWS SDK 클라이언트를 컨테이너당 한 번만 만들게 했습니다.

로그를 보면 claude.ai가 백그라운드 동기화에서 보낸 요청이 모두 4~5초 만에 취소됐습니다. 같은 기간 컨테이너의 첫 tools/list는 모두 6초를 넘겼고, 두 번째부터는 0.2~0.7초였습니다. 느린 구간은 128MB에서 AWS SDK를 불러오고 클라이언트를 만드는 초기화였습니다. 한동안 호출이 없으면 새 컨테이너가 뜨기 때문에, 증상은 “오래 안 쓰면 생긴다”처럼 간헐적으로 보였습니다.

측정 지점 전 후
응답 인터셉터 첫 tools/list 6.1~6.9초 1.42초
요청 인터셉터 콜드 스타트 3초 이상 1.29초
클라이언트가 잰 첫 tools/list (두 인터셉터 모두 콜드) 6.8초 3.4초

인터셉터는 모든 요청 앞에 서므로, 지연 시간 예산을 도구와 따로 잡아야 합니다. 목록 동기화처럼 사용자가 보지 않는 곳에서 끊기면 오류 메시지 없이 도구만 사라져 원인을 찾기 어렵습니다.

사라진 한국어 도구 이름

증상: MCP 서버 타깃의 도구에는 원본 서버가 준 읽기 전용 표시가 보이는데, 직접 만든 Lambda 도구에는 표시 이름도 읽기 전용 표시도 없습니다.

원인: Lambda 타깃의 도구 정의(ToolDefinition)는 name, description, inputSchema, outputSchema만 받습니다. 요청에 title을 넣어도 오류 없이 저장되지만, 저장된 정의에는 남지 않았습니다.

해결: 응답 인터셉터가 tools/list 응답에 표시 이름과 읽기 전용 표시를 붙였습니다.

도구마다 표시 이름과 읽기 전용 여부는 타깃의 규격 파일에 적습니다. 배포할 때 이 값을 응답 인터셉터에 함께 넣고, 인터셉터는 권한 밖 도구를 제거하면서 남은 도구에 값을 붙입니다. 원본이 준 값이 있으면 그것을 우선합니다. 표시 이름 앞에는 시스템 이름을 붙여(예: news_기사 검색), 여러 시스템의 도구가 섞인 목록에서 어느 시스템의 도구인지 바로 알 수 있게 했습니다.

보이지 않는 새 도구

증상: 게이트웨이에 새 도구를 붙인 뒤 Claude Code에서 다시 연결만 하면 도구 목록에 나타나지 않을 때가 있습니다. 게이트웨이의 도구 목록에는 새 도구가 들어 있었습니다.

원인: 클라이언트가 도구 목록을 캐시하는 것으로 보입니다. 게이트웨이의 도구 목록에는 새 도구가 있었고, 재인증 후에는 목록에 나타났습니다.

해결: 연결을 끊고 다시 인증해야 했습니다.

오래 걸리는 도구 호출

앞단 CloudFront의 오리진 응답 타임아웃은 기본 30초이며, 최대 60초까지 설정할 수 있습니다. 그보다 오래 걸리는 도구 호출은 504가 됩니다. 타임아웃은 최대값인 60초로 두었고, 호출 시간은 도구 쪽 장치로 줄입니다. 예를 들어 클라우드 비용 도구는 계정별 조회를 병렬로 실행하고, 조회 기간과 계정 수에 상한을 두고, 결과를 캐시합니다. 그래도 캐시가 없고 외부 API가 느린 경우에는 60초를 넘길 수 있어, 이 상한은 안고 가는 제약으로 남아 있습니다.

7. 외부 MCP 서버를 타깃으로 연결하며 겪은 문제

외부에서 호스팅하는 MCP 서버를 타깃으로 붙일 때는 주로 AgentCore Gateway와 타깃 사이에서 문제가 생겼습니다.

증상 원인과 대응
API 키를 쓰는 타깃 생성이 FAILED 생성 시점의 도구 동기화가 키를 꺼낼 때, 권한 주체가 AgentCore Gateway 실행 role이 아니라 타깃 생성 호출자입니다. 목록 방식을 DYNAMIC으로 두면 생성 때 동기화를 하지 않아 정상 생성됩니다
타깃의 도구가 목록에 안 보임 DYNAMIC 타깃은 tools/list가 타깃마다 한 페이지씩 이어집니다(nextCursor). 첫 페이지만 읽으면 그 타깃의 도구가 없는 것처럼 보입니다. 응답하지 않는 타깃은 그 페이지만 비고 오류는 나지 않습니다

API 키는 처음부터 타깃 URL에 넣지 않고 API 키 자격 증명(헤더 또는 쿼리 파라미터)으로 넘겼습니다. AgentCore Gateway는 받은 URL을 그대로 쓰므로, URL에 넣으면 키가 타깃 설정에 평문으로 남기 때문입니다.

이렇게 붙인 외부 MCP 서버에도 게이트웨이의 도구 권한은 그대로 적용됩니다.

8. 운영: 도구 추가와 감사

새 도구는 Lambda 타깃으로

게이트웨이를 만든 이유는 각 팀이 인증을 다시 만들지 않고 도구 로직만 추가하게 하는 것이었습니다. 타깃은 Lambda와 MCP 서버 둘 다 가능하지만, 새 도구는 Lambda로 만들기로 했습니다.

기준 MCP 서버 타깃 Lambda 타깃
사용자 신원 서버마다 토큰 교환 같은 장치를 새로 만듦 인터셉터가 인자로 넣어 줌
역할별 AWS 권한 서버가 직접 구현 인터셉터가 정한 IAM role을 수임
네트워크 AgentCore Gateway 출구 IP가 고정이 아니라 방화벽 설정이 까다로움 AWS 안에서 IAM으로 호출
프로토콜 버전 지원 범위 밖으로 답하면 호출이 끊김 해당 없음

Lambda의 약점은 만드는 사람의 부담입니다. 그래서 규격과 검사, 스킬로 이 부담을 덜어 주는 것을 이 결정의 조건으로 두었습니다. 코드는 각 팀의 계정이 아니라 게이트웨이 저장소에 PR로 올립니다. 그래야 리뷰에서 신원을 어떻게 쓰는지, 쓰기 도구인지 볼 수 있습니다.

타깃 하나에 폴더 하나

Lambda 타깃 하나는 저장소의 폴더 하나입니다. 외부 MCP 서버 타깃은 원본 서버가 표시 이름을 보내지 않을 때만 폴더를 둡니다. 폴더에서 사람이 직접 쓰는 원본은 규격 파일 하나이고, AgentCore Gateway에 등록할 도구 스키마와 응답 인터셉터가 붙일 표시 정보는 이 파일에서 생성합니다.

규격 파일에 적는 것 비고
타깃 이름, 종류(Lambda 또는 외부 MCP 서버) 이름은 소문자와 숫자만. 밑줄을 넣으면 타깃 생성이 실패합니다
도구별 이름, 한국어 표시 이름, 읽기 전용 여부, 입력 스키마 표시 이름과 읽기 전용 여부는 필수
메모리, 타임아웃, 네트워크 선택
환경 변수와 시크릿의 이름 값은 적지 않습니다. 비밀 값은 AWS Secrets Manager에 둡니다
추가 의존성, 허용할 역할 의존성은 담당자가 승인합니다

PR을 올리면 테스트가 먼저 돌고, 하나라도 실패하면 인프라 변경 계획(plan)까지 가지 않습니다. 검사기는 아래를 봅니다.

  • 규격 파일 형식, 타깃과 도구 이름 규칙

  • 한국어 표시 이름과 읽기 전용 여부가 있는지, 생성물이 규격 파일과 같은지

  • 코드가 읽는 환경 변수가 규격 파일에 선언돼 있는지, import가 허용 범위인지

  • 키처럼 보이는 문자열이 코드에 들어 있는지

  • 도구마다 테스트가 있는지, 신원 인자가 없거나 모르는 도구를 받았을 때 규약대로 답하는지

검사기가 판정하지 못하는 것도 있습니다. 쓰기 도구를 읽기 전용으로 표시하면 클라이언트가 확인 없이 실행할 수 있어서, 이 항목은 사람이 리뷰에서 따로 봅니다.

배포는 CI, 권한은 경계 안에서

  1. 도구를 만든 팀이 draft PR을 올립니다. 담당자가 자동으로 리뷰어가 됩니다

  2. CI가 읽기 전용 role로 인프라 변경 계획을 만들고, 한국어 요약을 PR 댓글로 달아 줍니다. 삭제와 교체는 경고로 표시됩니다

  3. 담당자가 리뷰하고, 시크릿 값 입력과 권한표 반영을 맡습니다

  4. main에 들어가면 CI가 쓰기 role로 배포합니다. 쓰기 role은 GitHub 환경 보호 규칙을 거친 main 배포에서만 쓸 수 있습니다

배포 전에는 가드가 변경 계획을 한 번 더 봅니다. 게이트웨이 자원이 아닌 리소스나 계정 전체 설정을 건드리거나 삭제나 교체가 있으면 배포를 멈추고 사람에게 넘깁니다. 실제로 외부 MCP 타깃의 목록 방식을 바꾸는 변경은 타깃 교체로 잡혀 가드에서 멈췄고, 사람이 확인한 뒤 반영했습니다.

도구 추가를 돕는 Claude Code 스킬

규격과 검사가 늘수록 처음 도구를 추가하는 팀의 부담도 커지므로, 사내 Claude Code 플러그인으로 스킬 두 개를 배포했습니다.

스킬 하는 일
도구 추가 필요한 항목을 묻고 뼈대를 만듭니다. 검사를 돌리고, 사람에게 확인받을 항목을 하나씩 물어본 뒤 draft PR을 엽니다
MCP 서버 옮기기 팀이 이미 운영하던 MCP 서버의 도구 목록을 읽어 Lambda 도구로 옮깁니다. 원래 서버와 도구 정의를 대조해 다른 점을 PR에 남깁니다

두 스킬은 권한표, 인프라, 배포를 건드리지 않고 담당자 할 일로 넘깁니다. 규격은 스킬에 다시 적지 않고 게이트웨이 저장소의 문서를 읽게 해서, 규격이 바뀌어도 스킬을 고칠 일이 적습니다.

감사 로그: 판정 한 줄, 결과 한 줄

AgentCore Gateway 자체 애플리케이션 로그는 요청과 응답 본문(도구 인자와 결과)을 그대로 남기고, 본문을 빼면 시각과 요청 ID 정도만 남아 감사에 쓰기 어려웠습니다. 이에 두 인터셉터가 요청마다 Amazon CloudWatch Logs에 JSON 한 줄을 남깁니다. 요청 인터셉터는 판정을, 응답 인터셉터는 결과를 적고, 두 줄은 사용자와 JSON-RPC 요청 ID로 연결됩니다.

구분 요청 인터셉터 응답 인터셉터
공통 사용자, 역할, 메서드, 요청 ID 사용자, 역할, 메서드, 요청 ID
판정 허용 또는 거부, 사유 목록 판정, 호출 결과
도구 호출(tools/call) 도구 이름, 클라이언트가 보낸 인자, 수임하도록 넘긴 role 성공, 도구 오류, RPC 오류, 거부 중 하나와 오류 문구, 응답 크기
목록(tools/list) 없음 판정 전후 도구 수, 목록에서 뺀 도구

토큰과 조회 결과 본문은 어느 로그에도 남기지 않습니다. 초기 버전의 응답 인터셉터는 디버깅을 위해 이벤트 전체를 출력했고, 그 바람에 시험 데이터의 민감 컬럼 값이 로그에 그대로 남았습니다. 요약 필드만 찍도록 고친 뒤에는 새로 호출한 구간의 로그에서 민감 컬럼 이름을 검색해도 0건이었습니다. 로그 형식에는 버전을 붙여, 필드 이름이나 의미를 바꿀 때는 버전을 올립니다.

감사 대시보드

대시보드는 감사 로그를 모아, 누가 어떤 도구를 얼마나 쓰는지와 어디서 오류와 거부가 났는지 보여 줍니다.

  • 화면: 호출 수, 활성 사용자, 오류율, 거부 수 지표와 타깃별 일별 호출, 도구 Top 10, 사용자별 호출, 최근 오류와 거부를 보여 줍니다

  • 사용자 타임라인: 한 사람을 고르면 요청과 결과를 시간순으로 보여 줍니다

  • 오류율에서는 권한 거부를 뺍니다. 거부는 정책대로 동작한 결과이기 때문입니다

  • 브라우저는 쿼리 이름만 보냅니다. 쿼리 문장은 서버에만 있어 임의 쿼리를 실행할 수 없습니다

대시보드도 같은 Entra 앱으로 로그인합니다. 조회 API는 토큰 서명을 직접 검증하고, 권한표에서 대시보드 열람 권한이 있는 역할만 통과시킵니다. 이 권한은 도구 권한과 따로 관리해, 자기 권한 확인 도구에는 나오지 않습니다. 대시보드를 본 기록도 따로 남기되, 감사 로그와는 섞지 않습니다.

그림 6. 감사 대시보드 “사용 현황” 화면 예시
그림 6. 감사 대시보드 “사용 현황” 화면 예시

마치며

AgentCore Gateway는 여러 시스템을 하나의 MCP 엔드포인트로 통합하고 토큰을 검증합니다. 한국일보는 그 위에 인터셉터 두 개와 권한표 하나로 사람마다 다른 권한을 부여했습니다. 같은 고민을 하는 팀에 전하고 싶은 것은 다섯 가지입니다.

  • 권한 정보는 이미 있는 곳에: 사람과 역할은 Entra ID, 역할과 도구는 JSON 파일 하나에 둡니다

  • 권한 판정은 한 곳으로 통합 관리합니다: 도구 목록, 호출, 도메인 문서, 대시보드가 모두 같은 권한표와 데이터 권한을 따릅니다

  • 인터셉터가 넣는 신원은 항상 덮어씁니다: 클라이언트가 보낸 값을 믿지 않습니다

  • 클라이언트와 어긋난 곳은 앞단과 인터셉터에서 맞춥니다: 토큰 갱신은 프록시가, 도구 표시 정보는 응답 인터셉터가 채웁니다

  • 인터셉터의 지연 시간 예산은 도구와 따로 관리합니다: 모든 요청 앞에 서는 계층이라 작은 지연이 게이트웨이 전체의 장애로 이어질 수 있습니다.

은현수

은현수

한국일보에서 백엔드와 AI 플랫폼 개발을 함께 하며, 안정적인 백엔드 서비스를 개발 및 운영하고 있습니다. AI Agent와 MCP 등을 활용해 AI를 실제 업무에 적용하고, 사내 구성원이 AI 도구로 더 편리하게 일할 수 있는 공용 기반을 만들고 있습니다.

TaeHoon Kyeong

TaeHoon Kyeong

Taehoon Kyeong is a Solutions Architect who helps media and entertainment customers design optimal cloud architectures to achieve their business goals. He is also an active member of a working group exploring how to apply generative AI technologies to the media and entertainment industry. Previously, he worked as an SAP DevOps developer and now contributes to customers' SupplyChain adoption on AWS.

Taekyung Han

Taekyung Han

한태경 솔루션즈 아키텍트는 AWS 클라우드 고객을 대상으로 고객의 비즈니스 성과 달성을 위해 고객과 함께 최적의 아키텍처를 구성하는 역할을 수행하고 있습니다. 백엔드 엔지니어와 DevOps 경험을 기반으로 안전한 클라우드 환경을 구성하는 방법에 대한 기술적인 도움을 드리고 있습니다. As a Solutions Architect, Taekyung Han works with customers to create the optimized architecture to achieve customer's business outcomes. With backend engineer and DevOps experience, I provide technical help on how to configure a secure cloud environment.