MCP 프로토콜 통합 실전: AI Agent가 임의의 도구를 호출하게 만들기

당신은 AI에게 항공권을 예약해달라고 부탁합니다. AI는 "저는 언어 모델이라 외부 시스템에 접근할 수 없습니다."라고 말합니다. 다른 Agent 제품으로 바꿔보니 예약할 수 있다고는 하지만, 비밀번호를 알려달라고 하며 관리자 권한까지 요구합니다. 당신은 망설여집니다.

LLM의 향후 10년 전쟁은 모델 자체가 아니라 **도구 호출 (Tool Calling)**에 있습니다. Anthropic은 2024년 말 Model Context Protocol (MCP)를 오픈 소스로 공개하여 「AI의 외부 도구 호출」을 표준화했습니다. 본문에서는 IHUI AI가 8개 엔드(end) 풀스택 AI 운영체제 내에서 MCP를 어떻게 통합하여 Agent가 실제로 업무를 수행할 수 있게 만드는지 설명합니다.

1. 페인 포인트(Pain Point): AI는 대화만 할 뿐, 일은 못 한다

LLM 애플리케이션의 가장 난처한 현황은 모델은 매우 똑똑하지만, 유리 상자 안에 갇혀 있다는 것입니다.

페인 포인트 1: Agent 프레임워크마다 제각각인 도구 프로토콜

• OpenAI Function Calling: tools + tool_calls
• Anthropic Tool Use: tool_use block
• LangChain Tools: BaseTool 클래스
• AutoGen Tools: @tool 데코레이터
• Coze / Dify: 시각화 플러그인

"주문 조회" 도구를 하나 만들면, 5개의 프레임워크에 맞추기 위해 5개의 코드를 작성해야 합니다.

페인 포인트 2: 도구 재사용률이 거의 0에 수렴

A 회사가 "날씨 조회" 도구를 만들면 자신의 Agent에서만 사용할 수 있습니다. B 회사가 이를 재사용하려면 처음부터 다시 구현해야 합니다. 업계 전체가 바퀴를 재발명하고 있습니다.

페인 포인트 3: 권한 통제 불능

Agent가 데이터베이스를 조회하려면 DB 계정을 줘야 하고, 이메일을 보내려면 SMTP 비밀번호를 줘야 하며, GitHub을 조작하려면 PAT(Personal Access Token)를 줘야 합니다. 프롬프트 인젝션 (Prompt Injection) 공격 한 번에 당신의 운영 데이터베이스가 무방비로 노출될 수 있습니다.

페인 포인트 4: 샌드박스(Sandbox) 부재

Agent가 당신이 작성한 코드 조각을 실행할 때, 당신의 서버에서 직접 eval()을 실행하나요? 운영 환경이 순식간에 망가질 수 있습니다.

2. 솔루션: MCP 프로토콜 + 샌드박스 실행

2.1 MCP란 무엇인가

**Model Context Protocol (MCP)**는 Anthropic이 주도하는 오픈 소스 AI 도구 호출 프로토콜입니다. 핵심 아이디어는 도구/리소스/프롬프트를 표준 서버(Server)로 노출하여, 어떤 MCP 호환 클라이언트(Client)든 호출할 수 있게 하는 것입니다.

비유하자면: MCP와 AI Agent의 관계는 LSP와 에디터의 관계와 같습니다. LSP가 하나의 언어 서버를 VSCode/Vim/Emacs에서 동시에 사용할 수 있게 하듯, MCP는 하나의 도구를 Claude Desktop/Cursor/모든 Agent에서 동시에 사용할 수 있게 합니다.

2.2 MCP의 3요소

1. Tools (도구): 실행 가능한 함수, 예: query_order(orderId), send_email(to, subject, body)
2. Resources (리소스): 읽기 가능한 데이터, 예: file:///path/to/doc.md, db://users/123
3. Prompts (프롬프트 템플릿): 재사용 가능한 프롬프트, 예: summarize_meeting(transcript)

2.3 IHUI AI의 MCP 아키텍처

┌──────────────────────────────────────────┐
│  AI Agent (LangGraph 오케스트레이션)      │
│  ↓ 도구 호출 결정                         │
...

각 MCP 서버는 독립적인 프로세스이며, Agent는 표준 프로토콜을 통해서만 통신합니다. 이를 통해 **도구 구현과 Agent가 디커플링(Decoupling, 결합도 낮춤)**됩니다.

3. 기술적 세부 사항

3.1 커스텀 MCP 서버 구축

IHUI AI는 공식 @modelcontextprotocol/sdk를 사용하여 MCP 서버를 작성합니다. 다음은 "주문 조회" 서버의 예시입니다:

// mcp-servers/order-query/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
...

핵심 설계:

• 도구용 JSON Schema (JSON Schema)로 입력 파라미터를 기술하여, LLM (Large Language Model)이 자동으로 호출 방법을 알 수 있게 합니다.
• 권한 검증 (Permission Validation)은 도구 내부에서 이루어지므로, Agent (에이전트)가 이를 우회할 수 없습니다.
• 구조화된 JSON을 반환하여, LLM이 추가적인 처리를 할 수 있도록 합니다.

3.2 MCP Client 통합

apps/ai-service/src/mcp/client.py:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from contextlib import asynccontextmanager
...

3.3 LangGraph 도구 호출 루프

MCP 도구를 LangGraph Agent에게 노출합니다:

from langgraph.graph import StateGraph, END
from langgraph.prebuilt import ToolNode
from litellm import acompletion
...

전체 호출 루프: LLM 결정 → MCP 도구 호출 → 결과를 LLM으로 반환 → 다음 단계 결정 → 완료될 때까지 반복.

3.4 권한 제어: 3계층 모델

IHUI AI의 MCP 권한은 세 가지 계층으로 나뉩니다:

1. 사용자 계층 (User-level): 사용자는 자신이 접근 권한을 가진 도구만 호출할 수 있습니다 (예: 자신의 주문 조회). 도구 구현 단계에서 userId를 검증합니다.
2. 요금제 계층 (Plan-level): Free 사용자는 5개의 내장 도구만 사용할 수 있고, Pro 사용자는 50개를, Enterprise 사용자는 모든 도구를 사용할 수 있습니다. MCP Client 계층에서 도구 목록을 필터링합니다.
3. 세션 계층 (Session-level): 사용자는 UI에서 "Agent가 X 도구를 호출하는 것을 허용하시겠습니까?"와 같이 명시적으로 승인해야 하며, 이는 OAuth 권한 부여와 유사합니다. Agent는 임시 토큰을 받으며, 세션이 종료되면 무효화됩니다.

def filter_tools_by_permission(
    user_id: str,
    plan: str,
...

3.5 샌드박스 실행: 코드 인터프리터 (Code Interpreter) MCP

가장 위험한 도구는 "코드 실행"입니다. IHUI AI는 Docker와 리소스 제한을 기반으로 한 독립적인 샌드박스 MCP 서버를 구축했습니다:

// mcp-servers/code-sandbox/index.ts
import Docker from 'dockerode';
const docker = new Docker();
...

보안 조치: 네트워크 차단 + 메모리/CPU 제한 + 5초 타임아웃 + 일회용 컨테이너 + 비 루트(non-root) 사용자. Agent가 어떤 코드를 실행하더라도 호스트 머신에 영향을 줄 수 없습니다.

3.6 A2A 프로토콜: MCP 상위의 Agent 간 상호 호출

MCP는 "Agent가 도구를 호출하는 것"을 해결하지만, Agent 간의 상호 호출은 어떻게 할까요? IHUI AI는 A2A (Agent-to-Agent) 프로토콜을 통합했습니다:

• Agent A (기획) → Agent B (검색) → Agent C (생성)
• 각 Agent는 MCP 서버를 노출하며, 다른 Agent는 이를 도구로 호출합니다.
• 단일 Agent가 아닌 Agent 네트워크를 형성합니다.

이것이 바로 IHUI AI의 **P3 심층 계층 (P3 Deep Layer)**입니다: 사용자가 Agent 토폴로지 (Topology)를 드래그하여 구성하면, 플랫폼이 스케줄링을 담당합니다.

4. IHUI AI 실전 데이터

실제 사례: 한 기업 사용자가 내부 ERP 시스템을 MCP 서버로 캡슐화하자, IHUI AI의 Agent가 원클릭으로 연결되었습니다. 직원은 자연어로 재고를 확인하고, 주문을 넣으며, 보고서를 생성합니다. 기존에는 통합에 3주가 걸렸던 작업을 2일 만에 완료했으며, 권한 격리 또한 명확하게 이루어졌습니다.

5. 시행착오 요약

문제 1: 도구 설명(Description) 미흡으로 인한 LLM의 오작동

LLM은 description 필드에 의존하여 도구를 호출합니다. 설명이 모호하면 ("주문 조회") LLM이 잘못 호출할 수 있습니다. 우리의 규정은 다음과 같습니다: 설명에는 반드시 ① 언제 사용하는지 ② 언제 사용하지 않는지 ③ 입력 파라미터의 의미 ④ 반환 구조가 포함되어야 합니다. 예: "주문 상세 정보를 조회합니다. 사용자가 명확하게 주문 상태를 물었을 때만 사용하며, 일상적인 대화 중에는 호출하지 마세요. id/items/total/status 필드를 포함한 주문 JSON을 반환합니다."

문제 2: 도구 수의 폭발로 인한 LLM의 선택 장애

도구가 많아지면 (50개 이상), LLM의 선택 오류율이 급증합니다. 해결책: 시나리오별로 그룹화하고, LangGraph 라우팅 노드에서 먼저 "도구 서브셋 (Subset)"을 선택한 뒤 LLM에 전달합니다.

문제 3: stdio vs SSE

MCP는 두 가지 전송 방식(Transport)을 지원합니다: stdio(로컬 서브프로세스)와 SSE(원격 HTTP). stdio는 성능이 좋지만 로컬에서만 사용 가능하며, SSE는 네트워크를 가로지를 수 있지만 지연 시간(Latency)이 높습니다. IHUI AI의 내장 도구는 stdio를 사용하고, 제3자 도구는 SSE를 사용하며, 클라이언트(Client) 계층에서 투명하게 전환됩니다.

함정 4: 도구 결과의 토큰 폭발

특정 도구가 10만 줄의 SQL 결과를 반환할 경우, 이를 컨텍스트(Context)에 그대로 넣으면 즉시 제한을 초과합니다. 저희는 MCP 클라이언트 계층에서 다음과 같이 절단(Truncation) 처리를 구현했습니다: tool_result_truncator(result, max_tokens=2000). 내용이 너무 길면 요약(Summary)을 제공하고 "전체 결과는 저장되었습니다. 상세 내용을 보려면 query_detail 도구를 호출하세요"라는 메시지를 표시합니다.

6. MCP를 도입하지 말아야 할 때

1. 단일 LLM 제조사에만 종속될 때: 제조사 고유의 함수 호출(Function Calling)을 사용하는 것이 더 가볍습니다.
2. 도구 개수가 5개 미만이며 외부와 공유하지 않을 때: 직접 캡슐화(Encapsulation)하는 것이 더 간단합니다.
3. 에이전트(Agent) 간 도구 재사용이 필요 없을 때: MCP의 핵심 이점은 "한 번 작성하면 모든 에이전트가 사용할 수 있다"는 점입니다. 만약 단 하나의 에이전트에서만 사용한다면 그 이점은 제한적입니다.

MCP의 진정한 가치는 생태계에 있습니다. 도구를 한 번 작성하면 모든 MCP 호환 클라이언트(Claude Desktop/Cursor/Cline/IHUI AI)에서 사용할 수 있습니다. 이는 과거 LSP(Language Server Protocol)가 에디터 생태계를 통일했던 것의 재현입니다.

7. 결론

MCP 통합의 핵심은 다음과 같습니다:

• 프로토콜 표준화: MCP를 통해 도구를 한 번만 작성하면 모든 에이전트가 호출할 수 있어, 5개의 프레임워크를 위해 5개의 코드를 작성하던 시대와 작별합니다.
• 서버(Server) 디커플링: 각 도구는 독립적인 프로세스이며, LangGraph 에이전트는 JSON-RPC를 통해서만 통신합니다.
• 3단계 권한 관리: 사용자 레벨 / 요금제 레벨 / 세션 레벨로 구분되어, 프롬프트 인젝션(Prompt Injection)이 발생하더라도 운영 데이터베이스를 파괴할 수 없습니다.
• 샌드박스 실행: 코드 실행형 도구는 Docker를 통해 격리되며, 네트워크 차단 + 리소스 제한 + 타임아웃 종료(Kill)가 적용됩니다.
• A2A 확장: MCP 위에서 에이전트 간 상호 호출을 구현하여 에이전트 네트워크(P3 심층 계층)를 형성합니다.

IHUI AI는 이미 MCP를 사용하여 28개의 내장 도구와 임의의 제3자 MCP 서버를 연결했습니다. 에이전트 시장의 도구들을 한 번만 작성하면 모든 플랫폼에서 통용됩니다. 만약 여러분도 에이전트 애플리케이션을 개발하고 있다면, 첫날부터 MCP를 사용할 것을 강력히 권장합니다. 나중에 마이그레이션하려면 도구 프로토콜 적응 과정이 매우 고통스러울 것입니다.

IHUI AI에 대하여

IHUI AI는 Apache 2.0 오픈 소스인 원스톱 8개 엔드포인트 풀스택 AI 운영체제입니다.

• 🌐 공식 웹사이트: https://aizhs.top
• 💻 GitHub: https://github.com/IHUI-INF-AI/IHUI-AI (Star ⭐로 응원해 주세요)
• 📦 8개 엔드포인트 동일 소스: Web / API / CLI / Desktop / Extension / Mobile / Miniapp
• 🤖 176개 모델: OpenAI / Claude / Gemini / Tongyi / DeepSeek / Zhipu / Wenxin / Doubao / Kimi / Ollama
• 💰 가격 정책: Free / Pro ¥49/월 / Team ¥199/인/월 / Enterprise ¥2999/월부터

5분 만에 Fork 하여 출시하세요. ChatGPT Team + Claude Code + Notion AI를 대체하며, 월 $60 이상을 절약할 수 있습니다.