MCP - AWS SigV4 인증

MCP - AWS SigV4 인증 (Auth)

AWS SigV4 인증을 사용해 LiteLLM을 AWS Bedrock AgentCore에 호스팅된 MCP 서버에 연결해요.

왜 SigV4인가? (Why SigV4?)

AWS 서비스는 요청 본문을 암호화 서명에 포함하는 요청별 서명 프로토콜인 Signature Version 4로 요청을 인증해요. 이는 매 요청마다 같은 헤더를 보내는 정적 헤더 인증 타입(api_key, bearer_token 등)과는 다르게 작동해요.

LiteLLM의 aws_sigv4 인증 타입이 이를 자동 처리해요. 모든 아웃바운드 MCP 요청이 AWS 자격 증명으로 보내지기 전에 서명돼요.

출처: 문서

본문

빠른 시작 (Quick Start)

LiteLLM UI:

1. MCP Servers로 이동해 Add New MCP Server 클릭
2. 전송을 Streamable HTTP로 설정
3. 인증 타입으로 AWS SigV4 선택
4. AWS 자격 증명 입력:

필드	필수	설명
AWS Region	예	SigV4 서명용 AWS 리전(예: us-east-1)
AWS Service Name	아니오	기본값 bedrock-agentcore
AWS Access Key ID	아니오	비워두면 boto3 자격 증명 체인으로 폴백
AWS Secret Access Key	아니오	Access Key ID를 제공하면 필수
AWS Session Token	아니오	임시 STS 자격 증명에만 필요
AWS Role ARN	아니오	STS AssumeRole용 IAM 역할 ARN(예: arn:aws:iam::123456789012:role/MyRole). 설정하면 LiteLLM이 서명 전에 이 역할을 가정함
AWS Session Name	아니오	AssumeRole 호출용 세션 이름 — CloudTrail에 표시됨. 생략 시 자동 생성

생성되면 LiteLLM이 모든 아웃바운드 MCP 요청을 SigV4로 서명해요. 서버의 도구가 MCP Tools 목록에 자동으로 나타나요.

자격 증명 편집: 기존 SigV4 서버를 편집할 때는 자격 증명 필드를 비워 두어 현재 값을 유지하세요. 채운 필드만 업데이트돼요.

1. AWS 자격 증명 설정

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION_NAME="us-east-1"

2. AgentCore MCP 서버를 config.yaml에 추가

config.yaml:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: os.environ/AWS_ROLE_ARN          # IAM role to assume (recommended)
    aws_session_name: "litellm-prod"                 # optional — for CloudTrail auditing
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

URL 인코딩 (URL encoding):

AgentCore 런타임 ARN은 url 필드에서 URL 인코딩되어야 해요. 예를 들어:

arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-mcp-server

이렇게 됩니다:

arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aruntime%2Fmy-mcp-server

3. 프록시 시작

litellm --config config.yaml

MCP 도구 사용 (Use the MCP tools)

구성되면 AgentCore MCP 도구가 다른 MCP 서버처럼 LiteLLM을 통해 사용 가능해요:

사용 가능한 도구 목록:

curl http://localhost:4000/mcp-rest/tools/list \
  -H "Authorization: Bearer ***"

도구 호출:

curl http://localhost:4000/mcp-rest/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "server_id": "my_agentcore_mcp",
    "name": "my_agentcore_mcp-your_tool_name",
    "arguments": {"key": "value"}
  }'

도구 명명, server_id 형식, 일반적인 실수는 MCP REST API를 참고해 주세요.

구성 참조 (Config Reference)

필드	필수	설명
url	예	AgentCore MCP 서버 URL(URL 인코딩된 ARN 포함)
transport	예	"http"여야 함
auth_type	예	"aws_sigv4"여야 함
aws_access_key_id	아니오	AWS 액세스 키. os.environ/VAR_NAME 지원. 생략 시 boto3 자격 증명 체인으로 폴백
aws_secret_access_key	아니오	AWS 시크릿 키. os.environ/VAR_NAME 지원. 생략 시 boto3 자격 증명 체인으로 폴백
aws_region_name	예	AWS 리전(예: us-east-1)
aws_service_name	아니오	서명용 AWS 서비스 이름. 기본값 bedrock-agentcore
aws_session_token	아니오	임시 자격 증명용 AWS 세션 토큰. os.environ/VAR_NAME 지원
aws_role_name	아니오	STS AssumeRole용 IAM 역할 ARN. os.environ/VAR_NAME 지원. 설정하면 LiteLLM이 서명 전에 sts:AssumeRole을 호출해 임시 자격 증명을 얻음
aws_session_name	아니오	AssumeRole 호출용 세션 이름(CloudTrail에 표시). 생략 시 자동 생성. os.environ/VAR_NAME 지원

동작 방식 (How It Works)

LiteLLM은 HTTP 요청 라이프사이클에 연결되는 httpx.Auth 서브클래스(MCPSigV4Auth)를 사용해요:

1. 모든 아웃바운드 MCP 요청에 대해 인증 핸들러가 요청 본문의 SHA-256 해시를 계산
2. AWS 자격 증명, 요청 URL, 헤더, 본문 해시로 SigV4 서명 생성
3. 서명된 Authorization과 x-amz-date 헤더를 요청에 추가
4. AWS가 서명을 검증하고 MCP 요청 처리

이 작업은 수동 토큰 관리 없이 자동으로 발생해요.

임시 자격 증명(STS) 사용 (Using Temporary Credentials (STS))

AWS STS 임시 자격 증명(예: IAM 역할 또는 SSO)을 사용한다면 세션 토큰을 포함하세요:

STS 자격 증명을 가진 config.yaml:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
    aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
    aws_session_token: os.environ/AWS_SESSION_TOKEN
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

IAM 역할 가정(AssumeRole) 사용 (Using IAM Role Assumption (AssumeRole))

LiteLLM 인스턴스가 IAM 역할(예: EKS 팟 역할, EC2 인스턴스 프로파일)로 인증하는 프로덕션 환경을 위해 aws_role_name을 구성하면 LiteLLM이 MCP 요청을 서명하기 전에 sts:AssumeRole을 호출해요:

AssumeRole을 가진 config.yaml:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: "arn:aws:iam::123456789012:role/BedrockAgentCoreRole"
    aws_session_name: "litellm-prod"    # optional
    aws_region_name: "us-east-1"
    aws_service_name: "bedrock-agentcore"

LiteLLM은 환경 자격 증명(팟 역할, 인스턴스 프로파일, 환경 변수)으로 sts:AssumeRole을 호출한 다음 가정한 역할의 임시 자격 증명으로 MCP 요청을 서명해요.

aws_role_name을 명시적 액세스 키와 결합할 수도 있어요. 키는 AssumeRole 호출의 소스 신원으로 사용돼요:

AssumeRole + 명시적 소스 키를 가진 config.yaml:

mcp_servers:
  my_agentcore_mcp:
    url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/<url-encoded-ARN>/invocations"
    transport: "http"
    auth_type: "aws_sigv4"
    aws_role_name: os.environ/AWS_ROLE_ARN
    aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
    aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
    aws_region_name: "us-east-1"

tip — 대부분의 Kubernetes 배포에는 aws_role_name과 aws_region_name만 필요해요. 팟의 IAM 역할이 소스 자격 증명을 자동 제공하니까요.

문제 해결 (Troubleshooting)

AWS의 403 Forbidden

• AWS 자격 증명이 유효하고 만료되지 않았는지 확인
• aws_region_name이 AgentCore URL의 리전과 일치하는지 확인
• aws_service_name이 bedrock-agentcore로 설정되어 있는지 확인
• STS 자격 증명을 사용한다면 aws_session_token이 설정되고 만료되지 않았는지 확인

AssumeRole AccessDenied

aws_role_name 사용 시 AccessDenied를 받으면:

• 역할 ARN이 올바른지 확인
• 대상 역할의 신뢰 정책이 소스 신원이 그것을 가정하도록 허용하는지 확인
• EKS에서 실행 중이라면 팟의 서비스 계정이 올바른 IAM 역할로 어노테이트되었는지 확인
• 실패한 sts:AssumeRole 호출에 대해 CloudTrail을 확인해 정확한 오류를 봅니다

시작 시 상태 확인 오류

SigV4 인증 MCP 서버는 프록시 시작 시 표준 상태 확인을 건너뛰어요. 정상이며, 프록시는 도구가 호출될 때 요청을 여전히 올바르게 서명해요.

"botocore not found" 오류

botocore 패키지 설치:

uv add botocore

botocore는 SigV4 자격 증명 처리에 사용되며 aws_sigv4 인증을 사용할 때 필요해요.

더 알아보기 (Learn more)

• MCP 개요 — LiteLLM의 MCP 알아보기
• MCP REST API — 도구 명명·호출