MCP 연동 가이드

토스쇼핑 API 문서는 MCP(Model Context Protocol) 서버를 제공합니다. AI 코딩 도구(Claude Desktop, Cursor, VS Code 등)에 연결하면 토스쇼핑 API 문서를 자연어로 검색하고, AI의 도움을 받아 연동 작업을 효율적으로 진행할 수 있습니다.

---

1. MCP란?

MCP(Model Context Protocol)는 AI 모델에게 외부에서 데이터를 전달하는 표준 프로토콜입니다.

토스쇼핑 MCP 서버를 연결하면 AI가 API 문서를 직접 검색하여 최신 스펙을 기반으로 정확한 답변과 코드를 제공합니다. 문서를 직접 탐색하거나, AI에게 문서 내용을 복사해서 전달할 필요가 없습니다.

---

2. MCP 서버 정보

아래는 AI 도구에서 토스쇼핑 MCP 서버에 연결할 때 필요한 정보입니다.

항목	값
MCP 엔드포인트	https://shopping-docs.toss.im/dev/~gitbook/mcp
전송 방식	Streamable HTTP
인증	불필요 (공개 문서)
접근 범위	토스쇼핑 API 문서 (공개된 최신 버전)

---

3. AI 도구별 설정 방법

각자 사용하고 있는 AI 혹은 개발 도구의 MCP 설정 방법에 따라 아래 JSON 설정을 추가하거나, 다음에서 제공하는 명령어를 활용하면 AI 도구가 MCP 서버와 연결되어 문서를 검색하거나 연동 관련 질문을 이해할 수 있게 됩니다.

{
  "mcpServers": {
    "toss-shopping-docs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shopping-docs.toss.im/dev/~gitbook/mcp"
      ]
    }
  }
}

3.1 Claude Code

claude mcp add --transport http --scope user toss-shopping-docs https://shopping-docs.toss.im/~gitbook/mcp

다음 명령어로 mcp가 추가되었는지 확인합니다

claude mcp list

3.2 Codex

codex mcp add toss-shopping-docs --url https://shopping-docs.toss.im/~gitbook/mcp

다음 명령어로 mcp가 추가되었는지 확인합니다

codex mcp list

---

4. 연결 확인

설정이 완료되면 AI 도구에서 토스쇼핑 API에 대해 질문해 보세요.

토스쇼핑 상품 등록 API의 필수 파라미터를 알려줘

AI가 API 문서를 검색하여 엔드포인트, 파라미터, 응답 형식 등을 구체적으로 안내하면 정상 연결된 것입니다.

연결이 되지 않는 경우:

• 엔드포인트 URL이 정확한지 확인

• 네트워크에서 shopping-docs.toss.im에 접근 가능한지 확인

• AI 도구를 재시작했는지 확인

• JSON 문법 오류가 없는지 확인

---

5. 활용 예시

5.1 API 연동 시작

사용자: 토스쇼핑 API 연동을 처음 시작하려고 해. 어떻게 하면 돼?

AI: (토스쇼핑 문서에서 검색)

1. Access Token 발급
   - POST https://oauth2.cert.toss.im/token
   - grant_type: client_credentials
   - client_id: 어드민에서 발급받은 access key
   - client_secret: 어드민에서 발급받은 secret key
   - scope: toss-shopping-fep:write

2. API 호출
   - Authorization 헤더에 Bearer {access_token} 추가
   - 운영: https://shopping-fep.toss.im
   - 테스트: https://shopping-fep-alpha.toss.im

5.2 특정 API 스펙 조회

사용자: 클레임 요청 목록 조회 API 파라미터가 뭐야?

AI: (토스쇼핑 문서에서 검색)

GET /api/v3/shopping-fep/claims

필수 파라미터:
- type: 클레임 유형 (CANCEL, EXCHANGE, RETURN)
- status: 클레임 상태 (REQUESTED 고정)

5.3 연동 코드 작성

사용자: Java로 토스쇼핑 Access Token 발급 코드 작성해줘

AI가 문서에서 인증 API 스펙을 검색한 뒤, 정확한 엔드포인트와 파라미터를 반영한 코드를 생성합니다.

public String getAccessToken(String clientId, String clientSecret) {
    RestTemplate restTemplate = new RestTemplate();

    MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
    params.add("grant_type", "client_credentials");
    params.add("client_id", clientId);
    params.add("client_secret", clientSecret);
    params.add("scope", "toss-shopping-fep:write");

    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

    HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(params, headers);

    ResponseEntity<Map> response = restTemplate.postForEntity(
        "https://oauth2.cert.toss.im/token",
        request,
        Map.class
    );

    return (String) response.getBody().get("access_token");
}

5.4 에러 트러블슈팅

사용자: 상품 등록 API에서 INVALID_REQUEST 에러가 나와.
       카테고리 코드를 어떻게 넘겨야 해?

AI: (토스쇼핑 문서에서 카테고리/상품 등록 문서 검색)

카테고리는 말단 카테고리 ID를 사용해야 합니다.
- 카테고리 구조는 2~6 level까지 가능
- isLeaf=true인 말단 카테고리만 상품 등록에 사용 가능
- 카테고리 항목 조회 API로 하위 카테고리를 탐색하세요:
  GET /api/v3/shopping-fep/products/categories/children?id={카테고리ID}

5.5 테스트 환경 설정

사용자: 테스트 환경에서 연동 테스트하려면 어떻게 해?

AI: (토스쇼핑 문서 검색)

1. 테스트 환경 접근 요청
   - 서버 outbound IP 정보와 담당자 정보를 제출
2. 승인 후 메일 수신
   - 테스트 앱 다운로드 링크
   - 본인인증 번호
   - 테스트 상점 초대 링크
3. 테스트 엔드포인트로 API 호출
   - https://shopping-fep-alpha.toss.im

---

6. 검색 가능한 문서 범위

MCP를 통해 검색할 수 있는 문서 카테고리입니다.

카테고리	주요 내용
API 인증	토큰 발급, Bearer 인증, OAuth2
상품	상품 등록/수정/삭제, 카테고리 조회, 재고 관리
주문	주문 조회, 주문 상태 변경
배송	배송 정보 등록, 송장 관리
클레임	취소/교환/반품 처리
정산	정산 내역 조회
환경 설정	테스트 환경, 운영 환경 엔드포인트
FAQ	자주 묻는 질문 및 트러블슈팅
통합솔루션	사방넷, 플레이오토 등 솔루션 연동

---

7. FAQ

Q. MCP를 사용하지 않고도 API 연동할 수 있나요?

A. 네. MCP는 AI 도구를 통한 개발 편의 기능입니다. 기존처럼 API 문서 사이트에서 직접 스펙을 확인하며 연동할 수 있습니다.

Q. MCP 서버에 인증이 필요한가요?

A. 아니요. 토스쇼핑 API 문서는 공개되어 있어 별도 인증 없이 MCP 서버에 접근할 수 있습니다. 단, 실제 API 호출 시에는 Access Token이 필요합니다.

Q. 어떤 AI 도구에서 사용할 수 있나요?

A. MCP를 지원하는 AI 도구라면 모두 사용 가능합니다. Claude Desktop, Cursor, VS Code (Copilot), Claude Code, Windsurf 등에서 연결할 수 있습니다.

Q. MCP로 API를 직접 호출할 수 있나요?

A. 아니요. MCP는 API 문서 검색 기능만 제공합니다. 실제 API 호출은 기존과 동일하게 토스쇼핑 API 서버(https://shopping-fep.toss.im)로 직접 요청합니다.

Q. 최신 문서가 반영되나요?

A. 네. MCP 서버는 항상 공개된 최신 버전의 문서를 제공합니다. 문서가 업데이트되면 MCP를 통한 검색 결과에도 즉시 반영됩니다.