.NET을 사용하여 첫 번째 MCP 서버 구축 | Niraj Ranasinghe

프로그래밍 언어 C# / .NET
, ,
1

.NET으로 첫 번째 MCP 서버 구축하기

개요

본 문서는 .NET을 사용하여 MCP(Model Context Protocol) 서버를 구축하는 방법에 대한 상세한 가이드입니다. MCP는 AI 모델과 다양한 시스템 간의 통신을 표준화하는 프로토콜로, Claude와 같은 AI가 데이터베이스, API, 파일 등에 직접 접근할 수 있게 해줍니다.

MCP(Model Context Protocol)란 무엇인가?

핵심 개념

  • 정의: Model Context Protocol의 약자로, AI 모델과 외부 시스템 간의 표준화된 통신 프로토콜
  • 목적: AI 모델이 데이터베이스, API, 파일, 비즈니스 로직 등에 실시간으로 접근할 수 있도록 하는 것
  • 기반 기술: JSON-RPC를 기반으로 한 메시지 교환 방식

MCP가 해결하는 문제점

기존의 AI 상호작용 방식의 한계:

  1. 데이터 복사-붙여넣기의 번거로움
  2. 각 사용 사례별 개별 통합 구축의 시간 소모
  3. 임시방편적 해결책의 불안정성

MCP의 작동 원리

Claude ←→ MCP Server ←→ 데이터베이스/API/파일/시스템

단계별 프로세스:

  1. MCP 서버 구축 및 기능 정의
  2. 서버가 제공 가능한 기능들을 Claude에게 알림
  3. Claude가 서버에 연결하여 사용 가능한 기능 탐색
  4. Claude가 필요에 따라 해당 기능들을 실시간으로 활용

MCP의 핵심 구성 요소

1. Tools (도구)

  • 설명: Claude가 호출할 수 있는 함수들
  • 예시: 이메일 전송, 캘린더 이벤트 생성, 앱 배포 등
  • 특징: 매개변수를 받아서 결과를 반환

2. Resources (리소스)

  • 설명: Claude가 읽을 수 있는 데이터 소스
  • 예시: 작업 목록, 일일 매출 수치 등
  • 특징: URL과 유사하지만 커스텀 데이터용

3. Prompts (프롬프트)

  • 설명: 미리 구축된 프롬프트 템플릿
  • 용도: 특정 워크플로우를 위한 재사용 가능한 프롬프트
  • 특징: 덜 일반적이지만 특정 상황에서 유용

기술적 배경

통신 방식 (Transport)

  1. stdio: 표준 입출력을 통한 통신 (가장 간단한 설정)
  2. HTTP: 웹 서비스 형태로 서버 운영
  3. WebSockets: 실시간 통신이 필요한 경우

서버 생명주기

  1. 초기화: 서버 시작 및 기능 설정
  2. 핸드셰이크: Claude와의 연결 및 정보 교환
  3. 탐색: Claude가 사용 가능한 도구와 리소스 확인
  4. 운영: Claude가 필요에 따라 도구와 리소스 활용
  5. 종료: 깔끔한 연결 해제

MCP의 주요 장점

1. 실시간 데이터 접근

  • 오래된 데이터가 아닌 최신 정보를 실시간으로 제공
  • 시스템에서 직접 데이터를 가져와 정확성 보장

2. 사용자 제어 보안

  • 읽기 전용 또는 쓰기 권한 제어 가능
  • 특정 테이블이나 기능에 대한 접근 제한 설정

3. 하나의 서버, 다중 클라이언트

  • 단일 MCP 서버로 여러 MCP 호환 클라이언트 지원
  • 현재는 주로 Claude에서 사용되지만 생태계 확장 중

4. 표준화된 인터페이스

  • 각 AI 통합별 개별 API 구축 불필요
  • 하나의 MCP 서버로 모든 통합 처리

실습: 직원 관리 MCP 서버 구축

프로젝트 설정

dotnet new console -n EmployeeMcpServer
cd EmployeeMcpServer
dotnet add package ModelContextProtocol.Server

메인 프로그램 구조

Program.cs의 핵심 특징:

  • 간단한 설정: SDK가 JSON-RPC 프로토콜, 탐색, 스키마 생성을 자동 처리
  • 자동 도구 탐색: WithToolsFromAssembly()로 어셈블리에서 도구 자동 발견
  • 표준 입출력 통신: WithStdioServerTransport()로 간단한 통신 설정

직원 관리 도구 클래스

주요 기능들

  1. GetEmployees(): 모든 직원 기록 조회
  2. GetEmployeeById(): 특정 직원 ID로 조회
  3. AddEmployee(): 새 직원 추가
  4. UpdateEmployee(): 기존 직원 정보 수정
  5. DeleteEmployee(): 직원 삭제
  6. GetEmployeesByDepartment(): 부서별 직원 조회
  7. GetEmployeesByStatus(): 상태별 직원 조회
  8. GetDepartmentCounts(): 부서별 직원 수 통계

구현의 핵심 특징

1. 어트리뷰트 시스템
  • [McpServerToolType]: 클래스가 MCP 도구를 포함함을 표시
  • [McpServerTool]: 메서드를 호출 가능한 도구로 표시
  • [Description]: Claude가 볼 수 있는 도구 설명 제공
2. 자동 스키마 생성
  • SDK가 모든 도구를 자동으로 탐색하여 JSON 스키마 생성
  • Claude가 각 도구의 매개변수와 기능을 정확히 파악 가능
3. 타입 안전성
  • decimal 타입으로 급여 처리
  • DateTime 타입으로 입사일 처리
  • SDK가 JSON과 C# 타입 간 변환 자동 처리
4. 간단한 반환값
  • 각 도구는 문자열을 반환
  • SDK가 적절한 MCP 응답으로 패키징
5. 유효성 검사
  • 각 메서드에서 기본적인 유효성 검사 수행
  • 오류 시 의미 있는 오류 메시지 반환

직원 데이터 모델

private class Employee
{
    public string Name { get; set; }
    public string Role { get; set; }
    public string Department { get; set; }
    public string Email { get; set; }
    public DateTime HireDate { get; set; }
    public decimal Salary { get; set; }
    public string Status { get; set; }
    public string Phone { get; set; }
    public string Address { get; set; }
}

Claude Desktop과의 연동 설정

설정 파일 위치

  • Windows: %APPDATA%/Claude/claude_desktop_config.json

설정 예시

{
  "mcpServers": {    
    "EmployeeMCPServer": {
      "command": "dotnet",
      "args": [
        "run", 
        "--project", 
        "C:\\Users\\Niraj\\MCP\\EmployeeMCP\\EmployeeMCP.csproj",
        "--no-build"
      ]
    }
  }
}

사용 방법

  1. Claude Desktop 재시작
  2. 연결 시 해머 아이콘 확인
  3. 자연어로 직원 관리 명령 입력

실제 사용 사례

기본 명령어 예시

  • 직원 추가: “Engineering 부서에 Software Engineer로 Niraj라는 새 직원을 추가해줘”
  • 부서별 조회: “Marketing 부서의 모든 직원을 보여줘”
  • 정보 수정: “EMP001 직원의 급여를 $195,000로 업데이트해줘”
  • 통계 조회: “각 부서별 직원 수는 얼마나 되나요?”

Claude의 지능적 처리

  • 도구 간 관계 이해: 복잡한 작업을 위해 여러 도구를 조합하여 사용
  • 매개변수 자동 추출: 자연어에서 필요한 매개변수를 자동으로 식별
  • 오류 처리: 유효성 검사 오류 시 적절한 사용자 피드백 제공

확장 가능성과 활용 아이디어

데이터베이스 통합

  • Entity Framework 연동: 메모리 딕셔너리를 실제 데이터베이스로 교체
  • 대용량 데이터 처리: 수천 명의 직원 기록 관리 가능

파일 처리 기능

  • CSV/Excel 내보내기: 요청 시 직원 데이터 보고서 생성
  • 자동 보고서: Claude가 필요에 따라 다양한 형식의 보고서 생성

이메일 통합

  • 신입사원 환영 이메일: 자동 발송 기능
  • 상태 변경 알림: 직원 상태 변경 시 관련자에게 자동 통지

캘린더 연동

  • 일정 관리: 직원 스케줄, 휴가 관리
  • 회의 설정: API를 통한 자동 회의 일정 조율

고급 보고 기능

  • HR 분석: 인사 관련 고급 통계 및 분석
  • 급여 분석: 부서별, 직급별 급여 통계
  • 성과 지표: 다양한 HR 메트릭 추적

승인 워크플로우

  • 급여 변경 승인: 특정 금액 이상의 급여 변경 시 승인 절차
  • 퇴사 처리: 여러 단계의 승인이 필요한 중요 작업 관리

다른 활용 사례

프로젝트 관리 도구

  • 작업 할당 및 추적
  • 프로젝트 진행 상황 모니터링
  • 팀 협업 지원

고객 데이터 시스템

  • 고객 정보 관리
  • 상호작용 이력 추적
  • 맞춤형 서비스 제공

파일 조직 시스템

  • 자동 파일 분류
  • 문서 검색 및 관리
  • 백업 및 아카이빙

배포 자동화 도구

  • 자동 배포 프로세스
  • 환경 관리
  • 모니터링 및 로깅

주요 학습 포인트

MCP 서버 개발의 핵심 패턴

  1. 클래스 생성: MCP 도구를 포함할 클래스 작성
  2. 어트리뷰트 적용: 적절한 MCP 어트리뷰트로 마킹
  3. 메서드 구현: 비즈니스 로직을 포함한 메서드 작성
  4. Claude 연동: 설정 파일을 통한 Claude와의 연결

성공적인 MCP 서버의 특징

  • 명확한 도구 설명: Claude가 이해하기 쉬운 설명 제공
  • 적절한 유효성 검사: 오류 상황에 대한 명확한 처리
  • 타입 안전성: 강력한 타입 시스템 활용
  • 사용자 친화적: 자연어 명령에 대한 직관적인 응답

실용적인 팁

개발 시 고려사항

  • 간단한 시작: 기본 기능부터 구현하여 점진적으로 확장
  • 테스트 중심: 각 도구를 개별적으로 테스트하여 안정성 확보
  • 문서화: Description 어트리뷰트를 활용한 충분한 문서화
  • 오류 처리: 예외 상황에 대한 명확하고 도움이 되는 메시지 제공

성능 최적화

  • 메모리 관리: 대용량 데이터 처리 시 적절한 메모리 관리
  • 비동기 처리: Task 기반 비동기 패턴 활용
  • 캐싱: 자주 사용되는 데이터에 대한 적절한 캐싱 전략

보안 주의사항

  • 입력 검증: 모든 사용자 입력에 대한 철저한 검증
  • 권한 제어: 민감한 작업에 대한 적절한 권한 관리
  • 로깅: 중요한 작업에 대한 적절한 로깅 및 감사

참고 자료

공식 문서

  • ModelContextProtocol.Server NuGet 패키지
  • .NET 콘솔 애플리케이션 개발 가이드

개발 도구

  • Visual Studio 또는 VS Code
  • .NET SDK
  • Claude Desktop 애플리케이션

추가 학습 방향

  • JSON-RPC 프로토콜 이해
  • Entity Framework를 활용한 데이터베이스 연동
  • RESTful API 설계 원칙
  • 비동기 프로그래밍 패턴
2개의 좋아요