MCP 시맨틱 도구 필터

MCP 시맨틱 도구 필터 (Semantic Tool Filter)

MCP 도구를 시맨틱 관련성에 따라 자동으로 필터링해요. 등록된 MCP 도구가 많을 때 LiteLLM이 사용자 쿼리를 도구 설명과 시맨틱 매칭해 가장 관련 있는 도구만 LLM에 보내요.

출처: 문서

본문

동작 방식 (How It Works)

도구 검색은 도구 선택을 프롬프트 엔지니어링 문제에서 검색(retrieval) 문제로 바꿔요. 모든 프롬프트에 큰 정적 도구 목록을 주입하는 대신, 시맨틱 필터가:

시작 시 모든 사용 가능한 MCP 도구의 시맨틱 인덱스를 구축
각 요청에서 사용자 쿼리를 도구 설명과 시맨틱 매칭
top-K 관련 도구만 LLM에 반환

이 접근 방식은 컨텍스트 효율을 높이고, 도구 혼동을 줄여 신뢰성을 높이며, 수백·수천 개의 MCP 도구가 있는 생태계로 확장할 수 있게 해줘요.

구성 (Configuration)

LiteLLM config에서 시맨틱 필터링을 활성화해 주세요:

config.yaml:

litellm_settings:
  mcp_semantic_tool_filter:
    enabled: true
    embedding_model: "text-embedding-3-small"  # Model for semantic matching
    top_k: 5                                    # Max tools to return
    similarity_threshold: 0.3                   # Min similarity score

구성 옵션 (Configuration Options):

enabled — 시맨틱 필터링 활성/비활성(기본값: false)
embedding_model — 임베딩 생성용 모델(기본값: "text-embedding-3-small")
top_k — 반환할 최대 도구 수(기본값: 10)
similarity_threshold — 매칭의 최소 유사도 점수(기본값: 0.3)

사용법 (Usage)

MCP 도구를 Responses API 또는 Chat Completions와 함께 평소처럼 사용하세요. 시맨틱 필터는 자동으로 실행돼요.

Responses API:

curl --location 'http://localhost:4000/v1/responses' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
    "model": "gpt-5.6-terra",
    "input": [
    {
      "role": "user",
      "content": "give me TLDR of what BerriAI/litellm repo is about",
      "type": "message"
    }
  ],
    "tools": [
        {
            "type": "mcp",
            "server_url": "litellm_proxy",
            "require_approval": "never"
        }
    ],
    "tool_choice": "required"
}'

Chat Completions:

curl --location 'http://localhost:4000/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ***" \
--data '{
  "model": "gpt-5.6-terra",
  "messages": [
    {"role": "user", "content": "Search Wikipedia for LiteLLM"}
  ],
  "tools": [
    {
      "type": "mcp",
      "server_url": "litellm_proxy"
    }
  ]
}'

응답 헤더 (Response Headers)

시맨틱 필터는 모든 응답에 진단 헤더를 추가해요:

x-litellm-semantic-filter: 10->3
x-litellm-semantic-filter-tools: wikipedia-fetch,github-search,slack-post

x-litellm-semantic-filter — 이전→이후 도구 수 표시(예: 10->3은 10개 도구가 3개로 필터링됨을 의미)
x-litellm-semantic-filter-tools — 필터링된 도구 이름의 CSV 목록(최대 150자, 더 길면 ...으로 잘림)

이 헤더들은 각 요청에서 어떤 도구가 선택되었는지 이해하고 필터가 올바르게 작동하는지 확인하는 데 도움을 줘요.

예시 (Example)

50개의 MCP 도구가 등록되어 있고 Wikipedia에 대해 묻는 요청을 한다면, 시맨틱 필터는:

쿼리 "Search Wikipedia for LiteLLM"를 50개 도구 설명과 시맨틱 매칭
가장 관련 있는 상위 5개 도구 선택(예: wikipedia-fetch, wikipedia-search 등)
그 5개 도구만 LLM에 전달
x-litellm-semantic-filter: 50->5를 보여주는 헤더 추가

이렇게 하면 LLM이 작업에 필요한 올바른 도구에 접근할 수 있도록 보장하면서 프롬프트 크기가 크게 줄어들어요.

성능 (Performance)

시맨틱 필터는 프로덕션에 최적화되어 있어요:

라우터는 시작 시 한 번만 구축(요청별 오버헤드 없음)
시맨틱 매칭은 보통 50ms 미만
우아하게 실패 — 필터링 실패 시 모든 도구 반환
MCP 도구가 없는 요청의 지연 시간에는 영향 없음

MCP 개요 — LiteLLM의 MCP 알아보기
MCP 권한 관리 — 키/팀별 도구 접근 제어
MCP 사용 — 전체 MCP 사용 가이드

더 알아보기 (Learn more)

MCP 개요 — LiteLLM의 MCP 아키텍처
MCP 권한 관리 — 도구 별 접근 제어

MCP 시맨틱 도구 필터