Superfid Docs

Superfid workspace read API를 MCP 클라이언트에 연결하는 운영 계약입니다.

운영 MCP와 hosted OAuth가 배포되어 있습니다. 아래 production 주소를 ChatGPT remote app 또는 Claude Custom Connector에 등록해 연결할 수 있습니다.

Superfid MCP는 읽기 전용 연결입니다. ChatGPT remote app과 Claude Custom Connector처럼 로그인 기반 클라이언트는 Superfid OAuth로 연결하고, 직접 API client를 만들 때는 workspace developer key를 사용합니다.

OAuth는 Superfid API가 authorization server로 동작하는 표준 OAuth 2.1 authorization code + PKCE(S256) 흐름입니다. ChatGPT·Claude에는 developer key를 붙여 넣지 않습니다. 클라이언트가 /mcp에서 받은 protected-resource metadata와 authorization-server metadata를 따라 Google 로그인·동의·토큰 발급을 진행합니다.

제공 도구

get_workspace — 연결된 workspace와 read scope 확인
list_locations — 위치·section 목록 조회
search_inventory — 재고현황 검색 및 cursor 페이지네이션
get_inventory_status — SKU별 위치 재고 상세 조회
get_inventory_history — SKU 변동 이력 및 cursor 페이지네이션

모든 도구는 read-only입니다. MCP 도구는 기존 외부 REST API와 동일한 응답 DTO를 반환하며, 성공 결과에는 schemaVersion: "1"이 포함됩니다.

운영 서버 주소

운영 MCP 주소는 다음과 같습니다.

https://api.superfid.io/mcp

OAuth discovery 주소는 다음과 같습니다.

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

운영 readiness 확인 시 MCP OAuth discovery metadata와 인증되지 않은 요청의 protected-resource challenge가 정상 응답되어야 합니다.

운영자 사전 준비

운영 서버는 OAuth dynamic client registration(DCR)을 활성화한 상태입니다. 클라이언트가 DCR을 지원하면 discovery metadata를 따라 자동 등록하고, 그렇지 않으면 해당 클라이언트의 사전 등록 절차를 사용합니다. 운영자는 다음을 확인해야 합니다.

MCP client가 https://api.superfid.io/mcp에 접근할 수 있는지 확인합니다.
OAuth 요청에서 workspace:read만 요청되는지 확인합니다. 쓰기 scope는 제공하지 않습니다.
연결할 Superfid 계정에 활성 workspace가 정확히 하나 있는지 확인합니다.
실제 ChatGPT·Claude 계정으로 로그인, 동의, 도구 호출을 확인합니다.

운영 서버 설정

MCP는 다음 설정이 모두 준비된 경우에만 켭니다.

SUPERFID_MCP_ENABLED=true
SUPERFID_MCP_PUBLIC_URL=https://api.superfid.io/mcp
SUPERFID_MCP_ALLOWED_HOSTS=api.superfid.io
SUPERFID_MCP_ALLOWED_ORIGINS=https://<approved-client-origin>
SUPERFID_MCP_OAUTH_ENABLED=true
SUPERFID_MCP_OAUTH_DCR_ENABLED=true
SUPERFID_MCP_LOGIN_URL=https://api.superfid.io/mcp/login
SUPERFID_MCP_RESOURCE_URL=https://api.superfid.io/mcp

SUPERFID_MCP_PUBLIC_URL은 절대 URL이어야 하고 경로는 /mcp여야 합니다. 허용 origin은 정확한 origin 목록이며 *와 null은 사용할 수 없습니다. 설정이 잘못되면 서버가 시작되지 않습니다.

ChatGPT에서 연결해 보기

ChatGPT에서 Settings → Apps/Connectors → Developer mode를 엽니다. 계정·조직 정책에 따라 이 메뉴가 보이지 않을 수 있습니다.
Custom app을 만들고 MCP server URL에 https://api.superfid.io/mcp를 입력합니다.
도구 목록을 확인하고 OAuth 연결을 시작합니다. 브라우저가 Superfid Google 로그인으로 이동하면 로그인·승인합니다.
새 대화에서 해당 앱을 활성화한 뒤 “연결된 workspace의 위치와 재고 요약을 보여줘”처럼 읽기 요청을 보냅니다.

ChatGPT는 remote MCP app을 서버 URL로 연결하므로 developer key를 ChatGPT 대화 설정에 직접 붙여 넣지 않습니다. Developer mode와 앱 생성·공개 권한은 계정 또는 조직 관리자 정책의 영향을 받습니다.

Claude에서 연결해 보기

Claude의 Customize → Connectors → Add custom connector에서 다음 URL을 입력합니다.

https://api.superfid.io/mcp

연결(Connect)을 누르고 Superfid Google 로그인·승인을 완료한 뒤, 대화에서 connector를 활성화하고 읽기 요청을 보냅니다. Team/Enterprise에서는 조직 owner가 Custom Connector를 먼저 추가해야 구성원이 연결할 수 있습니다. Anthropic 서버가 접근할 수 있도록 MCP URL은 공개 HTTPS 주소여야 합니다.

developer key로 직접 연결

developer key 방식의 MCP 요청은 다음 헤더를 사용합니다.

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

query string의 token, access_token, api_key 인증은 거부됩니다. 키 원문과 전체 Authorization 헤더를 로그에 남기지 마세요.

제한과 오류

요청 body는 64 KiB, MCP 결과는 512 KiB로 제한됩니다. 위치 row는 1,000개, projection은 SKU×root 250,000 cell까지이며, 동시 실행은 프로세스 2개·workspace 1개입니다. 제한 초과는 MCP protocol/HTTP 오류 또는 tool 결과의 isError: true로 반환됩니다.

MCP와 REST는 같은 workspace·principal quota를 공유합니다. 401/403/429 같은 인증·origin·quota 오류는 HTTP 계층에서 처리하고, 도구 실행 중 읽기 오류는 MCP tool 오류로 반환합니다.

OAuth 사용자는 현재 활성 workspace가 정확히 하나일 때 연결됩니다. 활성 workspace가 둘 이상이면 임의 선택을 막기 위해 workspace_selection_required 오류가 반환됩니다. workspace 선택 UI는 후속 범위입니다.

OAuth access token은 표준 authorization code + PKCE(S256)로 발급되고 refresh token으로 갱신됩니다. 토큰 원문과 전체 Authorization 헤더는 로그에 남기지 마세요.

MCP 연결