Originally published on tamiz.pro.

REST에서 MCP로: 즉각적인 컨텍스트 포킹을 위한 자체 호스팅 AI 에이전트 스택 아키텍처링

RESTful 서비스에서 Model Context Protocol (MCP)로의 전환은 단순히 전송 계층(transport layer)의 변화가 아닙니다. 이는 AI 에이전트가 복잡한 시스템을 발견하고, 추론하며, 조작하는 방식에 대한 근본적인 변화입니다. 전통적인 API 게이트웨이는 엔드포인트만 노출할 뿐, 그 안에 담긴 _시맨틱(semantics)_은 노출하지 않습니다. /users/{id}와 같은 엔드포인트는 기계에게 어디를 호출해야 하는지 알려주지만, LLM에게 사용자가 무엇인지, 어떤 권한이 적용되는지, 또는 이 리소스가 시스템 그래프의 나머지 부분과 어떻게 관련되는지는 알려주지 못합니다. 기존 인프라를 MCP 도구로 감싸서(wrapping) 사용하면, 취약한 프롬프트 엔지니어링과 견고하고 도구 기반의 에이전트 워크플로우 사이의 간극을 메울 수 있습니다. 본 심층 분석에서는 레거시 REST/GraphQL 서비스를 응집력 있는 MCP 생태계로 마이그레이션하는 데 필요한 아키텍처 패턴과, 이 구조가 어떻게 밀리초 단위로 실행 컨텍스트를

Model Context Protocol(MCP)은 모델에 도구를 노출하기 위한 표준 인터페이스를 정의함으로써 이 문제를 해결합니다. MCP 서버는 단순한 원시 엔드포인트(raw endpoints) 대신 '기능(capabilities)'을 노출합니다. 이러한 기능들은 입력 스키마, 설명, 오류 처리 로직 등을 포함하여 자체적으로 기술(self-describing)됩니다. LLM이 MCP 서버와 상호 작용할 때, 단순히 함수를 호출하는 것이 아니라 서버가 에이전트의 컨텍스트를 능동적으로 관리할 수 있는 프로토콜에 참여하게 됩니다. 이를 통해 '컨텍스트 포킹(context forking)'이 가능해지는데, 이는 주된 대화 상태를 오염시키지 않으면서 하위 작업(sub-tasks)을 위해 격리된 실행 스레드를 생성하는 능력을 의미합니다.

2. 자체 호스팅 스택의 아키텍처 개요

자체 호스팅 스택을 구축하려면 세 가지 핵심 구성 요소가 필요합니다: MCP 서버 어댑터(MCP Server Adapter), 에이전트 오케스트레이터(Agent Orchestrator), 그리고 로컬 벡터 저장소(Local Vector Store)입니다.

2.1. MCP 서버 어댑터

어댑터는 기존의 REST/GraphQL 코드베이스와 MCP 프로토콜 사이의 다리 역할을 합니다. 이는 비즈니스 로직을 재작성하는 것이 아니라, 이를 감싸는(wraps) 역할을 합니다.

핵심 설계 원칙:

• 멱등성 매핑(Idempotency Mapping): LLM이 모호한 성공 응답 때문에 작업을 재시도할 수 있으므로, 상태를 변경하는 MCP 도구는 멱등적(idempotent)이어야 합니다.
• 세분화된 추상화(Granular Abstraction): GET /api/v1/everything와 같은 것을 노출하지 마십시오. 대신 원시 SQL이나 복잡한 쿼리 문자열보다는 search_orders_by_date_range와 같이 고수준의 의미론적 도구(high-level semantic tools)를 노출해야 합니다.

2.2. 에이전트 오케스트레이터

오케스트레이터는 생명주기 관리(lifecycle management)를 담당합니다. 메인 스레드를 시작하고, 도구 호출을 모니터링하며, 포킹 로직을 관리합니다. 저희 구현에서는 각 도구 호출을 이벤트로 간주하는 경량의 이벤트 기반 아키텍처를 사용합니다.

2.3. 자체 호스팅이 필요한 이유?

클라우드 LLM은 편리함을 제공하지만, 에이전트 스택을 자체 호스팅하면 데이터 프라이버시를 보장하고 복잡한 로컬 도구 호출에 대한 지연 시간을 줄이며 컨텍스트 관리에 대한 세밀한 제어를 할 수 있습니다. 저희 벤치마크에서 언급된 5.6초의 포킹(forking) 측정값은 활성 컨텍스트 상태를 클론하고, 새로운 서브 에이전트 스레드를 초기화하며, 주요 컨텍스트 전환(예: '고객 지원' 모드에서 '데이터 분석' 모드로 전환) 후에 실행을 재개하는 데 걸리는 시간을 의미합니다.

3. REST 엔드포인트를 MCP 도구로 변환하기

변환 과정은 세 단계로 이루어집니다: 스키마 추출(Schema Extraction), 도구 정의(Tool Definition), 그리고 프로토콜 구현(Protocol Implementation).

3.1. 스키마 추출

REST API의 경우, OpenAPI (Swagger) 정의를 활용합니다. GraphQL의 경우, 인트로스펙션 쿼리(introspection query)를 파싱합니다. 목표는 리소스들을 도구로 매핑하는 것입니다.

// 예시: REST 엔드포인트를 MCP 도구 정의로 변환하기
import { z } from 'zod';
import { MCPTool } from '@mcp/sdk';
...

3.2. GraphQL 복잡성 처리

GraphQL은 깊은 중첩(deep nesting) 기능 때문에 MCP에 본질적으로 더 복잡합니다. 단일 GraphQL 쿼리는 데이터의 트리 구조를 반환할 수 있습니다. GraphQL을 MCP 도구로 변환할 때, 출력물을 평탄화(flattening)하는 것을 권장합니다. LLM은 깊게 중첩된 트리보다 평평하고 JSON과 유사한 구조를 선호합니다.

전략: 일반적인 execute_graphql_query 도구 대신, 자주 사용되는 쿼리에 대한 특정 MCP 도구를 생성해야 합니다. 범용적인 도구는 LLM이 유효한 GraphQL 구문을 작성하도록 강제하는데, 이는 흔한 실패 지점입니다. fetch_customer_orders와 같은 특정 도구들은 쿼리 로직을 추상화합니다.

4. 컨텍스트 포킹 구현하기

컨텍스트 포킹은 이 스택의 핵심 혁신입니다. 표준 에이전트 구현에서는, 만약 에이전트가 루프에 빠지거나 컨텍스트 창(context window)이 가득 차면 전체 대화를 재설정하거나 요약해야 하며, 이때 미묘한 뉘앙스를 잃게 됩니다.

4.1. 포킹 메커니즘

4.1. 포킹 메커니즘

포킹(Forking)은 메인 에이전트가 현재 상태의 스냅샷을 가진 "자식(child)" 에이전트를 생성할 수 있게 합니다. 자식 에이전트는 하위 작업(예: "데이터베이스를 사용하여 이 인보이스를 확인하세요")을 실행하고, 부모에게는 오직 _결과(result)_만 반환하여 부모의 컨텍스트를 깨끗하게 유지합니다.

5.6초 벤치마크:
로컬 LLM (Llama-3-8B-Instruct) 및 표준 16GB GPU를 사용하여 테스트한 결과, 포킹 과정은 다음 단계들로 구성됩니다:

1. 컨텍스트 직렬화(Context Serialization) (1.2초): 활성 메시지 기록과 도구 상태를 직렬화합니다.
2. 스레드 초기화(Thread Initialization) (0.8초): 새로운 에이전트 인스턴스를 위한 메모리를 할당합니다.
3. 모델 컨텍스트 로딩(Model Context Loading) (2.5초): 직렬화된 컨텍스트를 로컬 모델의 KV-cache에 재주입합니다.
4. 핸드셰이크(Handshake) (1.1초): 자식 에이전트를 위한 MCP 세션을 설정합니다.

총합: 5.6초. 이는 사용자가 메인 에이전트가 기다리는 동안 하위 에이전트가 복잡한 검증 작업을 수행하는 실시간 상호작용 워크플로우에 충분히 빠른 속도입니다.

4.2. 포킹의 코드 구현

class AgentOrchestrator:
    def __init__(self, llm_client, mcp_server):
        self.llm = llm_client
...

5. 프로덕션 베스트 프랙티스

5.1. 오류 처리 및 재시도(Error Handling and Retries)

LLM은 확률적입니다. 따라서 간혹 유효하지 않은 JSON을 생성하거나 잘못된 매개변수로 도구를 호출할 수 있습니다. 사용자의 MCP 서버는 복원력이 있어야 합니다.

• Zod/Pydantic 사용: 경계(boundary)에서 엄격한 검증을 수행하여 쓰레기 데이터가 REST API에 도달하는 것을 방지합니다.
• 우아한 실패 처리(Graceful Failures): 도구가 실패할 경우, 원시 스택 트레이스 대신 LLM이 해석할 수 있는 구조화된 오류 객체를 반환해야 합니다.

5.2. 컨텍스트 창 관리(Context Window Management)

포킹을 사용하더라도 컨텍스트 창은 가득 차게 됩니다. 오래된 메시지를 요약하는 "슬라이딩 윈도우(sliding window)" 전략을 구현하세요. 예를 들어, 대화가 20턴을 초과하면 1~15턴을 단일 요약 블록으로 압축합니다:
[SUMMARY] 지난 15개 메시지 동안 사용자는 3분기 판매 보고서를 요청했습니다. 에이전트는 'sales.get_quarterly' 도구를 조회하여 5% 증가를 발견했습니다.

5.3. 보안 격리 (Security Isolation)

MCP 도구는 임의의 코드를 실행하거나 민감한 데이터에 접근할 수 있으므로, 이를 격리해야 합니다. 가능한 경우 읽기 전용 액세스를 가진 샌드박스 컨테이너에서 MCP 서버를 실행하고, 최소 범위(minimal scopes)를 가진 API 키를 사용하세요.

6. 자주 묻는 질문 (Frequently Asked Questions)

질문: MCP는 로컬 LLM과만 호환되나요?
답변: 아닙니다. MCP는 전송 계층에 구애받지 않습니다(transport-agnostic). OpenAI, Anthropic 또는 로컬 모델과 함께 사용할 수 있습니다. 로컬 모델의 장점은 MCP 서버를 동일한 기기에 호스팅할 수 있어 도구 호출 시 네트워크 지연 시간(network latency)을 줄일 수 있다는 것입니다.

질문: 이것은 OpenAI의 함수 호출(function calling)과 어떻게 비교되나요?
답변: 함수 호출은 상태가 없으며(stateless), 특정 제공업체에 묶여 있습니다. MCP는 도구 노출을 표준화하는 프로토콜이므로, 다양한 LLM 백엔드 전반에 걸쳐 이식성이 높습니다. 또한 단순한 함수 스키마가 갖지 못한 의미적 풍부함(semantic richness)을 더합니다.

질문: GraphQL 구독(GraphQL subscriptions)과 MCP를 사용할 수 있나요?
답변: 직접적으로는 어렵습니다. 왜냐하면 MCP 도구는 요청-응답 방식이기 때문입니다. 하지만, 구독 기능을 폴링하거나 타임아웃이 있는 특정 이벤트를 기다리는 도구로 감싸서(wrap) 구현한 후, 이벤트가 발생할 때 결과를 반환하도록 할 수 있습니다.

결론 (Conclusion)

REST/GraphQL API를 MCP 도구로 변환하는 것은 시스템을 수동적인 데이터 소스에서 AI 에이전트를 위한 능동적이고 의미론적인 인터페이스로 변화시킵니다. 컨텍스트 포킹(context forking) 기능을 갖춘 자체 호스팅 스택을 구축함으로써, 컨텍스트 창의 한계에 부딪히지 않고 복잡한 에이전트 워크플로우를 관리하는 능력을 얻게 됩니다. 5.6초 포킹 벤치마크는 시작일 뿐입니다. 로컬 모델이 더 빨라지고 MCP 채택률이 높아짐에 따라, 우리는 단순히 스마트할 뿐만 아니라 훨씬 더 탄력적이고 안전한 에이전트 스택을 보게 될 것입니다. 에이전트 아키텍처에 대한 추가적인 통찰력을 원한다면, Tamiz's Insights에서 더 기술적인 심층 분석(deep-dives)을 살펴보세요.