본문바로가기
Search MCP
AI Assistant OpenSearch Integration
Search MCP
AI Assistant OpenSearch Integration
Search MCP
Search MCP Server (자체개발)
Agent가 OpenSearch를 도구로 사용할 수 있게 하는 MCP 표준 서버
  • Python 3.10+
  • FastMCP
  • OpenSearch
  • MCP Protocol
  • stdio / Streamable HTTP
  • Tools / Resources / Prompts
  • Project
    Search MCP Server
  • Release Date
    2026.03
  • Type
    MCP Server / Developer Tool
  • Role
    Backend Development
분류
MCP Server / Developer Tool
기술스택
Python 3.10+, FastMCP, OpenSearch, MCP Protocol, stdio, Streamable HTTP
GitHub
https://github.com/joodb
담당업무
MCP Server 설계/개발, Transport 구현, OpenSearch 연동, 테스트
주요기능
MCP Tools/Resources/Prompts, OpenSearch 검색 연동, Dual Transport (stdio + Streamable HTTP)
컨셉
AI Assistant OpenSearch Integration via MCP
특징
MCP Primitives (Tools, Resources, Prompts), Dual Transport, Context Window 관리
제작기간
약 2주
제작단가
5000만원 초과
Search MCP Server - MCP Architecture & Transport
Problem
& Why MCP

AI 어시스턴트(Claude, Cursor 등)는 코드 작성에는 뛰어나지만, OpenSearch에 쌓인 사내 업무 데이터를 직접 검색할 수 없었습니다. 개발자가 매번 수동으로 쿼리를 작성하고 결과를 복사·붙여넣기해야 했습니다.

자체 REST API를 만들 수도 있었지만, MCP(Model Context Protocol)를 선택했습니다. MCP는 Anthropic이 제안한 개방형 표준으로, 한 번 구현하면 Claude Desktop·Cursor 등 다양한 AI 클라이언트가 별도 연동 없이 바로 사용할 수 있기 때문입니다.

Search MCP Server - MCP Primitives
Solution Design
& 3 Primitives

FastMCP 프레임워크로 OpenSearch 전용 MCP 서버를 구현하되, 3가지 Primitive를 역할별로 설계했습니다.

• Tools — AI가 직접 호출하는 검색 함수. "지난주 에러 로그 찾아줘" 같은 자연어 요청을 실제 OpenSearch 쿼리로 변환합니다.
• Resources — 클러스터 상태·인덱스 매핑 등 컨텍스트를 AI에게 노출. AI가 어떤 인덱스에 어떤 필드가 있는지 파악한 뒤 정확한 검색을 수행합니다.
• Prompts — 검색 쿼리 작성 가이드 템플릿. AI가 복잡한 집계·필터링도 일관된 품질로 수행하도록 유도합니다.

Challenge 1 | AI와 사내 데이터의 단절

상황: con03에서 설명한 대로, AI 어시스턴트가 사내 OpenSearch 데이터에 직접 접근할 수 없는 단절 문제가 있었습니다.

판단: 자체 API를 만들 수도 있었지만, MCP 표준을 따르면 Claude Desktop, Cursor 등 다양한 AI 클라이언트가 별도 연동 코드 없이 바로 사용할 수 있다고 판단했습니다.

액션: FastMCP로 OpenSearch 전용 MCP 서버를 구현했습니다. Tools로 검색 함수, Resources로 인덱스 구조 노출, Prompts로 쿼리 가이드를 등록하여, AI가 "어떤 데이터가 있는지 파악 → 적절한 쿼리 생성 → 검색 실행"까지 자율적으로 수행할 수 있게 설계했습니다.

결과: AI 어시스턴트가 자연어 요청을 받으면 MCP 서버를 통해 OpenSearch를 직접 조회합니다. 수동 쿼리 작성이 불필요해졌습니다.

Challenge 2 | 듀얼 트랜스포트 설계

상황: MCP 서버를 로컬 개발 환경(Claude Desktop, Cursor)과 원격 서비스(팀 공용 서버) 양쪽에서 사용해야 했습니다. 로컬은 프로세스 간 stdin/stdout 통신이 자연스럽고, 원격은 HTTP 기반 통신이 필수였습니다. 두 환경을 별도 서버로 만들면 유지보수가 이중으로 발생하는 문제가 있었습니다.

판단: 하나의 서버 코드베이스에서 stdio와 Streamable HTTP 두 가지 트랜스포트를 모두 지원하도록 설계하기로 했습니다. FastMCP가 듀얼 트랜스포트를 지원하므로, 실행 시 환경변수로 모드를 전환하는 방식을 채택했습니다.

액션: stdio 모드에서는 Claude Desktop·Cursor가 MCP 서버를 자식 프로세스로 실행하여 JSON-RPC 메시지를 교환하도록 구현했습니다. Streamable HTTP 모드에서는 단일 엔드포인트(/mcp)에서 POST 요청을 받고 SSE로 스트리밍 응답을 반환하도록 구현했습니다.

결과: 로컬 개발자는 Claude Desktop 설정에 경로만 추가하면 바로 사용 가능하고, 원격 팀원은 HTTP URL만 등록하면 동일한 검색 기능을 사용할 수 있습니다. 코드 중복 없이 두 환경을 하나의 서버로 커버합니다.

What I Learned | 프로젝트를 통해 배운 것

AI 도구 설계는 "AI가 어떻게 생각하는가"를 이해하는 일이었습니다. 단순히 검색 API를 노출하는 것과, AI가 스스로 판단하여 올바른 검색을 수행하도록 설계하는 것은 완전히 다른 문제였습니다. Tools만 등록하면 AI가 알아서 잘 쓸 것이라 생각했지만, 실제로는 Resources로 인덱스 구조를 알려주고, Prompts로 검색 패턴을 안내해야 비로소 정확한 결과가 나왔습니다.

MCP 표준의 힘을 체감했습니다. 자체 API를 만들었다면 각 AI 클라이언트마다 연동 코드를 작성해야 했을 것입니다. MCP 표준을 따른 덕분에 Claude Desktop, Cursor 등에서 설정 한 줄로 연결이 완료되었고, 새로운 MCP 호환 클라이언트가 등장하면 추가 작업 없이 바로 사용할 수 있습니다.

프로토콜 설계 역량이 성장했습니다. stdio와 Streamable HTTP라는 서로 다른 통신 방식을 하나의 서버에서 지원하면서, 전송 계층 추상화와 프로토콜 설계에 대한 실무 감각을 쌓을 수 있었습니다.

Back to Main
거인소프트 대표작을 만나보세요.