MCP REST API

MCP REST API

MCP 도구를 HTTP로 직접 호출하는 가이드예요. 어떤 도구를 실행할지 이미 알고 있을 때 사용하세요. LLM 주도 도구 사용은 Using your MCP를 참고해 주세요.

기본 URL: http://localhost:4000(LiteLLM 프록시 URL로 교체)

인증: 매 요청에 LiteLLM API 키:

-H "Authorization: Bearer ***"
# or
-H "x-litellm-api-key: sk-<yo...ey>"

출처: 문서

본문

엔드포인트 (Endpoints)

메서드 경로 용도
GET /v1/mcp/server MCP 서버 목록(server_id / server_name 가져오기)
GET /mcp-rest/tools/list 도구 목록(모든 서버 또는 한 서버)
POST /mcp-rest/tools/call 도구 실행

이 경로들은 Claude Desktop과 Cursor가 사용하는 /mcp 또는 /{server_name}/mcp의 JSON-RPC MCP 전송과는 별개예요. 전체 엔드포인트 결정 매트릭스는 MCP Configuration Reference를 참고해 주세요.

도구 명명 (Tool naming)

LiteLLM은 여러 MCP 서버의 도구를 등록해요. 요청의 도구 이름은 두 패턴 중 하나를 따릅니다:

패턴 사용 시점 예시
접두사(Prefixed) 전역 도구 목록 또는 자족적 도구 id places_api-getPlaces
비접두사 + server_id (Unprefixed +server_id) 서버별 도구 목록 server_id: places_api, name: getPlaces

접두사 형식: {server_prefix}{separator}{upstream_tool_name}

  • 기본 구분자(separator) 는 -(하이픈).
  • 프록시에서 환경 변수 MCP_TOOL_PREFIX_SEPARATOR로 재정의.
  • LITELLM_USE_SHORT_MCP_TOOL_PREFIX=true이면 접두사가 서버 이름 대신 3자 id(같은 {prefix}{separator}{tool} 모양).

프록시는 업스트림 MCP 서버를 비접두사 도구 이름(예: getPlaces)으로 호출하며, 전체 접두사 문자열이 아니라요.

1. MCP 서버 목록 (List MCP servers)

curl -s http://localhost:4000/v1/mcp/server \
  -H "Authorization: Bearer ***" | jq .

응답의 server_id 또는 server_name을 이후 호출에서 사용하세요. 둘 다 /mcp-rest/*에서 server_id로 작동해요.

2. 도구 목록 (List tools)

모든 서버 (All servers)

curl -s http://localhost:4000/mcp-rest/tools/list \
  -H "Authorization: Bearer ***" | jq .

도구 name 값은 종종 비접두사(예: getPlaces)이고 mcp_info.server_name이 서버를 나타내요. tools/call에는 다음 중 하나를 사용하세요:

  • 접두사 name: places_api-getPlaces, 또는
  • 비접두사 name + server_id: getPlaces + places_api.

server_id는 UUID, server_name, 별칭을 받아요.

curl -s "http://localhost:4000/mcp-rest/tools/list?server_id=places_api" \
  -H "Authorization: Bearer ***" | jq .

비접두사 업스트림 이름(예: getPlaces, ping)을 반환해요.

3. 도구 호출 (Call a tool)

요청 본문 (Request body)

필드 필수 타입 설명
server_id 예 string UUID, server_name, 또는 별칭
name 예 string 접두사 또는 비접두사 도구 이름(위 참고)
arguments 권장 object 도구 파라미터. 없으면 {} 사용. 생략하면 프록시가 {}로 취급. null은 전달하지 마세요.

선택적 JSON-RPC 필드(jsonrpc, method, id)는 REST 핸들러가 무시해요. 클라이언트 호환성 때문에 포함해도 됩니다.

작동: 접두사 이름 + 서버 UUID

curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "17a4490465f74d3696caf12b30220166",
    "name": "places_api-getPlaces",
    "arguments": {}
  }' | jq .

작동: 비접두사 이름 + 서버 이름

curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "places_api",
    "name": "getPlaces",
    "arguments": { "query": "coffee" }
  }' | jq .

작동: x-litellm-api-key 헤더

curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "x-litellm-api-key: sk-<yo...ey>" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "order_status_mcp",
    "name": "order_status_mcp-order_status",
    "arguments": { "orderId": "ord1234" }
  }' | jq .

작동하지 않는 것 (What does not work)

server_id 누락

# 400 missing_parameter
curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{ "name": "places_api-getPlaces", "arguments": {} }'

arguments: null

# 500 — arguments must be a JSON object, not null
curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "places_api",
    "name": "places_api-getPlaces",
    "arguments": null
  }'

수정: "arguments": {}를 사용하거나 필드를 아예 생략하세요.

도구 이름의 잘못된 구분자(하이픈 대신 밑줄)

기본 구분자는 _가 아니라 -예요.

# Tool not found or wrong routing
curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "places_api",
    "name": "places_api_getPlaces",
    "arguments": {}
  }'

수정: places_api-getPlaces를 사용하거나 MCP_TOOL_PREFIX_SEPARATOR를 명명 규칙에 맞게 설정하세요.

도구가 server_id와 다른 서버에 속함

# 403 tool_server_mismatch
curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "order_status_mcp",
    "name": "places_api-getPlaces",
    "arguments": {}
  }'

응답:

{
  "detail": {
    "error": "tool_server_mismatch",
    "message": "Tool 'places_api-getPlaces' belongs to MCP server 'places_api' but request specified server_id for 'order_status_mcp'."
  }
}

잘못되었거나 알 수 없는 server_id

# 404 server_not_found (unknown name/uuid)
curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "serverid1",
    "name": "some-tool",
    "arguments": {}
  }'

# 403 access_denied (server exists but key cannot access it)

고객 예시의 플레이스홀더 서버 id

"serverid1" / "serverid2" 같은 문자열은 정확히 그 id로 서버를 만들지 않았다면 유효하지 않아요. GET /v1/mcp/server를 실행해 실제 server_id를 복사하거나 server_name을 사용하세요.

빠른 참조 (Quick reference)

# All servers
curl -s http://localhost:4000/mcp-rest/tools/list \
  -H "Authorization: Bearer ***"

# One server
curl -s "http://localhost:4000/mcp-rest/tools/list?server_id=MY_SERVER" \
  -H "Authorization: Bearer ***"

curl -s -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "MY_SERVER",
    "name": "MY_SERVER-tool_name",
    "arguments": {}
  }'

더 알아보기 (Learn more)