Merchant API MCP 액세스 서비스 (알파)

Merchant API 모델 컨텍스트 프로토콜 (MCP) 액세스 서비스를 사용하여 판매자 센터 데이터 및 분석 정보에 승인된 액세스 권한을 얻어 새로운 에이전트형 환경과 자동화된 워크플로를 빌드하세요.

개요

Merchant API MCP 액세스 서비스는 LLM, 에이전트, 코딩 어시스턴트가 판매자 센터 데이터를 기반으로 새로운 에이전트형 환경과 자동화된 워크플로를 빌드하고 오케스트레이션할 수 있는 표준화된 보안 브리지를 제공합니다.

특히 판매자 센터 데이터와 Google에서 생성한 보고서 및 분석 정보에 승인된 액세스 권한을 부여하여 다음과 같은 사용 사례를 해결하기 위해 읽기 전용 및 제한된 쓰기 작업을 실행할 수 있습니다.

• 제품 비승인 진단 및 해결
• 실적 보고서 및 분석 정보 생성
• 자동 개선 선택 검토
• 데이터 소스 생성 및 가져오기

안전 및 액세스 제어

Merchant API MCP 액세스 서비스는 보안을 우선순위로 하여 설계되었습니다.

• 인증: 도구 실행은 표준 Merchant API 인증에 의거하여 관리되며 OAuth 2.0 또는 서비스 계정 사용자 인증 정보가 필요합니다. 가능한 가장 제한적인 액세스 권한이 있는 사용자 인증 정보를 사용하는 것이 좋습니다.
• 실행 안전: 도구 공개 상태는 에이전트형 검색에 제한되지 않지만 도구 실행은 특정 API 사용자 인증 정보로 제한됩니다.
• 보호 수단: 도구는 안전 가드레일로 읽기 전용 작업 및 위험도가 낮은 쓰기 도구 (예: 데이터 소스 생성)로 엄격하게 제한됩니다.

중요 고려사항

Merchant API MCP 액세스 서비스는 알파 버전이며 범위와 기능이 확장되고 변경될 수 있습니다.

시작하기 전에 다음 제한사항 및 권장사항을 검토하세요.

변경사항 및 출시 버전

변경사항은 사전 고지 없이 발생할 수 있으며 출시 노트에 게시됩니다.

안전한 테스트

실제 프로덕션 환경에서 이러한 도구를 활용하기 전에 테스트 계정 또는 비실시간 계정을 사용하여 먼저 실험하는 것이 좋습니다.

공유 할당량

Merchant API MCP 액세스 서비스는 표준 Merchant API 호출과 동일한 할당량 풀을 공유합니다. 에이전트를 실행하면 특히 데이터 소스 가져오기의 경우 할당량이 빠르게 소진될 수 있습니다. 프로덕션 서비스 중단을 방지하려면 테스트 계정을 사용하는 것이 좋습니다.

도구 필터링 및 안전

새로운 기능, 특히 쓰기 작업이 앞으로 추가될 예정입니다. 전체 도구 모음을 노출하는 대신 클라이언트를 기본 제공 도구 필터링으로 명시적으로 구성하는 것이 좋습니다.

사용 가능한 기능 요약

Merchant API MCP 액세스 서비스를 사용하여 다음과 같은 작업을 에이전트형 방식으로 실행할 수 있습니다.

• 정확한 리소스 이름을 사용하여 특정 제품의 자세한 상태 및 보고 컨텍스트를 가져옵니다.
• 여러 제품을 나열하고 검색 합니다.
• 인기 제품, 가격 분석 정보, 노출 경쟁, YouTube Shopping 제휴 프로그램 분석 정보에 대한 실적 측정항목, 제품 상태, 분석 정보를 쿼리 합니다.
• 제품 공개 상태 또는 프로그램 참여에 영향을 미치는 계정 수준 문제를 파악 합니다.
• 데이터 소스의 업로드 상태를 나열, 생성, 가져오기, 확인 합니다.
• 인벤토리 전반에서 제품 비승인에 대한 집계된 사유를 나열 합니다.
• 상품, 이미지, 배송의 자동 개선 설정을 검토 합니다.
• 특정 판매자 센터 프로그램의 활성 지역, 충족되지 않은 요구사항, 참여 상태를 확인 합니다.

시작하기

IDE, 코딩 어시스턴트 또는 에이전트를 Merchant API MCP 액세스 서비스에 연결하려면 MCP 클라이언트 설정 (예: mcp.json 또는 settings.json)을 업데이트하세요.

클라이언트 구성

구성 설정:

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      }
    }
  }'

다음을 바꿉니다.

• ACCOUNT_ID: 판매자 센터 ID
• ACCESS_TOKEN: API 호출을 실행할 승인 토큰
• GOOGLE_CLOUD_PROJECT_ID: 판매자 센터 계정과 연결된 Google Cloud 프로젝트의 ID

사용 시나리오 예

Merchant API MCP 액세스 서비스를 활용하여 에이전트형 환경과 자동화된 워크플로를 빌드하는 방법을 보여주기 위해 다음 시나리오를 고려해 보세요.

시나리오 1: 제품 비승인 진단 및 해결

특정 제품이 Google 검색 결과에 표시되지 않는 이유를 알고 싶습니다.

사용자 프롬프트:

'혜택 ID'가 'offer123'인 제품이 비승인된 이유는 무엇인가요?

MCP를 사용하는 에이전트 동작:

1. 에이전트가 list_products 또는 get_product_by_name을 호출하여 제품 상태를 찾습니다.
2. MCP 서버는 issues(예: '잘못된 가격 형식' 또는 '배송 값 누락') 목록을 포함한 제품 상태를 반환합니다.
3. 에이전트는 문제를 분석하고 근본 원인을 설명하며 해결 방법을 제안합니다 (예: 가격 정보 업데이트).

시나리오 2: 자동 개선 선택 검토

배송 자동 개선이 활성 상태인지 확인하고 싶습니다.

사용자 프롬프트:

'배송 자동 개선이 사용 설정되어 있나요?'

MCP를 사용하는 에이전트 동작:

1. 에이전트가 get_automatic_improvements를 호출하여 계정 수준 설정을 가져옵니다.
2. MCP 서버는 이미지, 상품, 배송 개선의 상태를 보여주는 구성을 반환합니다.
3. 에이전트는 배송 개선이 활성 상태인지 확인하거나 사용 중지된 경우 사용 설정 방법을 설명합니다.

시나리오 3: 실적 보고서 및 분석 정보 생성

판매자 센터 UI를 탐색하지 않고 최근 실적을 빠르게 확인하고 싶습니다.

사용자 프롬프트:

'지난주 클릭수 기준 실적이 가장 우수한 제품 5개를 보여주세요.'

MCP를 사용하는 에이전트 동작:

1. 에이전트는 판매자 센터 쿼리 언어 (MCQL) 쿼리 를 구성합니다. product_performance_view 테이블을 타겟팅하고 clicks DESC를 기준으로 정렬하며 5로 제한합니다.
2. 에이전트는 구성된 쿼리로 report_search를 호출합니다.
3. MCP 서버는 실시간 보고 데이터베이스에 대해 쿼리를 실행하고 행을 반환합니다.
4. 에이전트는 결과를 깔끔한 마크다운 테이블로 형식화합니다.

시나리오 4: 데이터 소스 생성 및 가져오기

제품 업데이트를 업로드하기 위해 새 데이터 소스를 추가하고 싶습니다.

사용자 프롬프트:

'판매자 계정에 'price-updates'라는 보조 데이터 소스를 만들어 주세요.'

MCP를 사용하는 에이전트 동작:

1. 에이전트는 지정된 설정으로 create_data_source를 호출하여 새 피드를 등록합니다.
2. MCP 서버는 데이터 소스를 만들고 고유한 리소스 이름을 반환합니다.
3. 에이전트는 fetch_data_source를 호출하여 연결된 파일의 다운로드 및 처리를 트리거합니다.
4. 에이전트는 get_file_upload를 호출하여 업로드 진행률을 모니터링하고 상품의 처리 상태가 성공적인지 확인합니다.

MCP 도구 및 설명

Merchant API MCP 액세스 서비스는 다음과 같은 도구를 에이전트에 노출합니다.