사람이 아닌 에이전트를 위한 CLI 설계

URL: https://www.youtube.com/watch?v=3wj6sgbi1YA 날짜: 2026-10-10 채널: aiDotEngineer

📌 핵심 질문 / 이 영상이 다루는 핵심 논점

==AI 에이전트가 안정적으로 발견하고 호출하고 조합할 수 있는 CLI는 사람용 CLI와 어떤 점이 달라야 하며, MCP와 어떤 역할 분담을 해야 하는가?==

• 에이전트용 CLI는 복잡한 플래그보다 JSON 입력·출력, 명사-동사 구조, 비대화형 인증을 우선해야 한다.
• CLI가 설치되어 있어도 에이전트가 존재와 사용법을 모르면 호출할 수 없으므로 스킬(skill)을 함께 배포해야 한다.
• MCP는 비기술 사용자의 빠른 연결과 일회성 작업에 강하고, CLI는 기술 사용자의 장시간 작업·긴 출력·Unix 파이프 조합에 강하다.

Airbyte는 데이터 이동 도구에서 AI 에이전트의 데이터 및 액션 레이어로 확장하면서, 같은 플랫폼을 얇게 감싸는 MCP와 CLI를 구축했다. 핵심은 표면 인터페이스를 플랫폼의 재구현으로 만들지 않고 공통 API 위에 두며, 에이전트가 추측하거나 대화형 입력에서 멈추지 않도록 계약과 인증 경험을 설계하는 데 있다.

1. Airbyte가 에이전트의 데이터·액션 레이어가 된 배경

Airbyte의 MCP와 CLI는 독립적인 제품이 아니라 여러 SaaS의 데이터를 에이전트가 검색하고 실제 시스템에 쓰거나 행동하게 만드는 공통 플랫폼의 인터페이스다.

1.1. 데이터 이동 표준에서 Context Store로

1. Airbyte의 출발점

   1. 오픈 소스 데이터 이동 표준: Airbyte는 데이터 이동을 위한 오픈 소스 표준으로 시작했다.
   2. SaaS와 분석 파이프라인 연결: Zendesk, Stripe, GitHub 같은 SaaS 도구를 데이터 분석 파이프라인에 연결해 왔다.

2. AI 에이전트를 위한 확장

   1. 데이터 및 액션 레이어: 기존 데이터 연결 전문성을 바탕으로 AI 에이전트가 데이터를 조회하고 시스템에서 행동할 수 있는 레이어로 진화했다.
   2. Context Store: Airbyte Agent 제품은 여러 도구에 연결된 Context Store를 제공하며, 에이전트 사이에 위치해 전체 데이터를 검색 최적화 인덱스로 제공한다.
   3. 교차 시스템 결합: 여러 도구에 흩어진 레코드와 연락처를 모아 결합하므로 에이전트가 각 SaaS를 따로 뒤지는 대신 더 효율적으로 질의할 수 있다.

1.2. 데이터 접근 인터페이스와 세 가지 공통 역량

1. 세 가지 접근 방식

   1. SDK: 자체 에이전트와 도구를 개발하는 팀이 Context Store를 코드로 사용할 수 있다.
   2. Web UI: 웹 앱에서 빠르게 Context Store를 사용하는 인터페이스다.
   3. MCP와 CLI: ChatGPT와 Claude 같은 기존 에이전트 안에서 Airbyte 데이터를 쉽게 활용하게 하는 인터페이스다.

2. 모든 인터페이스가 노출해야 하는 기능

   1. 핵심 리소스 관리: 조직(organization), 워크스페이스(workspace), 커넥터(connector)를 생성·조회·관리한다.
   2. 타사 서비스 인증: 연결된 외부 서비스에 안전하게 인증하되 AI 에이전트에 자격 증명을 직접 노출하지 않는다.
   3. Ask and Act: Context Store 전체를 검색하고 데이터를 읽고 쓰며 연결된 시스템에서 작업을 수행한다.

1.3. 얇은 통합 인터페이스와 API의 단일 기준점

1. 플랫폼 재구현을 피하는 구조

   1. Thin unified interface: MCP와 CLI는 플랫폼을 다시 구현하지 않고 플랫폼으로 들어가는 얇고 통합된 인터페이스다.
   2. 표면 레이어의 역할: 사용자의 명령을 받아 플랫폼을 호출하고 결과를 적절히 포맷팅하는 프레젠테이션 계층에 가깝다.
   3. 공유 플랫폼과 API: 실제 기능은 공통 플랫폼과 API 위에서 동작하므로 MCP와 CLI 사이의 동작 기준을 공유한다.

2. 잦은 배포에 대응하는 기준점

   1. 하루 10회 초과의 플랫폼 변경: Airbyte 플랫폼은 하루에도 10번 넘게 바뀔 수 있어 인터페이스가 빠르게 최신 상태를 따라가야 한다.
   2. OpenAPI 사양: API 연결 방식의 source of truth로 OpenAPI specification을 사용하고, 여러 인터페이스를 그 사양 위에 구축한다.

2. MCP: 비기술 사용자를 위한 빠른 연결 계층

MCP(Model Context Protocol)는 설치와 연결이 간단하고 기존 AI 앱 안에서 데이터를 바로 쓰게 해 비기술 사용자에게 적합하지만, 클라이언트별 지원 차이를 고려해야 한다.

2.1. 설치 경험과 교차 시스템 질의

1. 낮은 진입 장벽

   1. 주요 대상: 데이터를 ChatGPT나 Claude에 직접 연결하고 싶은 비기술 사용자에게 유용하다.
   2. 패키징과 설치: ChatGPT 공식 스토어에 Airbyte 앱 리스팅을 제공하고, Anthropic에도 앱을 신청해 승인 대기 중이다.
   3. 마켓플레이스 밖의 설치: 스토어에 등록되지 않아도 호스팅된 MCP URL을 입력하면 최종 사용자가 빠르게 연결할 수 있다.

2. Zendesk와 Stripe를 결합하는 예시

   1. 커넥터 탐색: 사용 가능한 커넥터를 묻자 해당 워크스페이스에 설정된 커넥터 4개를 반환한다.
   2. 자연어 요청: “Zendesk 지원 티켓이 있는 유료 고객 5명을 보여 달라”고 요청한다.
   3. Context Store 검색: MCP가 연결된 모든 커넥터를 살펴보고 Context Store에서 요청에 맞는 정보를 검색한다.
   4. 교차 검증 결과: Zendesk와 Stripe 데이터를 결합·교차 검증해 열린 지원 티켓을 가진 유료 고객 5명을 반환한다.

2.2. MCP 도구 수를 줄이고 점진적으로 발견하기

1. 두 개의 핵심 실행 도구

   1. describe: 커넥터를 설명하고 해당 데이터를 질의하는 스키마를 얻는다.
   2. execute: 레코드를 읽고(read), 쓰고(write), 삭제(delete)한다.

2. 도구를 커넥터별로 쪼개지 않은 이유

   1. 가능했던 대안: 수많은 커넥터마다 서로 다른 엔티티와 작업이 있으므로 각각에 MCP 도구를 하나씩 노출할 수도 있었다.
   2. 좁은 표면: 도구 수를 좁게 유지하면 서버가 다뤄야 할 표면이 작아지고, 도구 설명에 주입되는 컨텍스트 양도 제한된다.
   3. Progressive discovery: 커넥터가 제공하는 기능을 필요할 때 점진적으로 탐색하는 방식이 MCP 서버 성능에 더 유리했다.

2.3. MCP 인증은 OAuth와 장기 오프라인 세션을 중심으로

1. OAuth가 사실상 기본 경로인 이유

   1. 연결 흐름: Anthropic에서 연결 버튼을 누르면 OAuth 흐름이 시작되고, 사용자가 Airbyte에 로그인해 권한을 승인하면 연결된 커넥터 설정이 완료된다.
   2. Bearer 인증의 불리함: MCP 사양이 OAuth에 크게 의존하고 주요 클라이언트가 설치 UX로 OAuth를 선호하므로 Bearer 토큰 같은 방식을 택하면 구현과 사용성이 어려워진다.
   3. 클라이언트 제약: Anthropic custom connector 등록 화면에는 Bearer 토큰을 입력할 방법이 없고 OAuth가 기본으로 설정되어 있다.

2. 모바일 앱 같은 세션 경험

   1. 사용자 기대: 사용자는 웹 앱처럼 한두 번마다 재로그인하기보다 MCP를 모바일 앱처럼 인증을 거의 의식하지 않고 언제든 쓰기를 기대한다.
   2. 오프라인 장기 세션: 웹 앱 세션과 분리된 장기 offline session을 저장하고 MCP 고유의 수명 주기(lifecycle)를 운영해야 한다.

2.4. Elicitation보다 직접 연결 흐름이 필요한 경우

1. 안전한 외부 도구 연결

   1. HubSpot 사례: HubSpot 연결을 요청하면 Airbyte가 링크를 만들고, 링크를 연 뒤 표시되는 위젯에서 연결할 엔티티를 선택하고 HubSpot으로 리디렉션해 OAuth를 진행한다.
   2. 자격 증명 보호: API 자격 증명을 에이전트에 직접 넘기지 않고 사용자가 안전한 OAuth 흐름을 완료하게 한다.

2. URL mode Elicitation의 한계

   1. MCP 기능: Elicitation은 사용자에게 정보를 요청하고 URL을 표시한 뒤 입력을 처리할 수 있는 사양 기능이다.
   2. 민감 정보와 Form mode: 오랫동안 제공된 Form mode Elicitation은 API 자격 증명처럼 민감한 데이터에 적합하지 않았다.
   3. 최근의 URL mode: URL mode Elicitation은 Airbyte가 구현한 링크 기반 흐름과 유사한 기능으로 추가됐다.
   4. 클라이언트 간 불일치: MCP 사양이 있어도 기능 지원 범위가 클라이언트마다 크게 다르다. Claude Desktop은 URL mode Elicitation을 지원하지 않는다고 알려 주므로 Airbyte는 사양 기능을 쓰지 않고 자체 연결 방식을 다시 사용해야 했다.

3. CLI: 에이전트를 호출자로 간주하는 설계

CLI(Command-Line Interface)는 MCP의 기술 사용자용 대응 계층으로, 에이전트가 스킬을 로드하고 명령을 직접 호출해 긴 작업과 Unix 도구 조합까지 수행하게 한다.

3.1. MCP와 같은 질의를 CLI로 수행하기

1. 동일한 업무 흐름

   1. 스킬 로드: 에이전트가 CLI의 존재와 사용법을 알려 주는 skill을 먼저 로드한다.
   2. 커넥터 조회: CLI로 사용 가능한 커넥터를 질의해 워크스페이스의 커넥터 목록을 받는다.
   3. 고객 질의: “Zendesk 지원 티켓이 있는 유료 고객 5명”을 요청한다.
   4. 집계와 반환: CLI가 Context Store를 질의하고 데이터를 집계한 뒤 MCP 예시와 같은 5명의 사용자를 반환한다.

2. 설계 관점의 전환

   1. 사람에게 편한 기능의 위험: 사람에게 유용한 프롬프트나 플래그가 에이전트에게는 중단 지점과 방해 요소가 될 수 있다.
   2. 에이전트를 첫 호출자로 가정: CLI가 사람이 터미널에서 대화하는 도구라는 전제를 버리고, 발견·구성·호출·파싱을 에이전트가 수행한다고 보고 계약을 설계해야 한다.

3.2. JSON in, JSON out

1. 입력 계약

   1. 사람용 플래그의 한계: 사람은 여러 플래그를 지정하는 방식에 익숙하지만, 복잡한 질의 입력을 플래그 조합으로 만들면 에이전트가 추측해야 할 부분이 늘어난다.
   2. JSON 구성의 장점: 에이전트는 복잡한 질의 구조를 JSON으로 더 직접적이고 덜 추측적인 방식으로 구성할 수 있다.

2. 출력 계약과 Unix 조합

   1. 긴 응답 처리: JSON은 긴 결과를 구조적으로 다루기 쉽다.
   2. 파이프 연결: CLI의 핵심 강점인 Unix system pipe를 사용해 출력을 다른 프로그램으로 리디렉션할 수 있다.
   3. jq 활용: jq로 결과에서 특정 항목을 선택하고 불필요한 부분을 다듬을 수 있어 JSON이 CLI 조합 능력을 크게 확장한다.

3.3. 명사-동사 구조와 실패를 계약으로 바꾸기

1. 모든 리소스에 일관된 명령 구조 적용

   1. noun then verb: connectors list, connectors create처럼 명사 뒤에 동사를 두는 규칙을 사용한다.
   2. 리소스 간 일관성: workspace 명령도 workspace list처럼 같은 형식을 따라야 에이전트가 새로운 리소스에서도 사용법을 추측하지 않는다.
   3. 문서 의존성 축소: 에이전트가 방대한 문서를 읽지 않아도 올바른 명령을 즉시 알 수 있도록 계약을 명확히 만든다.

2. 반복되는 실수를 API 신호로 해석하기

   1. 관찰할 현상: 에이전트가 같은 잘못된 명령을 계속 호출하면 단순히 에이전트를 탓할 일이 아니다.
   2. 계약 수정: 반복 실수를 계약(contract)으로 삼아 올바른 사용법을 에이전트가 쉽게 발견하도록 명령 표면을 바꾼다.
   3. 진단 원칙: 같은 실수가 반복된다는 것은 CLI contract가 충분히 명확하지 않다는 뜻일 가능성이 높다.

3.4. CLI와 함께 배포해야 하는 Skill

1. 발견 가능성 확보

   1. 설치만으로는 부족함: CLI가 설치되어 있어도 에이전트가 그 CLI가 존재한다는 사실을 자동으로 알 수는 없다.
   2. Skill의 역할: skill은 사용 가능한 도구를 발견하게 하고 효과적인 호출법을 알려 준다.
   3. 상황 기반 노출: 커넥터에 관해 질문이 들어오면 관련 설명이 나타나고, 에이전트가 해당 CLI를 불러 호출할 수 있다.

2. 컨텍스트 비용을 관리하는 구조

   1. 메인 스킬 최소화: 모든 명령 설명을 한 번에 넣으면 컨텍스트가 무거워지므로 핵심 지침만 메인 skill에 둔다.
   2. 참조 파일 분리: skill 디렉터리의 다른 reference 파일을 메인 skill이 가리키게 해 명령별 정보를 필요할 때 확장한다.
   3. 점진적 탐색: 이 구조는 매 호출마다 로드되는 컨텍스트 양을 줄이고 에이전트의 progressive discovery를 활용한다.

3.5. CLI 인증과 비대화형 실행

1. 사람의 프롬프트를 전제하지 않기
   1. 중단 문제: 에이전트가 CLI를 호출했을 때 사용자가 입력할 때까지 프롬프트에서 기다리면 에이전트가 그 단계에서 멈춘다.
   2. 사전 설정: 플래그로 동작을 지정하고, 자격 증명은 환경 변수(environment variable)나 설정 파일(config file)로 out-of-band 설정해야 한다.
   3. 일반적 원칙: 인증뿐 아니라 사람용 CLI 전반의 대화형 질문을 제거해야 에이전트가 명령을 끝까지 실행할 수 있다.

4. MCP와 CLI의 트레이드오프 및 역할 분담

MCP의 제약은 실행 환경이 제공하는 일관된 경계를 만들고, CLI의 자유도는 강력한 조합을 가능하게 하지만 잘못된 호출 루프도 만들 수 있다.

4.1. MCP의 장점과 제약

1. 제약

   1. 사양 구현의 불균일성: MCP specification이 모든 클라이언트에서 동일하게 구현되지 않는다.
   2. 공급자별 추가 제한: 클라이언트 공급자가 사양 외 제한을 부과하며, Claude는 서버와 도구 호출 설명에 2KB 제한을 둔다.
   3. 실행 시간 제한: 도구 실행 시간에도 제한이 있어 장시간 실행 프로세스를 MCP로 처리하기 어렵다.
   4. 기능별 지원 편차: URL mode Elicitation처럼 사양에 있는 기능도 특정 클라이언트에서 빠질 수 있다.

2. 장점

   1. 호스팅된 최신 서버: 호스팅 MCP 서버는 항상 업데이트된 버전을 제공할 수 있다.
   2. 낮은 설치 부담: 사용자가 URL을 연결하는 방식으로 빠르게 시작할 수 있다.

4.2. CLI의 장점과 운영 부담

1. 장점

   1. 제약이 적은 실행: MCP의 서버·도구 설명 크기나 실행 시간 제한에 덜 묶인다.
   2. 긴 작업과 출력: 장시간 작업, 매우 긴 결과, 파일 리디렉션에 적합하다.
   3. Unix 도구 조합: 출력에 tail이나 head를 적용하고 파이프로 다른 도구에 넘길 수 있다.

2. 부담

   1. 버전 관리: 호스팅 MCP처럼 항상 최신 상태가 보장되지 않으므로 패키지 버전과 배포를 관리해야 한다.
   2. 자유도의 부작용: 호출에 경계가 없으면 잘못된 도구 호출이 이어지고 에이전트가 루프를 돌며 계속 실행될 수 있다.

4.3. 사용 상황에 따른 선택

1. MCP를 선택할 때

   1. 사용자 유형: 비기술 사용자가 데이터를 AI 앱에 연결할 때 적합하다.
   2. 작업 형태: 빠른 프로토타이핑, 일회성 보고서, MCP 생태계 안에서 여러 요소가 서로 통신하는 작업에 유리하다.

2. CLI를 선택할 때

   1. 사용자 유형: 기술 사용자가 명령과 데이터 흐름을 직접 제어할 때 적합하다.
   2. 작업 형태: 장시간 실행, 아주 긴 출력, 파일 저장, tail·head·Unix pipe를 이용한 후처리가 필요한 작업에서 강점을 발휘한다.

주요 발언 모음

“에이전트를 염두에 두고 CLI를 설계해야 한다.”

“사람에게 도움이 되는 것들이 에이전트에게는 방해 요소가 될 수 있다.”

“JSON을 입력받고 JSON으로 출력하라.”

“에이전트가 같은 실수를 반복한다면 그것을 계약으로 만드는 것을 고려하라.”

“CLI를 설치했는데도 에이전트가 그 CLI의 존재를 어떻게 알겠는가? 스킬은 반드시 필요하다.”

“MCP와 CLI는 각자의 자리가 있다.”

핵심 데이터 & 수치

• 하루 10회 초과: Airbyte 플랫폼이 하루에도 10번 넘게 변경될 수 있어 MCP와 CLI를 OpenAPI 사양에 연결한다.
• 커넥터 4개: MCP 예시 워크스페이스에서 사용 가능한 커넥터로 반환된 수다.
• 고객 5명: Zendesk 지원 티켓이 있는 유료 고객을 Zendesk와 Stripe에서 교차 검증해 반환한 수다.
• 핵심 MCP 도구 2개: describe와 execute로 커넥터 스키마 조회 및 레코드 read/write/delete를 담당한다.
• 2KB: Claude가 서버와 도구 호출 설명에 두는 제한의 예시다.
• 세 가지 공통 역량: 핵심 리소스 관리, 안전한 타사 서비스 인증, Context Store 검색과 시스템 액션이다.
• 세 가지 인터페이스: SDK, Web UI, MCP·CLI를 통해 Context Store에 접근한다.

결론 및 시사점

1. 에이전트용 CLI의 품질은 명령 수보다 에이전트가 입력을 추측하지 않고 성공 경로를 찾는지로 평가해야 한다.
2. JSON in/out, 명사-동사 명령 규칙, 일관된 리소스 표면은 에이전트의 구성·파싱·재사용을 단순하게 만든다.
3. 반복되는 잘못된 호출은 모델의 결함으로만 보지 말고 CLI 계약과 발견 가능성을 개선하라는 피드백으로 사용해야 한다.
4. 스킬은 CLI의 부속 문서가 아니라 도구의 존재를 알리고 필요한 명령 정보를 점진적으로 제공하는 발견 계층이다.
5. 인증은 에이전트가 사람의 입력을 기다리지 않도록 OAuth 장기 세션 또는 환경 변수·설정 파일 기반의 비대화형 흐름으로 설계해야 한다.
6. MCP는 단순한 설치와 호스팅 업데이트가 중요한 사용자 경험에 적합하고, CLI는 긴 실행·긴 출력·Unix 파이프 조합이 중요한 흐름에 적합하다.
7. Airbyte처럼 공통 플랫폼과 OpenAPI를 중심에 두면 MCP와 CLI가 서로 다른 표면을 제공하면서도 기능과 변경 사항을 함께 따라갈 수 있다.

핵심 요약

Airbyte는 데이터 이동 표준에서 AI 에이전트의 데이터 및 액션 레이어로 제품 범위를 확장했다. Context Store는 여러 SaaS의 레코드와 연락처를 검색 최적화 인덱스로 묶어 에이전트의 질의를 효율화한다. SDK와 Web UI와 MCP와 CLI는 같은 Context Store에 접근하는 서로 다른 인터페이스다. 모든 인터페이스는 핵심 리소스 관리와 타사 인증과 데이터 검색·실행이라는 세 가지 역량을 제공해야 한다. MCP와 CLI는 플랫폼을 재구현하지 않고 공통 플랫폼과 API를 호출하는 얇은 통합 계층으로 설계됐다. 하루에도 10번 넘게 변하는 플랫폼과 인터페이스를 동기화하는 기준으로 OpenAPI 사양을 활용한다. MCP는 비기술 사용자가 ChatGPT나 Claude에 데이터를 빠르게 연결하는 데 적합하다. 호스팅된 MCP URL만 입력해도 마켓플레이스 밖에서 최종 사용자가 연결할 수 있다. MCP 예시는 워크스페이스의 커넥터 4개를 조회하고 Zendesk와 Stripe를 결합해 유료 고객 5명을 찾는다. 커넥터 실행 표면은 describe와 execute라는 두 핵심 도구로 좁혀 성능을 높였다. Progressive discovery와 제한된 도구 설명은 MCP에 불필요한 컨텍스트가 쌓이는 문제를 줄인다. MCP 서버 인증은 주요 클라이언트와 설치 경험의 방향을 고려할 때 OAuth가 사실상 기본 경로다. MCP 사용자는 모바일 앱처럼 재로그인 없이 쓰기를 기대하므로 웹 앱과 분리된 장기 오프라인 세션이 필요하다. URL mode Elicitation은 클라이언트별 지원 차이 때문에 사양만 믿을 수 없어 직접 연결 흐름이 필요할 수 있다. 에이전트용 CLI는 사람이 아니라 에이전트가 발견하고 구성하고 호출하고 파싱한다는 전제로 설계해야 한다. JSON 입력과 JSON 출력은 복잡한 질의를 명확하게 만들고 jq와 Unix 파이프를 통한 후처리를 가능하게 한다. connectors list와 connectors create처럼 명사-동사 규칙을 모든 리소스에 일관되게 적용해야 한다. CLI에는 스킬을 함께 배포하고 참조 파일로 세부 정보를 나눠 에이전트의 점진적 탐색을 지원해야 한다. CLI 인증과 실행은 프롬프트 대신 플래그와 환경 변수와 설정 파일을 사용해 비대화형으로 처리해야 한다. MCP는 빠른 연결과 일회성 작업에, CLI는 장시간 작업과 긴 출력과 Unix 도구 조합에 각각 강점이 있다.