인증 및 권한
큐넥터 MCP는 OAuth 2.0 Device Authorization Grant를 기본으로 합니다. 스코프는 REST API와 1:1로 매핑됩니다.
OAuth Device Flow
stdio MCP 서버는 Device Authorization Grant로 access·refresh 토큰을 발급합니다. 최초 도구 호출 또는 qnector_login 시 브라우저에 인증 URL과 user_code가 표시됩니다.
- Hosted MCP: Authorization Code + PKCE (/oauth/mcp/authorize) + Dynamic Client Registration
- stdio: Device Flow (client_id: qnector-mcp-cli)
- 토큰 타입: Bearer (access: qnx_at_* 형태)
- refresh: offline_access 스코프 동의 시 발급
스코프
기본 동의(최소): mcp:products:read, mcp:warehouses:read, mcp:inventory:read, offline_access. 주문·정산·견적·문의·공지·구매자·등급·단가·카탈로그·링크열람은 consent에서 추가 체크합니다. 쓰기 스코프는 아직 consent에 노출하지 않습니다.
mcp:products:read
qnector_product_* ↔ products:read
mcp:warehouses:read
qnector_warehouse_* ↔ warehouses:read
mcp:inventory:read
qnector_inventory_* ↔ inventory:read
mcp:orders:read
qnector_order_* ↔ orders:read
mcp:settlements:read
qnector_settlement_* ↔ settlements:read
mcp:quotes:read
qnector_quote_* ↔ quotes:read
mcp:inquiries:read
qnector_inquiry_list ↔ inquiries:read
mcp:notices:read
qnector_notice_list ↔ notices:read
mcp:buyers:read
qnector_buyer_* ↔ buyers:read
mcp:buyer-tiers:read
qnector_buyer_tier_list ↔ buyer-tiers:read
mcp:prices:read
qnector_price_* ↔ prices:read
mcp:catalogs:read
qnector_catalog_* ↔ catalogs:read
mcp:link-leads:read
qnector_link_lead_* ↔ link-leads:read (유료)
offline_access
refresh_token 발급
토큰 저장
- 경로: ~/.qnector/credentials.json (권한 Unix 0600)
- 내용: access_token, refresh_token, expires_at, seller_id, scopes, role
- QNECTOR_CREDENTIALS_PATH로 저장 경로를 바꿀 수 있습니다.
- user + client + role당 활성 refresh는 기기별 상한(기본 3개)이 있습니다.
API 키(대안)
서버·CI처럼 OAuth를 쓸 수 없는 환경만 v18 API 키를 허용합니다. QNECTOR_API_KEY=qnx_live_* 를 env에 명시하면 OAuth를 건너뜁니다.
- 일반 사용자 경로에는 API 키를 mcp.json 예시에 넣지 않습니다.
- 대시보드 API 연동 탭의 키는 ERP/WMS·CI용으로 안내합니다.
인증 오류
oauth_expired
access/refresh 만료 — 재로그인
oauth_insufficient_scope
툴 요구 스코프 부족 — consent에서 추가 동의
api_access_denied
플랜·권한 없음 또는 연결 해제
consent_required
추가 스코프·역할 동의 필요