모든 API는 에이전트(Agents)를 위해 재구축될 것이다
요약
현재의 API는 인간 개발자 중심의 설계로 인해 에이전트가 사용하기에 부적합한 '동사 격차(verb gap)' 문제를 안고 있습니다. 향후 API는 단순한 리소스 형태를 넘어 에이전트의 의도와 목표를 중심으로 하는 '에이전트 네이티브' 방식으로 재구축될 것입니다.
핵심 포인트
- MCP는 연결과 인증 등 '플러그' 영역을 표준화하지만, 작업의 논리적 흐름은 해결하지 못함
- 기존 API는 인간의 정신적 모델에 맞춰 설계되어 에이전트가 오작동할 가능성이 높음
- 미래의 API는 의도(intent), 상태, 승인, 복구를 중심으로 하는 '의도 형태의 계약'으로 진화할 것
MCP는 플러그(plug) 문제를 해결합니다. 하지만 동사 격차(verb gap)를 해결하지는 못합니다.
코딩 에이전트에게 사람이 개발하기에 아주 훌륭하게 문서화된 REST API(버전 관리 및 OpenAPI가 적용된, 인간 개발자가 기꺼이 사용할 만한 수준의 API)를 건네주고, 오후 한나절 만에 이를 MCP로 감싸준다고 해도, 에이전트가 여전히 허둥대는 모습을 보게 될 것입니다. 에이전트는 잘못된 엔드포인트(endpoint)를 선택합니다. 하나면 충분할 상황에서 세 번을 호출합니다. 물어봤어야 할 파괴적인 쓰기(destructive write) 작업을 수행해 버립니다. API가 나쁜 것이 아닙니다. 잘못된 소비자를 위해 만들어졌을 뿐입니다.
MCP는 항상 해결될 예정이었던 부분, 즉 플러그(the plug) 영역에서 승리하고 있습니다. 그리고 이 승리는 불편한 진실을 드러냅니다. 우리가 가진 거의 모든 API는 더 이상 유일한 주요 소비자가 아닌 대상을 위해 구축되었다는 사실입니다. 지난 20년 동안 그 소비자는 의도(intent)와 정신적 모델(mental model)을 가지고 나타나는 인간 개발자였습니다. 하지만 이제는 그 둘 모두를 가지고 있지 않으며, 당신이 제공하는 표면(surface)으로부터 그 둘을 모두 재구성해야 하는 에이전트입니다. 인터페이스의 주요 소비자가 이토록 완전히 바뀌면, 인터페이스는 재구축됩니다. 언제나 그래왔습니다.
따라서 제가 확언할 수 있는 주장은 다음과 같습니다: 에이전트가 작동하는 진지한 제품의 표면들은 에이전트 네이티브 작업(agent-native operations)을 중심으로 재구축될 것입니다. 단순히 감싸는(wrapped) 것이 아니라, 재구축(rebuilt)될 것입니다. 이것은 여전히 한 개인의 노트일 뿐 조언은 아니며, 의도적으로 방향성을 제시하는 것이지 마이그레이션(migration) 계획은 아닙니다. 제가 확신하지 못하는 것은 방향이 아닙니다. 오직 타임라인(timeline)뿐입니다.
제가 _모든 API_라고 말할 때, 모든 엔드포인트가 교체되거나 모든 프로토콜이 사라진다는 뜻은 아닙니다. 에이전트가 실행하도록 신뢰받는 제품 수준의 작업들이 리소스 형태의 API(resource-shaped APIs)에서 의도 형태의 계약(intent-shaped contracts)으로 이동한다는 것을 의미합니다. 즉, 목표(goals), 상태(state), 부수 효과(side-effects), 승인(approval), 그리고 복구(recovery)를 중심으로 재설계된다는 뜻입니다.
MCP는 작업이 아닌 플러그를 표준화합니다
MCP에 정당한 평가를 내리자면, MCP는 이제 Claude, ChatGPT, VS Code, Cursor, Codex, Copilot과 같은 교차 클라이언트 표준(cross-client standard)이 되었습니다. 연결(Connection), 인증(auth), 전송(transport), 인간 참여(human-in-the-loop), 장기 실행 작업(long-running Tasks) 등이 모두 꾸준히 표준화되고 있습니다.
하지만 명세(spec)에서 도구(tool)는 단지 함수(function)일 뿐입니다. 즉, 이름, 설명, 스키마(schema)에 불과합니다. MCP는 여러분의 도메인이 어떤 상태 전이(state transitions)를 갖는지, 도구들이 어떤 순서로 배치되는지, 어떤 작업이 위험한지, 혹은 어떤 작업에 승인이 필요한지를 의도적으로 결정하지 않습니다. 그것이 프로토콜(protocol)에 적합한 범위이기 때문입니다. 이는 또한 MCP가 여러분의 API가 현재 어떤 형태이든 상관없이, 그것을 노출할 수 있는 깔끔한 방법을 제공한다는 것을 의미합니다. 그리고 현재의 API는 계획을 수립하는 개발자를 위해 설계된 것입니다.
이 실패를 **동사 격차(the verb gap)**라고 부릅니다. API는 에이전트(agents)에게 명사(nouns)와 CRUD를 전달하지만, 에이전트에게는 의도(intent)를 담은 동사(verbs)가 필요합니다. 어떤 프로토콜도 그 격차를 메울 수 없는데, 그 격차는 전송 계층(wire)이 아니라 API 자체에 존재하기 때문입니다. MCP는 플러그(plug) 문제를 해결합니다. 하지만 동사 격차(verb gap)를 해결하지는 않습니다.
래퍼의 한계(The wrapper ceiling)는 이미 가시화되고 있습니다
그 증거는 가장 성숙한 API 기업들이 공개적으로 래퍼(wrapper) 방식에서 발을 빼고 있다는 점입니다.
GitHub의 공식 MCP 서버는 매우 훌륭합니다. 하지만 GitHub는 도구의 비대화(tool bloat)를 줄이고 에이전트의 추론(reasoning) 능력을 향상시키기 위해, 기본 도구 세트를 축소하고 PR 도구들을 더 적고 더 강력한 것들로 통합하고 있습니다. 여기서 얻을 수 있는 시사점은 명확합니다. 지구상에서 가장 뛰어난 API 기업 중 하나조차도 제품 API를 에이전트 도구로 1:1 매핑하는 것이 올바른 형태가 아니라는 점을 배우고 있다는 것입니다.
연구 결과도 같은 방향을 가리킵니다. AutoMCP는 OpenAPI 명세로부터 MCP 서버를 생성했습니다. 50개의 실제 API와 약 5,000개의 엔드포인트(endpoints)를 대상으로 조사한 결과, 도구 호출(tool-call) 성공률은 76.5%에서 99.9%로 상승했습니다. 하지만 이는 근본적인 명세를 수정한 후에나 가능한 일이었습니다. 에이전트 준비가 된 OpenAPI 문서에 관한 2026년 연구에 따르면, 에이전트들은 계획 수립(planning)과 도구 선택(tool selection) 단계에서 체계적으로 실패했으며, 사실상 모든 작업에서 결함이 발견되었습니다. 이 연구의 핵심 문구는 다음과 같습니다: API가 구조적으로는 유효할지라도, 에이전트를 위한 의미론적 준비(semantically ready)는 되어 있지 않을 수 있습니다.
모든 "그냥 감싸기 (just wrap it)" 방식은 결국 동일한 벽에 부딪힙니다. 즉, 계약 (contract)이 새로운 소비자에게 맞지 않으며, 래퍼 (wrapper)를 만드는 것만으로는 다른 계약을 만들어낼 수 없다는 것입니다. 래핑 (Wrapping)은 데모를 만들어낼 뿐이지만, 재구축 (Rebuilding)은 제품을 만들어냅니다.
"에이전트를 위해 재구축됨"의 모습
에이전트 네이티브 (Agent-native) API는 에이전트가 호출할 수 있는 API를 의미하는 것이 아닙니다. 그것은 에이전트가 자신이 무엇을 하고 있는지 알 수 있도록, 작업 (operations) 자체가 충분한 의도 (intent), 상태 (state), 그리고 안전성 (safety)을 담고 있는 API를 의미합니다.
단순히 몇 개의 거친 엔드포인트 (endpoints)를 덧붙이는 것이 아닙니다. 모든 작업에 대해
그리고 이것이 두 개의 API가 아닌 하나의 API여야 하는 이유는 다음과 같습니다. 개발자들 또한 이 모든 것을 원하기 때문입니다. 커밋 전 미리보기 (Preview-before-commit), 영향 범위 (blast radius), 명확한 권한 오류, 롤백 (rollback) — 이것들은 "에이전트 에디션"이 아니라, 단지 주요 소비자가 에이전트인 더 "나은" API일 뿐입니다. 인간용 API와 에이전트용 API를 영원히 따로 유지하고 싶지는 않을 것입니다. 시간이 흐름에 따라, 에이전트 네이티브 (agent-native) 설계가 인간용 설계를 흡수해야 합니다.
이는 지난 포스트와 연결됩니다. 엄밀한 사실이 모호한 표현을 단정적인 진술로 압축하듯, 훌륭한 작업 (operation)은 위험한 다단계 워크플로 (multi-step workflow)를 하나의 확신 있는 동사 (verb)로 압축합니다. 엄밀함은 압축하며, 훌륭한 작업 또한 마찬가지입니다.
API뿐만이 아닙니다 — CLI도 동일한 접점입니다
이것은 결코 REST에 관한 것이 아니었습니다. 이는 에이전트가 작동하는 모든 접점 (surface)에 관한 것이며, CLI (Command Line Interface)가 또 다른 큰 축입니다. 코딩 에이전트는 터미널 (terminal)에서 살아갑니다. git, kubectl, 빌드 및 배포 스크립트를 실행하며, 동일한 동사 간극 (verb gap)에 직면합니다. 즉, 플래그 (flags)를 이미 알고 있는 인간을 가정하고 만들어진 도구들 말입니다.
CLI는 API의 경우에 숨겨져 있던 두 번째 문제인 출력 (output)을 추가합니다. 대부분의 CLI는 인간을 위해 출력합니다 — 색상, 진행 표시줄 (progress bars), 자유 형식의 로그, 눈으로 훑어보게 되어 있는 요약 줄 등입니다. 에이전트는 이를 스크래핑 (scrape)해야 하며, 이는 다시 동사 간극이 반환 경로 (return path)로 이동한 것과 같습니다. 따라서 에이전트 네이티브 CLI는 예쁜 터미널 포맷팅보다 기계 판독 가능 출력 (machine-readable output) — --json, 구조화된 로그 (structured logs), 안정적인 종료 코드 (exit codes), 다음 작업을 명시하는 오류 — 을 우선시합니다. 두 가지를 모두 가질 수 없을 때, 기본 설정은 뒤집힙니다: 에이전트가 읽기 쉬운 것이 눈에 읽기 쉬운 것보다 우선합니다.
이는 동사 간극의 양면과 같습니다. 호출 측 (Calling side): 의도를 담은 동사들. 반환 측 (Return side): 에이전트가 해석해야 하는 산문 (prose)이 아니라, 파싱 (parse)할 수 있는 상태 (state). 그리고 이 변화는 API보다 더 큽니다. 반대편에 인간이 있다고 가정하고 구축한 모든 인터페이스 — API, CLI, 로그, 출력 형식 — 는 반대편이 에이전트가 되는 순간 재검토의 대상이 됩니다.
보안은 이것을 "하면 좋은 것"이 아닌 "반드시 해야 하는 것"으로 만듭니다
MCP 클라이언트(clients)는 도구(tool)의 이름, 설명, 스키마(schema)를 모델의 컨텍스트(context)에 직접 넣습니다. 따라서 악의적인 설명이 모델을 유도할 수 있습니다 (도구 오염 (tool poisoning), 혼동된 대리인 (confused-deputy), 과도하게 넓은 범위 (over-broad scopes)). 또한 에이전트(agents)는 설정된 도구를 자율적으로(autonomously) 사용합니다. GitHub의 자체 문서에서도 바로 이 이유 때문에 읽기 전용(read-only) 도구에 대한 허용 목록(allowlisting) 작성을 권장합니다.
인간 중심의 API(human-shaped API)에서 허용 목록만으로는 안전한 쓰기(writes)를 보장할 수 없습니다. 쓰기 작업은 '미리보기(preview) → 승인(approve) → 커밋(commit)'의 과정으로 재구축되어야 하며, 권한 오류는 그 이유를 스스로 설명할 수 있어야 합니다. 안전함(Safety)은 나중에 추가하는 래퍼(wrapper)가 아니라, 운영(operations) 자체에 설계해 넣어야 하는 속성입니다.
현재는 세 개의 계층, 나중에는 하나의 계약
이것은 하룻밤 사이에 일어나지 않을 것입니다. 단기적으로는 세 가지가 공존하겠지만, 오직 하나만이 최종 목적지(endgame)입니다.
| 계층 (Layer) | 정의 | 상태 |
|---|---|---|
| Direct API / SDK / CLI | 로컬 우회 경로 — 파일, 셸(shell), git, 테스트 | 프로토콜보다 근접성이 유리한 곳에서 지속됨 |
| ... |
래퍼(wrapper)는 전환기(transition)로서 유용합니다. 즉, 오늘날 존재하는 것들을 연결해 주지만, 그 아래에는 레거시 계약(legacy contract)을 품고 있으며, 바로 그 계약이 문제입니다. 시간이 흐르면서 코어(core)가 재구축되고 래퍼는 해체됩니다. 이는 모바일 BFF(Backend For Frontend)가 영원히 심(shim)으로 남는 대신 재설계된 API로 대체되었던 것과 같은 방식입니다.
실무적으로: 그린필드(greenfield, 신규 프로젝트)는 지금 당장 에이전트 네이티브(agent-native)로 시작해야 합니다. 어차피 다시 작성하게 될 인간 전용 계약(human-only contract)을 배포할 이유는 없습니다. 브라운필드(brownfield, 기존 프로젝트)는 가교로서 래퍼를 사용한 뒤, 가장 중요한 운영(operations)부터 재구축합니다. 어떤 방식이든 화살표는 한 방향을 가리키고 있습니다.
나 스스로가 제기할 수 있는 반론들
- "모든 API를 다시 작성할 수는 없습니다. 레거시(Legacy)는 영원합니다." 레거시는 지속됩니다. 하지만 "지속된다"는 것이 "당신이 새로 구축할 방식"이라는 뜻은 아닙니다. SOAP는 여전히 작동하고 있지만, 아무도 그것부터 시작하지는 않습니다. 인간 중심의 API는 당신이 감싸서(wrap) 마이그레이션해야 할 대상이 되는 것이지, 설계의 대상이 되는 것이 아닙니다.
- "이것은 그저 BFF(Backend For Frontend)의 재명명일 뿐입니다." 기술 자체는 새롭지 않습니다. 소비자가 새로운 것입니다. BFF는 인간이 설계한 고정된 UI 흐름에 봉사합니다. 에이전트 네이티브(agent-native) 작업은 자신의 전제 조건, 위험성, 그리고 복구 방법을 드러내야 합니다. 왜냐하면 에이전트가 직접 계획을 "형성(forming)\
요즘 저는 프롬프트에 "쓰기 전에 미리보기(preview)를 하라", "파괴적인 작업을 하기 전에 먼저 물어보라", "할 수 없는 이유를 설명하라"와 같은 방어적인 지침(defensive lines)을 계속 덧붙이고 있습니다. 이는 에이전트(agent)를 신뢰하지 못해서가 아닙니다. 제가 에이전트에게 넘겨주는 작업(operations) 자체가 모호하기 때문에, 상기시키는 것만이 제가 가진 유일한 패치(patch)이기 때문입니다. 작업(operations) 자체에 자체적인 미리보기(preview), 승인(approval), 그리고 롤백(rollback) 기능이 포함되도록 재구축한다면, 이러한 지침들은 더 이상 필요하지 않게 될 것입니다.
만약 작업(operation)이 설계 단계부터 안전하다면(safe by design), 에이전트에게 그것을 조심해서 다루라고 요청할 필요가 없습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기