MCP 툴로 감싼 벡터 검색, 무엇이 달라지는가
에이전트가 벡터 데이터베이스를 SDK로 직접 호출하던 구조에서 MCP 서버가 사이를 가로막으면, 호출 형태는 tools/call 요청 하나로 단순해집니다. 다만 단순해지는 것은 인터페이스뿐이고 인덱스 쿼리 로직·필터 조합·오류 유형은 서버 쪽 스키마 설계로 옮겨갑니다. MCP 명세는 목록 조회에 tools/list, 실행에 tools/call 두 메시지만 규정하며 tools/list는 커서 기반 페이지네이션을 지원합니다. 검색 품질을 좌우하던 파라미터 튜닝은 이제 inputSchema 필드 설계 문제로 바뀝니다.
오류 처리 방식도 갈립니다. MCP는 알 수 없는 도구 이름 같은 프로토콜 오류와, 요청은 유효하지만 실행 중 실패한 도구 오류를 구분하며 후자는 결과 안에 isError: true로 담겨 돌아옵니다. 둘을 같은 재시도 정책으로 묶으면 정상 재시도 대상까지 즉시 중단되거나 영구 실패를 무한 재시도합니다.
Vectorize 한도가 툴 스키마 설계를 좌우하는 지점
Cloudflare Vectorize를 백엔드로 쓰면 쿼리 한도가 스키마 설계에 직접 영향을 줍니다. topK는 최대 100까지 허용되지만 returnValues나 returnMetadata: "all"을 함께 요청하면 50으로 제한되며, 2026년 3월 기존 20에서 상향된 값입니다. 메타데이터 필터는 인덱스당 최대 10개, 벡터 1건당 메타데이터 용량은 10KiB로 묶여 있어 필터 조건을 파라미터로 그대로 노출하면 없는 필터 키 요청이 조용히 무시되거나 인덱스 재설계 없이는 필터를 추가할 수 없습니다.
설계에서 운영까지: Vectorize MCP 툴 체크리스트
(a) 기획 단계에서는 목표 지표부터 숫자로 고정합니다. 툴 호출 p95 지연 800ms 이하, topK 기본값 10~20으로 응답 페이로드를 줄이고, 스키마 검증 실패율은 전체 호출의 1% 이내로 관리합니다. returnMetadata는 필요한 필드만 골라 반환해야 50개 상한을 피하면서 페이로드도 가볍게 유지됩니다.
스키마는 자유 텍스트 검색창을 그대로 옮기지 않습니다. 검색어, topK(서버가 50으로 clamp), 네임스페이스, 허용된 메타데이터 필터 키만 열거형으로 노출하고 returnValues·returnMetadata는 기본 false로 잠급니다. 단건 조회는 search 툴과 fetch-by-id 툴을 분리해 같은 한도 정책을 공유하지 않게 합니다.
흔한 실패는 네 갈래입니다. 첫째, 검색어를 자유 텍스트 하나로만 열어 두면 필터 없는 광역 쿼리가 그대로 임베딩돼 상한에 가까운 topK 요청이 반복됩니다. 둘째, returnMetadata: all이 기본값이면 topK 50 상한에 자주 걸려 응답이 예고 없이 잘립니다. 셋째, 메타데이터 인덱스 10개 한도를 계획 없이 소진하면 필터 하나 추가에도 인덱스 재생성이 필요합니다. 넷째, 프로토콜 오류와 도구 실행 오류를 구분하지 않으면 영구 오류에도 지수 백오프 재시도가 반복됩니다.
복구 분기는 오류 유형별로 나눕니다. isError: true 실행 오류는 지수 백오프로 최대 3회 재시도하고, 프로토콜 오류는 즉시 중단해 사람 확인으로 넘깁니다. 필터 없는 요청은 서버가 기본 네임스페이스로 안전 축약하고, topK 초과 요청은 거부 대신 상한값으로 clamp해 호출을 살립니다.
배포 전에는 빈 결과, 필터 키 오타, topK 100 요청, 메타데이터 10KiB 초과 삽입 같은 경계 시나리오를 툴 단위로 테스트합니다. 로그에는 도구 이름·쿼리 해시·적용 필터·topK·지연시간·isError 여부를 필수 필드로 남겨 어떤 조합이 상한에 부딪히는지 대시보드에서 바로 추적합니다. 메타데이터에 사용자 식별자나 이메일을 원문 저장하면 검색 결과에 PII가 노출되므로, 해시·참조 ID 치환 마스킹 단계를 인덱싱 파이프라인에 포함합니다.
매주 실패 상위 유형을 모아 어떤 필터 조합이 가장 자주 상한에 걸리는지 집계하고, 스키마 변경과 인덱스 데이터 갱신 이력을 분리해 남깁니다. 응답 품질이 떨어졌을 때 원인이 도구 정의 변경인지 임베딩 갱신인지 바로 구분돼 롤백 대상을 헤매지 않습니다.
실행 요약
검색을 MCP 툴 하나로 감싸는 순간 품질은 인덱스 알고리즘이 아니라 inputSchema와 한도 설계에서 갈립니다. topK clamp와 오류 유형 분리, 메타데이터 마스킹을 배포 전 체크리스트에 넣어두면 Vectorize 쪽 상한이 바뀌어도 도구 인터페이스는 흔들리지 않습니다.
참고 링크
Metadata filtering — Cloudflare Vectorize docs
Return up to 50 query results with values or metadata — Cloudflare changelog