기존 BAU(Business-as-Usual) REST 마이크로서비스가 Model Context Protocol(MCP)을 통해 AI 에이전트와 연동되는 방식을 보여주는 실행 가능한 개념 증명(PoC)입니다.
이 데모는 Google Gemini를 사용하여 MCP 도구를 발견하고, 고객 및 주문 정보를 조회하며, 통제된 주문 취소 작업을 수행합니다. BAU 서비스는 독립적인 REST API로 유지되며, MCP는 해당 API와 에이전트 사이의 통합 경계 역할을 합니다.
포함된 시나리오는 에이전트에게 다음을 요청합니다:
CUST-1001의 프로필을 조회합니다.
고객의 주문 목록을 확인합니다.
Processing 상태인 주문을 식별합니다.
제공된 사유로 ORD-9002를 취소합니다.
완료된 작업을 요약합니다.
예상 도구 호출 순서는 다음과 같습니다:
Gemini agent
-> MCP tool discovery over stdio
-> MCP server
-> Customer and Order REST APIs
-> Tool results returned to Gemini
-> Final user-facing summaryRelated MCP server: MCP API Tool Demo
+------------------+ stdio +------------------+ HTTP +----------------------+
| Gemini agent | <----------------> | MCP server | <--------------> | Customer service |
| agent_runner.py | | server.py | | localhost:8001 |
+------------------+ +--------+---------+ +----------------------+
|
| HTTP
v
+----------------------+
| Order service |
| localhost:8002 |
+----------------------+도구 | 용도 |
| 고객 프로필, 등급, 상태 및 신용 한도를 조회합니다. |
| 고객과 연결된 주문 목록을 조회합니다. |
| 주문 상태가 취소를 허용하는 경우 주문을 취소합니다. |
.
├── agent/
│ └── agent_runner.py # Gemini agent and MCP client
├── mcp_server/
│ └── server.py # MCP tools and REST integration
├── services/
│ ├── customer_service.py # Mock customer REST API
│ └── order_service.py # Mock order REST API
├── tests/
│ └── test_services.py # Service behavior tests
├── .env.example # Environment variable template
├── requirements.txt # Python dependencies
└── mcp_microservices_poc_blueprint.md
# Detailed design and implementation referencePython 3.11 이상
Google AI Studio의 Gemini API 키
Windows PowerShell, macOS/Linux 셸 또는 이에 상응하는 터미널
에이전트 실행 시 Gemini API에 대한 네트워크 액세스
이 프로젝트는 Anthropic 또는 OpenAI API 키가 필요하지 않습니다.
프로젝트 디렉터리에서 PowerShell을 엽니다:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env.env를 열고 your_gemini_api_key_here를 본인의 키로 교체합니다:
GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash.env를 커밋하거나 API 키를 소스 코드에 넣지 마십시오. 선택한 모델은 Gemini 계정에서 사용 가능해야 합니다.
세 개의 터미널을 사용합니다. 각 터미널에서 .venv를 활성화합니다.
python services/customer_service.pyhttp://localhost:8001에서 실행됩니다.
python services/order_service.pyhttp://localhost:8002에서 실행됩니다.
python agent/agent_runner.py에이전트는 MCP 서버를 하위 프로세스로 시작하고, 해당 도구를 발견한 후 샘플 워크플로를 실행합니다.
두 서비스가 실행되는 동안 다음 명령을 실행합니다:
Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001가상 환경이 활성화된 상태에서:
python -m pytest -q테스트는 대소문자를 구분하지 않는 고객 조회, 존재하지 않는 고객, 처리 중인 주문의 취소, 배송 완료된 주문의 취소 방지를 다룹니다.
변수 | 설명 | 기본값 |
| Gemini 인증 키입니다. | 필수 |
| 에이전트가 사용하는 Gemini 모델입니다. |
|
| 고객 서비스 기본 URL입니다. |
|
| 주문 서비스 기본 URL입니다. |
|
이 프로젝트는 통합 패턴을 쉽게 검사하고 실행할 수 있도록 설계된 로컬의 의도적으로 작은 POC입니다.
고객 및 주문 레코드는 메모리에 저장되며 서비스가 재시작되면 초기화됩니다.
서비스는 인증 또는 권한 부여를 구현하지 않습니다.
취소 작업은 실제 시스템에서 승인 및 비즈니스 정책 제어로 보호되어야 합니다.
MCP는 로컬 프로세스 통합을 위해 stdio를 사용합니다. 배포 아키텍처에서는 인증된 네트워크 전송을 사용해야 합니다.
다운스트림 오류는 가시성을 위해 도구 텍스트로 반환됩니다. 프로덕션 시스템에서는 구조화된 오류, 재시도, 추적 및 메트릭을 사용해야 합니다.
샘플 에이전트는 실제 Gemini API 요청을 수행하며 유효한 키가 필요합니다.
GOOGLE_API_KEY is not set프로젝트 디렉터리에 .env가 존재하고 유효한 키가 포함되어 있는지 확인합니다. 프로젝트 디렉터리에서 에이전트를 실행합니다.
404 NOT_FOUND.env의 GEMINI_MODEL을 계정에서 활성화된 모델로 설정합니다. 이 POC의 기본값은 gemini-3.6-flash입니다.
활성 가상 환경에 종속성이 설치되었는지 확인합니다:
python -m pip install -r requirements.txt이 프로젝트는 서버 구현이 FastMCP를 사용하므로 MCP를 1.x API 범위로 고정합니다.
두 REST 서비스가 포트 8001 및 8002에서 실행 중인지 확인합니다. 포트가 이미 사용 중인 경우 서비스 포트와 .env의 해당 URL을 업데이트합니다.
This server cannot be deployed
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
