MCP 토큰 발급 · 자동등록

CONNECT / HTTP

MCP 서버 연결

먼저 MCP 토큰을 발급한 뒤, 아래 JSON을 Cursor·Codex·Claude Desktop mcpServers 설정에 붙입니다. dev는 https://dev.koiscore.com/api/mcp, 운영은 https://koiscore.com/api/mcp입니다.

{
  "mcpServers": {
    "koiscore-publishing": {
      "type": "http",
      "url": "https://dev.koiscore.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <KOISCORE_MCP_TOKEN>"
      }
    }
  }
}

TOOLS / SCOPE

제공 도구

연결 후 도구 목록에 register_game_draft, update_game_draft, build_sandbox_preview 등이 보입니다. 쓰기 도구는 draft·SKU·릴리즈 이미지를 실제로 변경합니다.

AUTH / PLATFORM LOGIN

게임별 STOVE·Microsoft 로그인 설정

세 도구는 등록된 게임 소유권을 확인한 후 동작합니다. 조회·검증에는 games:read, 저장에는 games:register 권한과 해당 게임 접근 권한이 필요합니다. 설정은 게임 ID·플랫폼·환경별로 분리되며, 저장할 때 전달하지 않은 필드·다른 플랫폼·다른 환경 설정은 유지됩니다. 비밀값은 서버에서 암호화해 저장하고 조회 응답에는 값 대신 등록 여부만 표시합니다.

list_game_platform_login_settings({
  "gameId": "billiards",
  "environment": "production"
})

set_game_platform_login_settings({
  "gameId": "billiards",
  "provider": "stove",
  "environment": "production",
  "enabled": true,
  "publicConfig": {
    "platformAppId": "GM-2C0E-6AB571B1_IND",
    "serviceId": "<STOVE_SERVICE_ID>",
    "apiBaseUrl": "<STOVE_LIVE_API_BASE_URL>"
  },
  "secrets": {
    "clientId": "<STOVE_SERVER_CLIENT_ID>",
    "clientSecret": "<STOVE_SERVER_CLIENT_SECRET>"
  }
})

set_game_platform_login_settings({
  "gameId": "billiards",
  "provider": "microsoft",
  "environment": "production",
  "enabled": true,
  "publicConfig": {
    "platformAppId": "9PBM8M8KNSZH",
    "entraClientId": "<ENTRA_APPLICATION_CLIENT_ID>",
    "tenantId": "<REGISTERED_TENANT_OR_COMMON>",
    "redirectUri": "<EXACT_REGISTERED_REDIRECT_URI>"
  },
  "secrets": { "nonceSecret": "<SERVER_ONLY_RANDOM_SECRET>" }
})

validate_game_platform_login_settings({
  "gameId": "billiards",
  "provider": "microsoft",
  "environment": "production"
})

Microsoft Store 앱 ID 9PBM8M8KNSZH와 Entra Application (client) ID는 별도 값입니다. Client ID·tenant·리디렉션 주소는 Entra 앱 등록을 확인해 입력하세요. STOVE 서비스 ID·Sandbox/Live 서버 자격증명도 파트너 콘솔에서 확인해야 합니다. 도구 검증 결과는 공급자 연결 상태를 점검하지만, Microsoft Entra 콘솔의 리디렉션 등록 완료 자체를 대신 확인하지는 않습니다. 서버 비밀값은 로그나 게임 클라이언트에 넣지 마세요.

로그인 API는 운영 https://koiscore.com, 개발 https://dev.koiscore.com에서 제공합니다. STOVE SDK 토큰은 POST /api/auth/stove/login에, Microsoft Authorization Code + PKCE 교환 후 받은 ID token과 검증용 nonce 값은 POST /api/auth/microsoft/login에 보냅니다. 로그인 후 GET /api/app/billiards/identity/context?requireAuthenticated=1에서 koiscore.game-identity.v2 assertion을 받고, 같은 assertion으로 GET /api/app/billiards/wallet?requireAuthenticated=1을 호출합니다. 온라인 게임 WebSocket도 assertion의 서명·만료·audience를 KOISCORE JWKS로 검증해야 합니다.

설정이 비어 있으면 로그인 API는 설정되지 않음 오류를 반환합니다. 실제 로그인을 시험하기 전에 각 환경의 설정을 저장·검증하고, 등록 계정으로 KOISCORE 세션·identity·지갑까지 확인하세요. 이메일 일치만으로 기존 KOISCORE 계정을 자동 연결하지 않습니다.

STORE / PRODUCT ID MAPPING

STOVE·Microsoft Store 상품 ID 연결

각 플랫폼의 실제 상품 ID를 기존 KOISCORE 상품 SKU에 연결합니다. 매핑은 게임 소유권과 SKU를 확인한 뒤 저장되며, STOVE는 stove, Microsoft Store는 msstore 플랫폼 값을 사용합니다. 토큰에는 해당 게임의 접근 허용과 games:read, games:register 권한이 필요합니다.

set_game_product_platform_mapping({
  "gameId": "your-game",
  "sku": "your-game.season-pass",
  "platform": "stove",
  "environment": "production",
  "appIdentifier": "<STOVE_APP_ID>",
  "productId": "<STOVE_PRODUCT_ID>",
  "enabled": true
})

set_game_product_platform_mapping({
  "gameId": "your-game",
  "sku": "your-game.season-pass",
  "platform": "msstore",
  "environment": "production",
  "appIdentifier": "<MSSTORE_APP_ID>",
  "productId": "<MSSTORE_PRODUCT_ID>",
  "enabled": true
})

list_game_product_platform_mappings({ "gameId": "your-game" })

입력 필드는 gameId, sku, platform, environment (test 또는 production), appIdentifier, productId, enabled입니다. 상품 SKU가 먼저 등록돼 있어야 합니다. 활성 매핑의 앱 ID나 상품 ID를 바꾸려면 먼저 enabled: false로 비활성화한 뒤 수정하세요. 등록된 매핑은 플랫폼별 유효 상품 ID 설정을 관리할 뿐, 영수증 검증이나 판매 기능 자체를 활성화하지는 않습니다.

GAMES / CRUD

등록 게임·상품 수정 예시

update_game_draft({
  "gameId": "example-game",
  "runtimeUrl": "https://example-game.koiscore.com/",
  "title": {
    "ko": "예시 게임",
    "en": "Example Game",
    "ja": "サンプルゲーム"
  },
  "genres": ["casual", "puzzle"]
})

add_game_product({
  "gameId": "example-game",
  "product": {
    "sku": "example-game.gem-pack",
    "title": { "ko": "젬 팩", "en": "Gem Pack", "ja": "ジェムパック" },
    "productType": "soft_currency",
    "commerceType": "gem",
    "gemPrice": 120,
    "grantKey": "koi_gem",
    "grantAmount": 500
  }
})

SANDBOX / PREVIEW

샌드박스 미리보기

build_sandbox_preview는 플레이어 샌드박스 UI와 같은 미리보기를 반환합니다.

RELEASE / EXAMPLE

스토어 데이터·이미지

MCP upload_release_asset와 동일 작업은 콘솔 릴리즈 에셋에서도 할 수 있습니다.

GUARDRAILS / REVIEW

안전 경계

• 등록 게임은 항상 draft로 시작 · 라이브는 운영 검수 후
• 강제 라이브·광고 정산 변경은 MCP 불가
• 토큰은 허용 gameId 접두사만 접근