응답 형식

MCP 도구 응답은 ok, tool, api_version, data, summary, meta를 포함합니다. summary는 IDE 채팅 표시용으로 항상 포함됩니다.

성공 응답

summary는 항상 포함되며, IDE 채팅에 바로 표시할 수 있는 한국어 한 줄입니다. data는 구조화 JSON, meta는 페이지네이션 등 부가 정보입니다.

json

{
  "ok": true,
  "tool": "qnector_product_search",
  "api_version": "2026-06-26",
  "data": {
    "matches": [
      {
        "id": "product-uuid",
        "prod_code": "SKU-001",
        "prod_name": "사과 5kg",
        "price": 15000,
        "quantity": 120
      }
    ]
  },
  "summary": "품목 1건: SKU-001 사과 5kg",
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

오류 응답

실패 시 ok: false와 code, message를 반환합니다. 레이트 리밋 시 retry_after가 포함될 수 있습니다.

구분설명

oauth_expired

토큰 만료 — qnector_login 재실행

oauth_insufficient_scope

스코프 부족

api_access_denied

플랜·권한 없음

result_set_too_large

목록 결과가 너무 큼 — page/limit·필터 축소 (REST와 동일)

rate_limit_exceeded

분당 한도 초과 — retry_after 후 재시도

json

{
  "ok": false,
  "code": "oauth_insufficient_scope",
  "message": "이 도구에 필요한 스코프가 없습니다. mcp:products:read 동의가 필요합니다."
}

호출량·안전

레이트 리밋은 seller 버킷으로 OAuth·API 키가 동일합니다.
_summary 계열은 내부 REST를 여러 번 호출해도 MCP 1회로 카운트합니다.
쓰기 도구는 confirm: true 없으면 dry-run만 수행합니다.
감사 로그에 source: mcp, oauth_client_id가 기록됩니다.