pgvector를 MCP 서버로 노출하기: 하드코딩된 RAG에서 재사용 가능한 도구 서버로

FastMCP로 pgvector 검색을 감싸서 재사용 가능한 MCP 서버를 만드세요. 그러면 Claude Code를 포함한 모든 LLM 클라이언트가 하드코딩된 통합 없이도 사용자의 벡터 데이터베이스를 쿼리할 수 있습니다.

핵심 요약 (Key Takeaways)

• FastMCP로 pgvector 검색을 감싸서 재사용 가능한 MCP 서버를 만드세요.
• 그러면 Claude Code를 포함한 모든 LLM 클라이언트가 하드코딩된 통합 없이도 사용자의 벡터 데이터베이스를 쿼리할 수 있습니다.

무엇이 바뀌었나 — pgvector 검색이 MCP 서버가 되다

당신은 RAG (Retrieval-Augmented Generation) 시스템을 구축했습니다. 당신의 pgvector 데이터베이스는 임베딩 (embeddings)으로 가득 차 있습니다. 검색 함수는 완벽하게 작동하지만, 오직 당신의 Python 스크립트 내부에서만 작동합니다. 다른 어떤 도구도 이 함수에 접근할 수 없습니다.

MCP (Model Context Protocol)는 그 장벽을 허뭅니다. 단일 스크립트 내부에 search_documents()를 하드코딩하는 대신, 이를 모든 LLM 클라이언트가 연결할 수 있는 독립형 서버로 노출합니다. Claude Desktop, Claude Code, Gemini 에이전트, 또는 향후 등장할 모든 MCP 호환 클라이언트가 별도의 통합 작업 없이도 당신의 벡터 검색에 접근할 수 있게 됩니다.

본 원문 기사는 바로 이것을 구축하는 과정을 설명합니다. 즉, pgvector 기반의 검색 시스템을 가져와 FastMCP로 감싸는 것입니다. 그 결과, 어떤 MCP 클라이언트라도 발견하고 호출할 수 있는 재사용 가능한 도구 서버가 탄생합니다.

당신에게 미치는 의미 — Claude Code 사용에 미치는 구체적인 영향

만약 당신이 Claude Code를 사용한다면, 이는 즉시 유용하게 쓰일 수 있습니다. 다음과 같은 방식 대신 말이죠:

• 검색 결과를 Claude Code에 복사하여 붙여넣기
• 벡터 데이터베이스를 쿼리하기 위해 커스텀 스크립트 작성하기
• 각 도구마다 별도의 통합 기능을 유지 관리하기

당신은 단 하나의 MCP 서버만 실행하면 됩니다. Claude Code는 MCP 프로토콜을 통해 서버에 연결됩니다. 그러면 Claude Code에게 "트랜스포머 아키텍처(transformer architectures)에 관한 문서를 찾아줘"라고 요청할 수 있으며, Claude Code는 자동으로 당신의 pgvector 검색을 호출합니다.

이것이 바로 패턴입니다: 한 번 작성하여, 어디에서나 연결하기 (write once, connect everywhere).

지금 바로 시도해보세요 — 당신의 pgvector MCP 서버 구축하기

1. FastMCP 설치

pip install fastmcp
pip freeze > requirements.txt

2. 서버 생성 (mcp_server/server.py)

import psycopg2
from google import genai
from google.genai import types as genai_types
...

3. 서버 실행 및 Claude Code 연결

서버를 시작합니다:

python mcp_server/server.py

그 다음, Claude Code가 서버에 연결하도록 설정합니다. claude_desktop_config.json에 추가하거나 --mcp 플래그를 사용하세요:

{
  "mcpServers": {
    "pgvector-search": {
...

이제 Claude Code에서 "attention mechanisms(어텐션 메커니즘)에 관한 문서를 검색해줘"라고 요청하면, 자동으로 귀하의 pgvector MCP 서버를 호출합니다.

4. 리소스(Resources) 및 프롬프트(Prompts) 추가 (선택 사항)

리소스(Resources)는 LLM이 읽을 수 있는 데이터를 노출합니다. 프롬프트(Prompts)는 재사용 가능한 템플릿입니다:

@mcp.resource("db://categories")
def get_categories() -> str:
    cur.execute("SELECT DISTINCT category FROM documents ORDER BY category")
...

이것이 작동하는 이유 — 토큰 경제학(Token Economics)과 재사용성

핵심은 프로토콜(Protocol)에 있습니다. MCP는 도구(Tools)가 설명되고 호출되는 방식을 표준화합니다. FastMCP는 수동으로 FunctionDeclaration 블록을 작성할 필요 없이, Python의 타입 힌트(Type hints)와 독스트링(Docstrings)으로부터 스키마(Schema)를 자동으로 생성합니다. 이는 다음을 의미합니다:

• 스키마 유지보수 제로: 함수 시그니처(Function signature)를 변경하면 스키마가 자동으로 업데이트됩니다.
• 모든 클라이언트 지원: Claude Desktop, Claude Code, Gemini 또는 커스텀 에이전트 모두 MCP를 사용합니다.
• 코드 중복 없음: 하나의 서버로 여러 소비자(Consumers)를 지원합니다.

사용 시점

• 임베딩(Embeddings)이 포함된 pgvector 데이터베이스를 보유하고 있으며, Claude Code가 이를 쿼리하기를 원하는 경우
• 여러 에이전트나 도구가 접근해야 하는 RAG 시스템을 구축하는 경우
• 검색 로직을 애플리케이션 코드로부터 분리(Decouple)하고 싶은 경우
• MCP를 교육 중이며 구체적이고 작동하는 예시가 필요한 경우

더 큰 그림

이것은 클래식 소프트웨어 엔지니어링(Classic Software Engineering)에서 AI 엔지니어링(AI Engineering)으로 나아가는 여정의 시작입니다. 원문 기사의 저자는 Anthropic과 Hugging Face의 더 심화된 MCP 과정을 다루기 전, 워밍업 프로젝트로 이를 구축했습니다. 이 패턴은 확장 가능합니다. pgvector에서 모든 데이터 소스로, 하나의 클라이언트에서 여러 클라이언트로 확장될 수 있습니다.

이 패턴을 채택하는 Claude Code 사용자들은 일회성 스크립트를 작성하는 것을 멈추고 재사용 가능한 인프라를 구축하기 시작합니다. 여러분의 벡터 데이터베이스(Vector Database)는 스크립트 의존성이 아닌 하나의 서비스가 됩니다.

출처: dev.to

원문은 gentic.news에 게시되었습니다.