에이전트에게 셸이 있다면 커맨드라인을 주세요

Model Context Protocol은 스스로를 “AI 애플리케이션을 외부 시스템에 연결하기 위한 오픈소스 표준”이라고 설명합니다(modelcontextprotocol.io). 프로젝트는 이를 USB-C 포트에 비유합니다. 여러 기기를 위한 하나의 플러그라는 뜻입니다.

현재 사양인 2026-07-28 버전은 호스트(AI 애플리케이션), 클라이언트(그 안의 커넥터), 서버(데이터와 도구를 제공하는 서비스)를 정의하며, 이들은 JSON-RPC로 통신합니다. 서버는 리소스, 프롬프트, 도구를 제공할 수 있습니다. 에이전트가 가장 많이 쓰는 것은 도구입니다. 클라이언트가 tools/list로 서버에 목록을 요청하면, 각 도구는 이름, 설명, 입력용 JSON Schema와 함께 전달됩니다.

커맨드라인이라고 해서 저절로 에이전트에게 좋은 것은 아닙니다. 사람은 잘 요구하지 않는 몇 가지 특성이 필요합니다.

• 자신을 데이터로 설명합니다. --help와 전체 명령 목록을 JSON으로 제공하므로 에이전트가 플래그를 추측할 필요가 없습니다.
• 출력은 계약입니다. --json을 쓰면 stdout에 정확히 하나의 JSON 문서가, stderr에 JSON 오류가 나옵니다.
• 종료 코드에 의미가 있습니다. 호출 수정, 사람에게 묻기, 대기, 재시도. 숫자 하나로 에이전트가 다음에 할 일을 압니다.
• 줄 수 없는 입력을 기다리지 않습니다. 터미널이 없으면 아무것도 묻지 않습니다. 파괴적 단계에는 --yes 같은 명시적 플래그가 필요합니다.
• 실행 대신 보여 줄 수 있습니다. --dry-run은 정확한 요청을 보내지 않고 출력합니다.
• 비밀 정보는 출력에 나오지 않습니다. --verbose와 --dry-run에서도 마찬가지입니다. 에이전트가 보는 것은 모두 컨텍스트에 들어가기 때문입니다.
• 에이전트가 실행되는 어디서든 쉽게 설치할 수 있고, 가능하면 의존성 트리가 없습니다.

Anthropic 엔지니어링 팀은 2025년 11월 이 문제를 이렇게 설명했습니다. “대부분의 MCP 클라이언트는 모든 도구 정의를 미리 컨텍스트에 직접 불러온다.” 그리고 이 설명들이 응답 시간과 비용을 늘린다고 했습니다(Code execution with MCP). 이들의 권고는 모델이 도구 정의를 필요할 때 읽게 하는 것입니다.

공정하게 말하면 클라이언트도 따라잡고 있습니다. Claude Code는 이제 기본적으로 MCP 도구를 지연 로딩합니다. 세션 시작 시 도구 이름과 서버 안내만 불러오고, 전체 정의는 Claude가 도구를 검색할 때 가져옵니다(MCP tool search). 다른 클라이언트는 여전히 전부 불러올 수 있습니다.

CLI는 필요할 때 불러오기가 기본입니다. 에이전트가 명령을 실행하기 전에는 컨텍스트에 아무것도 없기 때문입니다. tm 0.3.0에서 불러올 수 있는 양을 측정했습니다. 전체 목록(tm schema --json)은 377,203자, 모든 명령 그룹 개요(tm --json)는 32,110자, invoices 그룹은 104,009자입니다. 명령 하나는 157개 명령 기준 중앙값 934자입니다. 방법: npx -y @time-momentum/cli@0.3.0 schema --json | wc -c와 다른 호출도 같은 방식으로, 2026년 10월 10일에 측정.

목록은 작지 않습니다. 바로 그게 핵심입니다. 무엇을 불러올지는 에이전트가 정하며, 대개 그룹 하나나 명령 하나입니다.

같은 Anthropic 글의 표현대로 MCP에서는 “모든 중간 결과가 모델을 거쳐야 합니다.” 에이전트가 세기만 하면 되는 청구서 500건의 목록도 컨텍스트에 그대로 들어갑니다.

셸에서는 에이전트가 읽기 전에 거릅니다. tm payments outstanding --json | jq '[.data[].summary.outstanding_micros] | add / 1000000'은 숫자 하나, 즉 유로 단위 미수금 합계를 돌려줍니다. tm invoices list --all --json | jq '[.data[] | select(.status == "draft")] | length'는 모든 페이지에 걸쳐 초안 수를 셉니다. 같은 줄이 에이전트 없이 cron 작업이나 셸 스크립트에서도 작동합니다.

MCP에서 인가는 선택 사항입니다. HTTP로 연결하는 원격 서버는 사양의 OAuth 2.1 흐름을 따라야 하고, stdio로 연결하는 로컬 서버는 환경에서 자격 증명을 가져옵니다. 사용자마다 자기 계정으로 로그인하는 채팅 앱이라면 OAuth가 더 편합니다.

CLI는 보통 API 키로 작동합니다. 간단하지만 주의가 필요합니다. 키가 에이전트가 읽는 내용에 절대 나타나면 안 됩니다. tm은 키를 권한 600의 로컬 파일이나 환경 변수에 두고, 쓰기 키를 한 시간 유효한 토큰으로 교환하며, --verbose나 --dry-run에서도 키를 출력하지 않습니다. 이 교환으로 받은 토큰으로는 새 키를 만들거나 계정을 삭제할 수 없습니다.

에이전트가 CLI로 하는 모든 호출은 복사하고, 읽고, 직접 실행해 볼 수 있는 한 줄입니다. --dry-run은 한 걸음 더 나아가 아무것도 보내지 않고 메서드, URL, 본문을 보여 줍니다. 그래서 에이전트의 작업을 실행 전에 검토할 수 있고, 이는 청구서에서 특히 중요합니다.

MCP에도 개발자용 MCP Inspector 같은 도구가 있습니다. 하지만 도구 호출은 결과를 보려고 내 터미널에 입력해 볼 수 있는 것이 아닙니다.

CLI는 버전이 있는 패키지입니다. 고정할 수 있고(npx -y @time-momentum/cli@0.3.0), 되돌릴 수 있으며(tm update --to <version>), 어제 작동한 스크립트가 오늘도 작동한다는 것을 압니다. API가 옛 버전이 잘못 처리할 방식으로 바뀌면 서버는 명확한 오류와 업데이트 명령을 보여 주며 그 버전을 거부합니다.

MCP는 프로토콜 버전을 날짜로 매기고, 서버가 실행 중에 도구 목록 변경을 알릴 수 있게 합니다. 원격 서버는 오늘 어떤 도구를 줄지 스스로 정합니다. 아무것도 깨지지 않는 동안은 편리합니다.

Claude Code, Codex, Cursor와 대부분의 코딩 에이전트는 셸 명령을 실행할 수 있습니다. CLI는 클라이언트가 다른 무언가를 지원하지 않아도 이 모두에서 작동하며, 샌드박스와 CI에서도 마찬가지입니다.

• 셸이 없는 클라이언트. claude.ai, Claude Desktop, Claude 모바일 앱은 커넥터, 즉 MCP 서버로 외부 도구에 닿습니다(Claude docs). 여기서는 CLI가 도움이 되지 않습니다.
• 표준 탐색. 모든 MCP 서버는 tools/list에 같은 방식으로 답하고, 공식 MCP Registry가 서버를 모아 둡니다. CLI는 저마다 다른 방식으로 자신을 설명합니다.
• 사용자별 로그인. OAuth로 각자 키를 다루지 않고 자기 계정을 연결합니다.
• 비개발자 사용자. 채팅 앱에서 커넥터를 추가하는 것이 커맨드라인을 설치하는 것보다 쉽습니다.

사용자의 에이전트는 이미 셸에서 고객 프로젝트를 작업하고 있습니다. 그래서 Time Momentum에는 MCP 서버가 없습니다. 대신 제품 전체를 다루는 커맨드라인 tm이 있습니다. 공수, 고객, 계약, 프로젝트, 청구서와 전자 인보이스, 입금, 작업 내역서, 수익성까지입니다.

tm에는 런타임 의존성이 없습니다. 커맨드라인용 REST API 작업마다 명령이 정확히 하나씩 있으며(0.3.0 버전 기준 143개 작업), API가 바뀔 때마다 테스트가 이를 강제합니다. tm skill은 설치된 버전에 맞는 사용 안내를 돌려줍니다. Claude Code에서는 tm skill --install이 이를 가리키는 짧은 스킬을 추가하며, Time Momentum은 Claude Code 플러그인으로도 제공됩니다.

청구서 발행, 취소, 삭제에는 명시적인 --yes가 필요합니다. 그렇지 않으면 터미널이 없을 때 tm은 멈춥니다.