AI 에이전트 게이트웨이란?
AI 에이전트 게이트웨이는 AI 에이전트와 에이전트가 호출하는 시스템 사이에 위치하는 오픈 소스 서비스입니다. Anthropic Claude, AWS Bedrock, OpenAI, Gemini를 비롯해 지원되는 MCP 도구 서버와 LLM 제공업체를 위한 인증 및 관찰 기능이 통합된 단일 진입점을 제공합니다.
각 에이전트에 도구 자격 증명과 제공업체 설정을 복사하는 대신, 인증, 비밀 정보, 액세스 정책, 요청 로그를 중앙에서 관리할 수 있습니다. 게이트웨이는 단일 바이너리로 배포되며 내장된 관리 콘솔을 포함합니다.
이 서비스는 세 개의 리스너를 제공합니다.
- 8080 포트의 MCP 플레인: 에이전트의 MCP 요청을 수신하고 허용된 작업을 등록된 도구 서버로 전달합니다.
- 8081 포트의 제어 플레인: REST API와 관리 콘솔을 호스팅합니다.
- 8082 포트의 LLM 플레인: 지원되는 LLM 요청을 프록시하고 사용량 정보를 기록합니다.
PostgreSQL이 필요합니다. Redis 호환 세션 저장소는 선택 사항이며 MCP 플레인을 둘 이상의 복제본으로 실행할 수 있게 해 줍니다. 번들 배포에서는 Valkey를 사용합니다. ClickHouse는 선택 사항이며 추가 분석 기능을 제공합니다.
주요 기능
- 모든 요청에 대한 인증: 게이트웨이가 발급하는 API 키는 테넌트와 역할 범위로 제한됩니다.
- 보호된 커넥터 자격 증명: 자격 증명은 암호화된 비밀 저장소에 저장되며 호출자에게 노출되지 않은 채 외부 MCP 요청에 주입됩니다.
- 에이전트별 도구 정책: 프로필을 통해 에이전트가 사용할 수 있는 도구를 제한할 수 있습니다. 제한은 도구 목록을 제공할 때뿐 아니라
tools/call실행 중에도 적용됩니다. - 프롬프트와 리소스: 게이트웨이는 공유 네임스페이스를 통해 백엔드 프롬프트와 리소스를 전달하고 동일한 프로필 정책을 적용합니다.
- 스킬과 명령: 프로필에는 네이티브 MCP 메커니즘을 통해 노출되는 재사용 가능한 참고 텍스트와 프롬프트 템플릿을 포함할 수 있습니다.
- 다중 제공업체 LLM 프록시: LLM 플레인은 Anthropic, Bedrock, OpenAI, Gemini를 지원하며 토큰 사용량과 예상 비용을 수집합니다.
- 중앙 집중식 관찰 기능: 필요한 저장소가 활성화되면 콘솔에서 액세스 로그, LLM 로그, 세션 타임라인, 분석 대시보드에 액세스할 수 있습니다.
- 외부 요청 보호: 서버 측 요청 위조 위험을 줄이기 위해 내부, 루프백, 링크 로컬 및 기타 프라이빗 대상은 기본적으로 차단됩니다.
사전 요구 사항
가장 빠른 설정 방법은 Docker Compose를 사용하는 것입니다. 시작하기 전에 다음 항목을 설치하거나 확인하세요.
- Docker Compose 플러그인이 포함된 Docker(예: Docker Desktop, Colima 또는 Docker Engine).
- 상태 확인에 사용할
curl과 API 응답 처리에 사용할jq. - 사용 가능한 로컬 포트
8080,8081,8082. - 분석 프로필과 해당 Adminer 서비스를 활성화하는 경우 포트
8090. - 최소 4GB의 여유 Docker 용량. ClickHouse 분석 기능을 추가하는 경우에는 8GB가 필요합니다.
macOS와 Linux를 지원합니다. Windows는 WSL2를 통해 사용할 수 있지만 현재 해당 환경은 테스트되지 않았습니다.
Docker 외부에서 빌드하려면 저장소에 Go 1.27, 콘솔용 Node.js 26, make가 필요합니다. 일부 작업 예제에는 추가로 npx, Python, kind, kubectl 또는 제공업체 API 키가 필요합니다.
게이트웨이 설치 및 시작
1. 저장소 복제
git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway2. 표준 Compose 스택 실행
docker compose -f deploy/docker-compose.yml up --build -dDocker가 필요한 구성 요소를 빌드하거나 다운로드하고 데이터베이스를 초기화해야 하므로 최초 시작에는 시간이 걸릴 수 있습니다.
3. 제어 플레인 대기
until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done이 반복문은 제어 플레인의 상태 확인 엔드포인트가 성공적으로 응답할 때까지 기다립니다.
4. 세 플레인 모두 확인
curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health성공적인 응답이 반환되면 MCP, 제어, LLM 리스너를 모두 사용할 수 있다는 의미입니다.
관리자 액세스 초기화
새로 배포된 환경에는 콘솔 사용자와 API 키가 없습니다. 기본 테넌트와 관리자 API 키를 생성하는 것부터 시작하세요.
docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key이 명령은 API 키를 한 번만 출력합니다. 시작하기 워크플로에서 커넥터를 등록하고 관리 API 작업을 수행하는 데 사용하므로 안전하게 저장하세요.
다음으로 첫 번째 콘솔 사용자를 생성하세요.
docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin이 명령은 한 번만 사용할 수 있는 임시 비밀번호를 출력합니다. http://localhost:8081을 열고 admin으로 로그인한 다음, 메시지가 표시되면 임시 비밀번호를 변경하세요.
일반적으로 프로그램은 API 키로 인증해야 합니다. 긴급 상황에서는 콘솔에서도 API 키를 대체 인증 수단으로 사용할 수 있습니다.
기본 사용법: MCP 서버 추가 및 호출
게이트웨이 용어에서 MCP 도구 서버는 API에서 커넥터이고 콘솔에서는 MCP입니다. 로그인한 후 MCPs → Catalog를 열면 추가할 수 있는 사전 구성 MCP 서버를 확인할 수 있습니다.
일반적인 최초 사용 워크플로는 다음과 같습니다.
- 관리자 API 키를 생성하고 저장합니다.
- MCP 서버를 커넥터로 등록합니다.
- 커넥터에 필요한 자격 증명을 구성합니다.
- 에이전트 프로필을 생성하거나 선택합니다.
- 해당 프로필에서 커넥터의 도구를 사용할 수 있도록 설정합니다.
- 포트
8080의 게이트웨이 MCP 리스너를 통해 허용된 도구를 호출합니다. - 관리 콘솔에서 호출을 확인합니다.
저장소의 examples/01-quickstart에는 실행 가능한 전체 워크스루가 포함되어 있습니다. 이 예제는 스택을 시작하고 세 가지 플레인을 모두 확인한 다음, 관리자 키를 부트스트랩하고 샘플 MCP 서버를 등록한 뒤 해당 서버의 도구 중 하나를 호출합니다. 정확한 커넥터 등록 및 도구 호출 요청은 시작 가이드를 참조하세요.
외부 자격 증명이 필요하지 않은 모든 예제를 실행하려면 다음 명령을 사용하세요.
make examples-smoke에이전트 프로필의 액세스 적용 방식
프로필은 에이전트가 사용할 수 있는 도구, 프롬프트, 리소스, 스킬 및 명령을 정의합니다. 도구 제한은 에이전트가 tools/call을 호출할 때 확인되므로, tools/list에서 도구를 숨기는 것만으로는 유일한 보호 수단이 되지 않습니다.
더 강력한 정책 적용을 위해 API 키를 프로필에 연결하세요. 연결이 없으면 호출자는 X-Agent-Profile-Name 헤더를 통해 원하는 프로필을 지정할 수 있습니다. 키와 프로필의 연결은 호출자가 다른 프로필을 자유롭게 선택하지 못하도록 합니다.
여러 MCP 서버가 프롬프트나 리소스를 제공하는 경우 게이트웨이는 이를 공통 네임스페이스에서 관리합니다. 프롬프트에는 커넥터 이름이 포함되고, 리소스에는 게이트웨이가 관리하는 URI가 사용됩니다. 동일한 프로필 규칙에 따라 에이전트가 액세스할 수 있는 항목이 결정됩니다.
LLM 프록시 사용
LLM 플레인은 Anthropic, AWS Bedrock, OpenAI 및 Gemini와 같은 지원되는 모델 제공업체로 연결되는 중앙 집중식 경로를 제공합니다. 이를 통해 에이전트 애플리케이션은 도구에 사용되는 동일한 제어된 인터페이스를 통해 모델 트래픽을 전송할 수 있습니다.
각 프록시 호출에 대해 게이트웨이는 토큰 사용량을 수집하고 비용을 추정할 수 있습니다. 제공업체 설정, 자체 키 사용 구성, Bedrock 자격 증명 모드, 라우트, 수집 설정 및 비용 동작은 LLM 플레인 가이드에 설명되어 있습니다.
클라이언트를 구성하기 전에 상태 엔드포인트를 사용하여 리스너를 확인하세요.
curl localhost:8082/health분석 기능 활성화
표준 배포는 ClickHouse 없이도 LLM 로그를 지원합니다. 개요 대시보드, 액세스 로그, 세션 타임라인 및 ClickHouse 기반 분석 기능을 추가하려면 analytics 프로필로 Compose를 시작하세요.
GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d이 구성에는 더 많은 로컬 리소스가 필요하며 포트 8090을 사용할 수 있습니다.
민감한 요청 본문 보호
데모 스택은 LLM 요청 및 응답 본문을 PostgreSQL에 저장하며, 각 본문의 크기는 1MiB로 제한됩니다. analytics 프로필을 사용하면 콘솔에 표시할 수 있도록 LLM 및 MCP 요청과 응답 본문도 ClickHouse에 저장합니다. 이러한 본문은 컨테이너 로그에 출력되지 않습니다.
프롬프트, 모델 응답 또는 도구 페이로드에 민감한 정보가 포함될 수 있다면 본문 저장을 완전히 비활성화하세요.
GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d프로덕션 데이터로 수집 기능을 사용하기 전에 관측성 문서를 검토하세요.
로컬 또는 비공개 MCP 서버에 안전하게 연결
게이트웨이는 기본적으로 루프백, 비공개, 링크 로컬 및 기타 내부 대상에 대한 연결을 차단합니다. 또한 클라우드 메타데이터 주소 169.254.169.254를 영구적으로 차단합니다. 이 정책은 커넥터, 카탈로그 항목 또는 모델 대상이 호스트나 네트워크의 민감한 서비스에 몰래 연결하는 것을 방지합니다.
호스트 이름이 생성 시점에 차단된 주소로만 확인되면 게이트웨이는 400 egress_blocked 오류와 함께 요청을 거부합니다. 아직 확인되지 않는 호스트 이름은 허용될 수 있지만, 게이트웨이가 연결을 시도할 때 다시 확인됩니다.
바이너리를 직접 실행하는 경우
make run으로 실행할 때 동일한 컴퓨터에서 MCP 서버가 실행 중이라면 루프백을 명시적으로 허용하세요.
GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run제공된 Compose 스택 사용
포함된 Compose 구성에는 이미 host.docker.internal 및 루프백 CIDR이 허용되어 있습니다. 따라서 노트북에서 실행 중인 서버는 host.docker.internal을 통해 지정할 수 있습니다. 필요한 경우가 아니라면 공유 환경에서는 이러한 허용 설정을 제거하세요.
Kubernetes 또는 비공개 네트워크 사용
클러스터 내부 Kubernetes 서비스의 경우 호출할 DNS 이름만 허용하세요. 예를 들면 다음과 같습니다.
GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc대신 관련 파드 또는 서비스 CIDR을 허용할 수도 있습니다. VPN 전용 또는 비공개 네트워크 서버의 경우 모든 비공개 주소 범위를 활성화하는 대신 특정 호스트 이름이나 좁은 CIDR을 추가하세요.
아웃바운드 허용 목록은 가능한 한 좁게 유지하세요. 초기 테스트를 쉽게 하려고 보호 기능을 비활성화하지 마세요.
고급 운영 팁
- 사람과 프로그램의 액세스를 분리하세요: 관리자는 콘솔 계정을 사용하고, 에이전트와 자동화에는 게이트웨이에서 발급한 API 키를 사용하세요.
- 키를 프로필에 연결하세요: 호출자가 요청 헤더로 프로필을 선택하도록 하는 것보다 프로필에 연결된 키가 더 강력한 보장을 제공합니다.
- 자격 증명을 게이트웨이에 보관하세요: 커넥터 자격 증명을 중앙에서 구성하여 에이전트가 기본 비밀 정보를 받지 않도록 하세요.
- 커넥터 자격 증명을 교체하세요: 각 에이전트를 개별적으로 업데이트하는 대신 커넥터 및 자격 증명 관리 기능을 사용하세요.
- 데이터 캡처를 제어하세요: 기밀 프롬프트나 도구 결과를 처리하기 전에 요청 및 응답 본문을 보존할지 결정하세요.
- 여러 복제본에 대비하세요: MCP 플레인을 하나의 복제본보다 확장할 때는 선택적 Redis 프로토콜 세션 저장소를 구성하세요.
- 좁은 송신 규칙을 사용하세요: 광범위한 사설 범위 대신 개별 호스트 또는 CIDR을 허용하세요.
- 작성된 예제를 참고하세요: 각 예제는 추가 시나리오를 다루며, 필요한 도구나 공급업체 키를 각 예제의 README 파일에 명시합니다.
- 변경을 예상하세요: 이 프로젝트는 1.0 이전의 알파 소프트웨어이므로 마이너 버전 간에 API와 구성이 변경될 수 있습니다.
Docker 외부에서 빌드하기
로컬 개발을 위해 Go 1.27, Node.js 26, make를 설치하세요. 저장소는 make build 및 make run 워크플로를 제공합니다. 선택적 개발 및 릴리스 도구로는 golangci-lint, govulncheck, goreleaser가 있습니다.
개발 규칙, 테스트 명령, 풀 리퀘스트 지침, 스토어·싱크·프로바이더의 확장 지점은 기여 가이드를 참고하세요.
결론
AI Agent Gateway는 인증된 엔드포인트를 통해 MCP 도구와 여러 LLM 프로바이더에 대한 액세스를 중앙화합니다. 프로필 적용, 자격 증명 주입, 아웃바운드 네트워크 제어, 관측성 기능을 통해 개별 에이전트 구성에 정책과 비밀 정보가 포함되지 않도록 지원합니다.
Docker Compose 빠른 시작으로 시작하고, 생성된 관리자 키를 저장한 다음, 콘솔 사용자를 생성하고 첫 번째 커넥터 워크플로를 완료하세요. 그런 다음 프로필에 연결된 API 키를 추가하고, 프로바이더 액세스를 구성하며, 적절한 본문 캡처 정책을 선택하고, 추가적인 가시성이 필요할 때만 ClickHouse 분석을 활성화하세요.