스튜디오 MCP 서버는 귀하를 대신하여 Open Cloud API를 호출할 수 있습니다. 귀하의 MCP 클라이언트는 자산을 업로드하고, 개발자 제품 및 게임 패스를 관리하며, 게임 설정을 변경하고, 기타 작업을 수행할 수 있으며, API 키를 생성하거나 붙여넣을 필요가 없습니다.
귀하가 클라이언트가 수행할 수 있는 작업을 결정합니다. 권한은 각 게임에 대해 귀하의 Roblox 계정에 저장되며, 스튜디오는 모든 요청에 대해 이를 시행합니다.
전제 조건
스튜디오 MCP 서버와 Open Cloud를 사용하기 전에:
- 스튜디오 MCP 서버를 활성화하고 클라이언트를 연결합니다. 자세한 내용은 Roblox Studio MCP 서버에 연결을 참조하세요.
- 게시된 게임에 속하는 장소를 엽니다. 권한은 게임별로 저장되므로, 게시되지 않은 로컬 장소는 사용할 수 없습니다.
- 게임을 관리할 수 있는 권한이 있어야 합니다. 그룹이 게임을 소유하는 경우, 귀하의 그룹 역할은 클라이언트에 부여한 작업을 허용해야 합니다.
작동 방식
스튜디오 MCP 서버는 open_cloud_invoke 도구를 추가합니다. 스튜디오는 귀하를 위해 접근을 관리합니다. 귀하의 클라이언트는 현재 게임에 대해 활성화한 범위만 사용할 수 있으며, 자격 증명을 보거나 처리하지 않습니다. 오직 귀하만 권한을 변경할 수 있습니다. 클라이언트는 스스로 이를 활성화할 수 없습니다.
각 게임에 대해 귀하는 클라이언트가 호출할 수 있는 Open Cloud 범위, 업로드할 수 있는 폴더, execute_luau에서 데이터 저장소 및 메모리 저장소 호출이 작동하는지 여부, 스크립트가 HTTP 요청을 할 수 있는지 및 어떤 도메인으로 요청할 수 있는지를 제어합니다.
| 매개변수 | 설명 |
|---|---|
| method | GET, POST, PUT, PATCH, 또는 DELETE. |
| endpoint | https://apis.roblox.com,아래의 경로로, 쿼리 문자열을 포함합니다. 예:/cloud/v2/universes/123`. |
| body | JSON 인코딩된 요청 본문. GET 및 DELETE의 경우 생략합니다. |
| scopes | 엔드포인트에서 요구하는 범위, 예: ["universe:read"]. 선택 사항이지만, 필수 범위가 활성화되지 않은 경우 명확한 오류를 반환합니다. |
| files | multipart/form-data 엔드포인트에 대한 로컬 파일, 예: 자산 업로드. 파일은 승인된 업로드 폴더에 있어야 합니다. |
권한 관리
열려 있는 게임의 권한을 관리하려면, 스튜디오의 오른쪽 하단 모서리에서 MCP를 클릭한 다음 MCP 권한 탭을 선택합니다. 또는 Assistant에서:
- Assistant를 엽니다.
- … ⟩ 설정을 클릭합니다.
- MCP 권한 탭을 선택합니다.
- 권한을 활성화하거나 비활성화합니다. 변경 사항은 클라이언트의 다음 요청에 적용됩니다.
접근 수준
시작점으로 접근 수준을 선택한 다음, 개별 권한을 활성화하거나 비활성화합니다. 각 게임은 균형 잡힌 상태에서 시작합니다.
| 접근 수준 | 활성화되는 항목 |
|---|---|
| 안전 | 저위험 범위만. 대부분의 권한이 꺼져 있습니다. |
| 균형 잡힌 | 저위험 및 중간 위험 범위. |
| 전체 접근 | 모든 범위, Robux 비용이 발생할 수 있는 고위험 범위, 플레이어에 영향을 미치거나 실시간 게임에 게시할 수 있는 범위 포함. |
| 사용자 정의 | 수준을 선택한 후 권한을 변경할 때 표시됩니다. |
Roblox는 각 범위에 대한 위험 수준을 설정합니다.
권한 섹션
권한은 클라이언트가 수행할 수 있는 작업에 따라 그룹화됩니다. 각 섹션은 하나 이상의 Open Cloud 범위 또는 스크립트 기능에 매핑됩니다. 각 범위에 대한 자세한 내용은 Open Cloud 범위 참조를 참조하세요.
| 섹션 | 허용되는 작업 | 범위 |
|---|---|---|
| 게임 보기 | 게임 및 장소 설정, 버전 기록, 분석 및 인스턴스를 읽습니다. | universe:read, universe.place:read, universe.analytics:read, universe.place.instance:read |
| 게임 편집 | 게임 및 장소 설정을 변경하고, 게시하고, 서버를 재시작하며, 인스턴스를 원격으로 편집합니다. | universe:write, universe.place:write, universe.place.instance:write |
| 플레이어 및 소셜 | 프로필 및 인벤토리를 읽고, 알림을 보내고, 그룹 및 포럼을 관리하며, 이벤트를 관리하고, 저장된 Creator Store 항목을 읽습니다. | user.*, group:*, group-forum:read, universe.event:*, creator-store-save:* |
| 데이터 저장 및 로드 | execute_luau에서 DataStoreService 및 MemoryStoreService를 사용합니다. | universe-datastores.*, universe.ordered-data-store.*, memory-store.* |
| 인터넷 연결 | 허용된 도메인으로 Luau에서 HTTP 요청을 하고, 크로스 서버 메시지를 게시합니다. | Network 기능, universe-messaging-service:publish |
| 자산 게시 및 관리 | 자산을 업로드하고 상태를 확인하며, 자산을 공유하고, Creator Store 목록을 관리하고, 장소 버전을 게시하고, 썸네일을 관리합니다. | asset:*, asset-permissions:write, creator-store-product:*, universe-places:write, universe.thumbnail:* |
| 돈 및 수익화 | 개발자 제품, 게임 패스 및 광고 캠페인을 생성 및 편집하고, 구독을 읽습니다. | developer-product:*, game-pass:*, ad.campaign:*, ad.billing:read, universe.subscription-product.subscription:read |
| 플레이어 결과 | 금지 목록을 읽고, 생성하고, 제거합니다. | universe.user-restriction:* |
| 보안 및 자격 증명 | 비밀 이름을 읽고 비밀을 생성하며, 클라우드에서 Luau를 실행합니다. | universe.secret:*, universe.place.luau-execution-session:* |
업로드 폴더
클라이언트는 승인된 폴더에서만 파일을 업로드할 수 있습니다. 클라이언트에게 자산을 업로드하도록 요청하기 전에 폴더를 추가하고, 내보내기를 그곳에 보관하세요.
클라이언트는 이 제한을 우회하기 위해 승인된 폴더로 파일을 복사하거나 이동할 수 없습니다. 파일이 다른 곳에 있다면, 직접 이동하거나 해당 폴더를 승인하세요.
데이터 저장소 및 메모리 저장소
클라이언트는 execute_luau에서 DataStoreService 및 MemoryStoreService를 통해 데이터 저장소 및 메모리 저장소에 접근합니다. Open Cloud를 통해서는 접근하지 않습니다. 사용하려면:
- 데이터 저장 및 로드 아래에서 필요한 범위를 활성화합니다. 읽기에는 universe-datastores.objects:read가 필요합니다. 쓰기에는 universe-datastores.objects:update가 필요합니다.
- 게임 설정 ⟩ 보안에서 API 서비스에 대한 스튜디오 접근 허용을 활성화합니다. 이 게임 설정은 귀하의 MCP 권한과는 별개입니다.
HTTP 요청
클라이언트가 실행하는 스크립트가 HttpService를 사용하여 HTTP 요청을 하도록 허용하려면:
- 클라이언트가 필요한 각 도메인을 HTTP 도메인 허용 목록에 추가합니다.
스튜디오는 목록에 없는 도메인으로의 요청을 거부합니다.
사용 불가능한 권한
일부 범위는 MCP 클라이언트에 부여할 수 없습니다. 여기에는 배지 범위, universe-datastores.control:*, universe-datastores.objects:create, 분석 알림 및 모든 legacy-* 범위가 포함됩니다. 이러한 작업에는 Creator Dashboard 또는 API 키를 사용하세요.
일부 엔드포인트는 일치하는 범위가 활성화되어 있어도 스튜디오에서 사용하는 토큰을 거부합니다. 그런 경우 클라이언트는 오류를 보고하고 작업을 완료할 수 있는 다른 방법을 제안합니다.
3D 모델 가져오기
Blender, Maya 또는 다른 3D 도구에서 자산을 가져오는 것은 일반적인 작업 흐름입니다. 클라이언트는 모델을 내보내고, 업로드하고, 삽입한 다음, 결과를 원본과 비교하고 가져오기에서 변경된 내용을 수정합니다.
모델을 가져오려면:
자산 게시 및 관리 ⟩ asset:read 및 asset:write를 활성화합니다.
내보내기가 들어갈 폴더를 승인합니다.
3D 도구에서 모델을 열거나, 승인된 폴더에 .glb 또는 .fbx로 내보냅니다.
클라이언트에게 프롬프트를 제공합니다. 예를 들어:
내 열린 Blender 파일에서 스튜디오의 스폰 지점 옆에 성을 가져옵니다.
가져오기 기술은 클라이언트에게 업로드 전에 확인하도록 지시합니다. 그런 다음:
- 각 메시가 삼각형 제한을 초과하는지 확인하고, 초과하는 경우 분할하거나 단순화할지 여부를 묻습니다.
- 모델을 업로드하고 검토를 기다립니다.
- 모델을 삽입하고 크기, 회전, 누락된 텍스처, 색상 및 고정을 수정합니다.
- 모델을 바닥에 배치하고 다른 객체 및 스폰 지점에서 멀리 떨어뜨립니다.
지원되는 자산 유형, 형식 및 크기 제한에 대한 내용은 자산 사용 가이드를 참조하세요.
기술
다음 기술은 클라이언트가 이러한 권한을 사용하는 방법을 가르칩니다. MCP를 통해 연결된 클라이언트는 자동으로 이를 얻고 skill 도구로 로드합니다. 이를 보려면 Assistant를 열고 … ⟩ Assistant 설정을 클릭한 다음 기술을 선택합니다. 작업 흐름에 맞게 조정하려면 선택하고 복제를 클릭한 다음 복사본을 편집합니다. 귀하의 복사본은 원본을 대체하지만, 향후 업데이트를 받지 않습니다.
| 기술 | 설명 |
|---|---|
| rbx-open-cloud-usage | open_cloud_invoke로 Open Cloud를 호출하고, 올바른 엔드포인트를 선택하며, 오류를 처리합니다. |
| rbx-permissions | 작업에 필요한 권한을 결정하고, 활성화된 권한을 확인하며, 누락된 권한만 요청합니다. |
| rbx-import-asset | 외부 3D 도구에서 모델을 가져온 다음, 스튜디오에서 확인하고 수정합니다. |
문제 해결
요청이 차단되면 클라이언트는 누락된 내용을 보고합니다. 비활성화한 권한을 우회하지 않습니다.
| 오류 | 원인 | 수정 방법 |
|---|---|---|
| Scope '<scope>' has not been granted | 범위가 비활성화되었거나 이름이 잘못 입력되었습니다. | 일치하는 섹션에서 범위를 활성화합니다. |
| HTTP 403 또는 401, 범위가 활성화된 경우 | 엔드포인트가 MCP 토큰을 수락하지 않습니다. | 이 작업에는 Creator Dashboard 또는 API 키를 사용하세요. |
| lacking capability <capability> | 스크립트에 부여되지 않은 기능이 필요합니다. | Network에 대해 인터넷 연결을 활성화합니다. 다른 기능은 부여할 수 없습니다. |
| domain <domain> is not in the Assistant HTTP allowlist | 도메인이 허용 목록에 없습니다. | 인터넷 연결 ⟩ HTTP 도메인 허용 목록에서 추가합니다. |
| 502 … Access forbidden 데이터 저장소 호출에서 | 일치하는 데이터 저장 및 로드 범위가 비활성화되었습니다. | 읽기 또는 업데이트 범위를 활성화합니다. |
| Studio access to APIs is not allowed | 이 게임에 대해 스튜디오 API 접근이 비활성화되었습니다. | 게임 설정 ⟩ 보안 ⟩ API 서비스에 대한 스튜디오 접근 허용을 활성화합니다. |
| InternalError 메모리 저장소 호출에서 | memory-store.* 범위가 비활성화되었습니다. | 데이터 저장 및 로드에서 메모리 저장소 범위를 활성화합니다. |
| 승인된 업로드 디렉토리에 없는 파일 | 파일이 승인된 폴더 외부에 있습니다. | 폴더를 승인하거나 파일을 해당 폴더로 이동합니다. |