AI 도구 연결(MCP)

MCP는 AI 도구가 외부 서비스의 데이터를 조회하는 연결 방식입니다. Superfid를 MCP로 연결하면 AI 도구에서 위치, 재고현황, SKU별 변동 이력을 질문할 수 있습니다. 연결은 읽기 전용이며 재고를 변경하지 않습니다. 조회 범위에는 연결 계정의 워크스페이스·위치 권한이 그대로 적용됩니다.

연결 전 준비

• Superfid에 로그인할 수 있는 Google 계정을 준비합니다.
• 현재 로그인 방식에서는 계정에 활성 워크스페이스가 하나만 있어야 합니다. 여러 워크스페이스에 참여하고 있다면 관리자나 Superfid 지원팀에 연결 방법을 문의하세요.
• 사용하는 AI 도구에서 사용자 지정 MCP 연결을 추가할 수 있어야 합니다. 계정이나 조직 정책에 따라 관리자에게 연결 추가를 요청해야 할 수 있습니다.

ChatGPT·Claude에 연결

1. 사용하는 AI 도구의 사용자 지정 앱 또는 커넥터 추가 화면을 엽니다.
2. MCP 서버 주소에 아래 URL을 입력합니다.
3. 로그인 방식으로 OAuth를 선택하거나, 화면에서 안내하는 로그인 연결을 시작합니다.
4. Google 계정으로 로그인합니다. 패스키나 본인 확인을 요청하면 해당 인증을 완료합니다.
5. Superfid의 AI 도구 연결 승인 화면에서 요청한 도구와 조회 범위를 확인하고 연결 허용을 누릅니다. 연결하지 않으려면 취소를 누릅니다.
6. AI 도구로 돌아와 연결 완료 상태를 확인합니다. 대화에서 Superfid 연결을 활성화한 뒤 아래의 확인 질문을 입력합니다.

https://api.superfid.io/mcp

로그인 기반 연결에는 개발자 키를 붙여 넣을 필요가 없습니다. 연결 메뉴가 보이지 않으면 사용하는 AI 도구의 계정 권한과 조직 정책을 확인하세요.

Codex에서 연결

Codex CLI가 설치되어 있다면 다음 명령으로 운영 MCP 서버를 추가할 수 있습니다.

codex mcp add superfid --url https://api.superfid.io/mcp

인증 화면이 열리면 Google 로그인과 Superfid의 연결 허용까지 완료합니다. 이미 서버를 추가했거나 인증을 다시 시작할 때는 다음 명령을 실행합니다.

codex mcp login superfid

superfid는 이 예시에서 사용하는 연결 이름입니다. 다른 이름으로 추가했다면 로그인 명령에도 같은 이름을 사용하세요. 설정과 인증 방법은 Codex 공식 MCP 문서를 참고할 수 있습니다.

연결 결과 확인

먼저 “연결된 워크스페이스와 위치 목록을 보여줘”라고 요청하세요. 워크스페이스 이름과 위치·구역이 원하는 대상인지 확인한 뒤 재고를 조회합니다.

• Google 로그인 → Superfid 연결 허용 → AI 도구의 연결 완료 순서로 진행됩니다. 브라우저에 인증 완료 안내가 표시되면 AI 도구로 돌아갑니다.
• 재고 조회에서는 전체 SKU 수와 조회된 페이지의 항목 수가 다를 수 있습니다. 일부 결과만 보이면 다음 페이지를 요청하세요.
• SKU가 등록되어 있어도 현재 재고 합계는 0일 수 있습니다. 수량이 0인 조회 결과도 정상 응답입니다.

이렇게 질문해 보세요

• “연결된 워크스페이스와 위치 목록을 보여줘.”
• “시흥 센터에 재고가 있는 SKU를 찾아줘.”
• “이 SKU의 위치별 재고와 최근 변동 이력을 보여줘.”

답변의 워크스페이스와 조회 범위가 원하는 대상인지 확인하세요. 재고가 많으면 다음 페이지를 조회해 달라고 요청할 수 있습니다. 최신 스캔 반영이 끝나지 않은 재고는 SKU 재고 상세의 반영 상태도 함께 확인하세요.

제공하는 조회 도구

list_events는 이동 이벤트를, list_counts는 확정된 실사를 반환합니다. 두 결과는 업무 시각순이 아니라 cursor 기준으로 이어지며, cursor를 다음 요청에 그대로 전달해야 합니다. 이벤트의 SKU별 수량은 list_event_lines로 추가 조회할 수 있습니다.

연결·조회 문제 해결

• 워크스페이스 선택이 필요하다는 화면이 나옵니다: 연결 계정에 활성 워크스페이스가 정확히 하나인지 확인하세요. 현재 로그인 연결에서는 여러 워크스페이스 중 하나를 선택할 수 없습니다.
• 로그인이나 권한 승인이 실패합니다: 연결할 Google 계정과 워크스페이스 참여 상태를 확인한 뒤 다시 연결하세요.
• 로그인을 마쳤는데 연결이 완료되지 않거나 요청이 만료되었다고 나옵니다: AI 도구에서 인증을 다시 시작하고 새로 열린 승인 화면에서 연결 허용까지 진행하세요. Codex CLI에서는 codex mcp login superfid를 다시 실행합니다. 오래 열어 둔 승인 화면은 요청이 만료되었을 수 있습니다.
• 브라우저에는 인증 완료가 나오지만 AI 도구에 연결이 보이지 않습니다: AI 도구의 연결 상태를 확인하세요. 인증 대기 시간이 끝났다면 해당 도구에서 새 연결 요청을 시작합니다.
• 워크스페이스 이용이 정지되었다는 오류가 나옵니다: billing_access_restricted는 retryable: false인 오류입니다. 자동 재시도하지 말고 조직 관리자에게 대시보드 정산에서 정지 사유와 필요한 조치를 확인해 달라고 요청하세요. 이용 복구를 확인한 뒤 다시 조회합니다.
• 요청이 너무 많다는 오류가 나옵니다: 안내된 대기 시간 이후 다시 조회하세요. 같은 워크스페이스에서 실행하는 API 조회도 요청 제한에 영향을 줍니다.
• 결과가 너무 크다는 오류가 나옵니다: 재고·이력 조회의 위치 범위나 페이지 크기를 줄이세요. 위치 목록 등 범위를 줄일 수 없는 조회가 실패하면 Superfid 지원팀에 문의하세요.

직접 MCP 클라이언트를 연동하는 경우

직접 만드는 클라이언트에서는 워크스페이스 개발자 키로 인증할 수 있습니다. 다음 헤더를 사용하세요.

Authorization: Bearer <workspace-developer-key>
Accept: application/json, text/event-stream
Content-Type: application/json

URL의 token, access_token, api_key로는 인증할 수 없습니다. 키 원문과 전체 Authorization 헤더를 로그에 남기지 마세요.

로그인 기반 클라이언트를 구현하는 경우 OAuth 2.1 authorization code와 PKCE(S256)를 사용합니다. 인증 정보 검색 주소는 다음과 같습니다.

https://api.superfid.io/.well-known/oauth-protected-resource/mcp
https://api.superfid.io/.well-known/oauth-authorization-server

성공한 도구 응답에는 schemaVersion: "1"과 data가 포함됩니다. data의 필드는 해당 외부 REST API의 응답과 같습니다. 요청 본문은 64 KiB, 응답은 512 KiB로 제한됩니다. 결과는 JSON 구조와 text 설명에 함께 실려 실제 사용할 수 있는 데이터는 보통 190 KiB 이하입니다. 특수문자가 많으면 더 작아질 수 있으므로, 결과가 너무 크면 조회 범위나 limit을 줄이세요.

요청 횟수와 동시 실행 제한

인증된 MCP 요청은 모두 분당 제어 요청 제한을 적용받습니다. 데이터 조회에는 MCP 전용 제한과 일반 외부 API 제한이 함께 적용됩니다. 제한의 credential은 개발자 키 또는 OAuth 연결을 뜻합니다.

요청 횟수 제한은 분 단위로 계산합니다. 초과하면 오류의 retryAfterSeconds 또는 HTTP Retry-After만큼 기다린 뒤 다시 요청하세요. 동시 실행 제한과 일시적인 조회 장애도 재시도 가능 오류로 표시됩니다. 동시 제한은 API 인스턴스별 값이므로 서버 전체의 고정 동시 요청 수를 뜻하지 않습니다.

한 API 인스턴스에서 60초 동안 시간초과·조회 불가가 5회 발생하면 MCP 조회를 30초간 잠시 중단하고, 이후 한 건을 확인 요청으로 처리합니다. 계속 실패하면 연결 상태를 확인하고 잠시 뒤 다시 요청하세요.

도구 결과의 isError: true는 조회 실패를 뜻합니다. 오류의 retryable, retryAfterSeconds를 확인하고, 인증 실패나 잘못된 조회 조건은 수정한 뒤 다시 요청하세요.