콘텐츠로 이동
Study Notekagent · kmcp

개요

다른 이름: kagent · kmcp · MCPServer · RemoteMCPServer · AgentHarness · Hermes · trusted-proxy · allowedHeaders · token propagation · GitOps Agent 배포 · kagent init · kmcp init · 로컬 개발

결론부터
  • kagent는 Agent 리소스를 선언하면 Deployment와 호출 주소를 만들어 주는 Kubernetes controller이고, kmcp는 같은 방식으로 MCP 서버를 띄우는 하위 프로젝트다.
  • 리소스가 전부 Kubernetes manifest라 GitOps PR 승인 배포와 잘 맞는다. 다만 승인·권한·secret 관리는 kagent가 아니라 우리 쪽 책임이다.
  • 임직원 토큰은 allowedHeaders 설정으로 MCP 호출까지 전달된다. 조건은 MCP 서버가 http 전송이고 backend가 그 토큰을 직접 검증하는 것이다.
  • Hermes는 일반 Agent가 아니라 AgentHarness로 올린다. Agent Substrate 설치가 선행 조건이다.

사내 Agent 배포 플랫폼 덱은 kagent를 온프렘 실행 어댑터의 후보로만 다뤘다. 그 덱의 관심은 회사가 소유할 계약이었고, kagent 자체가 무엇을 만들어 주는지는 필요한 만큼만 짚었다. 이 덱은 반대로 kagent와 kmcp 제품 자체를 0.x 공식 문서 기준으로 정리한다.

정리하는 이유는 이 덱이 가정하는 다음 세 가지 구성을 판단하려면 제품의 실제 동작을 알아야 하기 때문이다.

  1. 배포: 우리 backend가 GitOps 저장소의 workflow를 트리거해 manifest PR을 만들고, PR이 merge되면 승인된 것으로 보는 방식.
  2. 인증 전파: 임직원이 oauth2-proxy를 거쳐 Keycloak으로 로그인한 뒤, 그 신원이 kagent와 MCP 서버를 지나 우리 backend API 호출까지 이어지는 방식.
  3. Hermes: Hermes 같은 외부 coding agent를 kagent 위에서 실행하는 방식.

2026년 10월 2일 기준 kagent v0.10.2, kmcp v0.4.0 문서와 소스를 확인했다. API가 alpha(v1alpha2)라 빠르게 바뀐다. 공식 문서에 없고 소스에서만 확인한 동작은 본문에 “소스에서 확인”이라고 표시했고, 이 덱이 가정한 설계에 해당하는 흐름과 manifest는 실제 클러스터에서 검증하지 않은 설명용이다.

큰 그림부터 읽기

구성

섹션 제목: “구성”
  1. 큰 그림kagent와 kmcp가 맡는 자리

    controller · Agent Pod · UI · kmcp controller · PostgreSQL과 CRD 여섯 개

    무엇을 선언하면 무엇이 만들어지고, 요청은 어느 문으로 들어오는가

  2. 주요 개념Agent · ModelConfig · Tool · kmcp

    Declarative와 BYO · 모델 연결 · MCP 서버 세 종류와 toolNames · MCPServer의 stdio와 http · 세 실행 형태

    Agent 하나를 띄우려면 어떤 리소스가 서로를 참조하는가

  3. 로컬 개발MCP 서버와 BYO Agent를 PC에서 만들기

    kmcp project와 http 전송 시험 · kagent run의 docker-compose 구성 · 로컬에서 재현되지 않는 controller 구간

    클러스터에 올리기 전에 무엇을 어디까지 확인할 수 있는가

  4. 실사용 배포설치 구성과 GitOps PR 승인 배포

    Helm chart 두 개와 운영 values · backend가 workflow를 트리거해 manifest PR을 만들고 merge를 승인으로 보는 흐름

    demo 설치에서 무엇을 바꿔야 하고, Git이 원본일 때 누가 무엇을 쓰는가

  5. 임직원 인증 전파oauth2-proxy에서 MCP·backend까지

    trusted-proxy 모드가 믿는 것 · allowedHeaders로 토큰을 MCP 호출에 싣기 · http 전송 조건 · backend의 JWT 검증

    Keycloak으로 로그인한 임직원의 신원이 어느 구간에서 끊기고, 어떻게 잇는가

  6. HermesAgentHarness로 Hermes 실행

    Agent Substrate 전제 · backend: hermes · ACP 연결 · Slack 채널 · 임직원 토큰 전파와의 관계

    Hermes를 올리려면 무엇이 더 필요하고, 일반 Agent와 무엇이 다른가

다른 덱과의 관계

섹션 제목: “다른 덱과의 관계”
덱다루는 것이 덱과의 차이
사내 Agent 배포 플랫폼회사가 소유할 Agent·권한·배포 계약과 runtime adapterkagent를 교체 가능한 후보로 본다. v0.9.9 기준
kagent 실습kind 클러스터에서 설치·호출·권한 우회 차단을 직접 실행명령과 관찰 중심. v0.9.9 기준
kagent · kmcp (이 덱)제품 개념, 실사용 배포 구성, 인증 전파, Hermes공식 문서 정리와 우리 방식의 대응. v0.10.2 기준

세 덱의 기준 버전이 다르다. 예를 들어 Declarative Agent의 기본 runtime은 v0.10에서 Python에서 Go로 바뀌었다(release notes). 값이 서로 다르면 버전 차이인지 먼저 확인한다.

kagent와 kmcp가 맡는 자리구성 요소와 CRD, 선언과 호출 두 경로를 한 장으로 본다.