엔터프라이즈 지원 MCP 서버

경량 엔터프라이즈 AI 통합 프로토타입으로, **Model Context Protocol (MCP)**을 통해 비즈니스 기능을 대규모 언어 모델에 노출하는 방법을 보여줍니다.

이 프로젝트는 Python 기반 MCP 서버를 통해 고객 및 주문 정보를 제공합니다. Mistral 기반 AI 어시스턴트가 사용 가능한 MCP 도구를 동적으로 발견하고, 자연어 지원 요청에 따라 호출할 도구를 결정합니다.

더 복잡한 요청의 경우, 어시스턴트는 최종 응답을 생성하기에 충분한 정보가 확보될 때까지 여러 도구 호출을 반복적으로 실행할 수 있습니다.

이 프로젝트에서 사용된 모든 고객 및 주문 레코드는 합성 데모 데이터입니다.

주요 기능

• Model Context Protocol (MCP) 서버 및 클라이언트

• 동적 MCP 도구 발견

• Mistral AI를 사용한 LLM 기반 도구 선택

• 다단계 도구 호출 워크플로우

• 엔터프라이즈 데이터와의 자연어 상호작용

• 고객 및 주문 조회

• Pydantic 데이터 모델

• SQLite 영속성

• 구조화된 오류 처리

• MCP, 영속성, AI 통합 계층의 분리

Related MCP server: E-commerce MCP Server

아키텍처

flowchart TD
    U[User] --> L[Mistral LLM]
    L --> C[MCP Client]
    C --> S[Enterprise Support MCP Server]
    S --> D[(SQLite Customer / Order Database)]
    D --> S
    S --> C
    C --> L
    L --> U

LLM은 데이터베이스에 직접 접근하지 않습니다.

대신, 엔터프라이즈 기능은 표준화된 MCP 도구를 통해 노출됩니다. MCP 클라이언트는 이러한 도구를 동적으로 발견하고 해당 스키마를 LLM에 제공합니다.

그러면 LLM은 주어진 사용자 요청에 대해 어떤 도구가 필요한지 결정합니다.

예제 워크플로우

사용자가 입력:

Show me customer 1001.

애플리케이션은 다음 워크플로우를 수행합니다:

User request
    ↓
Mistral LLM
    ↓
Selects get_customer
    ↓
MCP Client
    ↓
Enterprise Support MCP Server
    ↓
SQLite
    ↓
Customer data
    ↓
MCP Client
    ↓
Mistral LLM
    ↓
Natural-language response

예제 결과:

Here is the information for customer 1001:

- Name: Anna Schmidt
- Email: anna@example.com
- Status: ACTIVE

애플리케이션 코드는 get_customer 선택을 하드코딩하지 않습니다. LLM은 사용자의 자연어 요청에 기반하여 적절한 MCP 도구를 선택합니다.

사용 가능한 MCP 도구

get_customer

고객 ID로 고객 정보를 검색합니다.

예제 입력:

{
  "customer_id": 1001
}

get_customer_orders

고객의 모든 주문을 검색합니다.

예제 입력:

{
  "customer_id": 1001
}

get_order_status

주문의 현재 상태 및 추적 정보를 검색합니다.

예제 입력:

{
  "order_id": 5002
}

기술 스택

• Python

• Model Context Protocol (MCP) Python SDK

• Mistral AI

• Pydantic

• SQLite

• asyncio

• python-dotenv

• uv

시작하기

사전 요구사항

이 프로젝트에는 다음이 필요합니다:

• Python 3.11+

• pip

• uv

• Mistral API 키

Python 설치 확인:

python --version

uv 확인:

uv --version

1. 저장소 클론

git clone https://github.com/YOUR-USERNAME/enterprise-support-mcp-server.git
cd enterprise-support-mcp-server

YOUR-USERNAME을 GitHub 사용자 이름으로 바꾸세요.

2. 가상 환경 생성

python -m venv .venv

Windows PowerShell

.venv\Scripts\Activate.ps1

Linux / macOS

source .venv/bin/activate

3. 의존성 설치

pip install -r requirements.txt

주요 의존성은 다음과 같습니다:

mcp[cli]
mistralai
pydantic
python-dotenv

4. Mistral API 키 구성

프로젝트 루트에 .env 파일을 생성하세요.

.env.example을 템플릿으로 사용할 수 있습니다:

MISTRAL_API_KEY=your_mistral_api_key

실제 .env 파일이나 API 키를 Git에 커밋하지 마세요.

5. 데모 데이터베이스 초기화

실행:

python init_db.py

이 명령은 MCP 도구에서 사용하는 합성 고객 및 주문 레코드가 포함된 로컬 SQLite 데이터베이스를 생성합니다.

테스트

이 프로젝트는 여러 수준에서 테스트할 수 있습니다.

테스트 1 – 데이터베이스 접근

MCP가 관여하기 전에 데이터베이스 함수를 독립적으로 테스트할 수 있습니다.

데모 데이터베이스가 초기화되었는지 확인:

python init_db.py

데이터베이스 계층은 다음 작업을 제공합니다:

get_customer
get_customer_orders
get_order_status

이를 통해 MCP 및 LLM과 독립적으로 영속성 계층을 검증합니다.

테스트 2 – MCP 서버 시작

실행:

python server.py

stdio 기반 MCP 서버의 경우, HTTP 포트나 브라우저가 열리지 않습니다.

프로세스는 표준 입력/출력을 통해 MCP 클라이언트가 통신할 때까지 대기합니다.

서버 중지:

Ctrl+C

테스트 3 – LLM 없는 MCP 클라이언트

실행:

python client.py

클라이언트가 MCP 서버에 연결하고 사용 가능한 도구를 발견합니다.

예상되는 도구 발견:

Available tools:
- get_customer
- get_customer_orders
- get_order_status

그런 다음 클라이언트는 MCP 도구를 직접 호출할 수 있습니다.

이 테스트는 다음을 확인합니다:

MCP Client
    ↓
MCP protocol
    ↓
MCP Server
    ↓
SQLite
    ↓
MCP result

이 테스트에는 대규모 언어 모델이 필요하지 않습니다.

테스트 4 – LLM 기반 MCP 도구 선택

실행:

python llm_client.py

애플리케이션은 먼저 서버에서 발견된 MCP 도구를 표시해야 합니다:

Available MCP tools:
- get_customer
- get_customer_orders
- get_order_status

그런 다음 자연어 요청을 입력할 수 있습니다.

고객 조회

Show me customer 1001.

예상 동작:

Mistral
    ↓
get_customer
    ↓
customer_id = 1001

최종 응답에는 고객 1001의 정보가 포함되어야 합니다.

고객 주문

다음 입력:

Show me all orders for customer 1001.

예상 도구:

get_customer_orders

주문 상태

다음 입력:

What is the status of order 5002?

예상 도구:

get_order_status

엔터프라이즈 데이터가 필요 없는 요청

다음 입력:

What can you help me with?

LLM은 고객 또는 주문 데이터에 접근하지 않고 이 요청에 응답할 수 있어야 합니다.

이는 모든 요청에 대해 도구 실행이 강제되는 것이 아니라 동적으로 선택됨을 보여줍니다.

테스트 5 – 다단계 도구 호출

LLM 클라이언트는 반복적인 도구 실행을 지원합니다.

다음과 같은 더 복잡한 요청을 시도해 보세요:

Customer 1001 says that one of her orders has not arrived.
Can you investigate?

복잡한 요청의 경우, 어시스턴트는 최종 응답을 생성하기 전에 여러 MCP 도구를 사용할 수 있습니다.

개념적으로:

User
    ↓
Mistral
    ↓
MCP Tool
    ↓
Tool Result
    ↓
Mistral
    ↓
Another tool required?
    ├── Yes → MCP Tool → Result → Mistral
    └── No  → Final Response

도구 호출 루프에는 우발적인 무한 실행을 방지하기 위한 최대 반복 횟수가 있습니다.

오류 처리 테스트

MCP 서버는 알 수 없는 비즈니스 엔터티도 처리합니다.

예를 들어:

Show me customer 9999.

해당 MCP 도구는 고객 정보를 임의로 생성하는 대신 오류 결과를 반환합니다.

이는 AI 기반 엔터프라이즈 통합에서 특히 중요합니다: 사실적인 고객 및 주문 정보는 LLM이 아닌 연결된 엔터프라이즈 시스템에서 와야 합니다.

프로젝트 구조

enterprise-support-mcp-server/
│
├── server.py
│   └── MCP server and tool definitions
│
├── client.py
│   └── MCP client for direct tool testing
│
├── llm_client.py
│   └── Mistral integration and agentic tool-calling workflow
│
├── database.py
│   └── Database access layer
│
├── models.py
│   └── Pydantic domain models
│
├── init_db.py
│   └── Creates synthetic demo data
│
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

왜 MCP인가?

LLM은 애플리케이션별 함수를 직접 호출할 수도 있습니다.

MCP는 AI 애플리케이션과 외부 기능 간의 표준화된 인터페이스를 도입합니다.

이 프로젝트에서:

Mistral
   ↓
Tool Calling
   ↓
MCP Client
   ↓
Standardized MCP interface
   ↓
Enterprise Support MCP Server
   ↓
Enterprise capabilities

LLM은 어떤 기능이 필요한지 결정하는 역할을 합니다.

MCP는 이러한 기능을 표준화된 프로토콜을 통해 노출하는 역할을 합니다.

이러한 분리를 통해 엔터프라이즈 백엔드는 특정 LLM 제공업체에 맞게 설계될 필요가 없습니다.

프로젝트 목적

이 프로젝트는 의도적으로 작게 유지되며 하나의 아키텍처 질문에 초점을 맞춥니다:

기존 엔터프라이즈 기능을 표준화된 통합 계층을 통해 AI 어시스턴트에 어떻게 제공할 수 있을까?

다음의 조합을 보여줍니다:

• 엔터프라이즈 시스템 통합

• Model Context Protocol

• LLM 도구 호출

• 에이전틱 워크플로우

• 구조화된 비즈니스 데이터

• 관심사 분리

이 프로젝트는 AI 어시스턴트를 기존 엔터프라이즈 애플리케이션에 통합하기 위한 실용적인 프로토타입 역할을 합니다.

보안 주의사항

이 저장소에는 합성 데모 데이터만 포함되어 있습니다.

API 키, 자격 증명, 고객 데이터 또는 기타 민감한 정보를 소스 코드나 커밋된 .env 파일을 통해 노출하지 마세요.