O servidor MCP do Studio pode chamar as APIs do Open Cloud em seu nome. Seu cliente MCP pode fazer upload de ativos, gerenciar produtos de desenvolvedor e passes de jogo, alterar configurações do jogo e muito mais, sem criar ou colar uma chave de API.
Você decide o que seu cliente pode fazer. As permissões são salvas na sua conta Roblox para cada jogo, e o Studio as aplica em cada solicitação.
Pré-requisitos
Antes de usar o Open Cloud com o servidor MCP do Studio:
- Ative o servidor MCP do Studio e conecte seu cliente. Para mais informações, veja Conectar ao servidor MCP do Roblox Studio.
- Abra um lugar que pertença a um jogo publicado. As permissões são salvas por jogo, então lugares locais não publicados não podem usá-las.
- Tenha permissão para gerenciar o jogo. Se um grupo possui o jogo, seu papel no grupo deve permitir as ações que você concede ao cliente.
Como funciona
O servidor MCP do Studio adiciona a ferramenta open_cloud_invoke. O Studio gerencia o acesso para você. Seu cliente só pode usar os escopos que você ativou para o jogo atual, e ele nunca vê ou manipula credenciais. Apenas você pode alterar suas permissões. Seu cliente não pode ativá-las por conta própria.
Para cada jogo, você controla quais escopos do Open Cloud seu cliente pode chamar, quais pastas ele pode fazer upload, se chamadas de armazenamento de dados e armazenamento em memória funcionam a partir de execute_luau, e se scripts podem fazer solicitações HTTP e para quais domínios.
| Parâmetro | Descrição |
|---|---|
| method | GET, POST, PUT, PATCH ou DELETE. |
| endpoint | O caminho sob https://apis.roblox.com,, incluindo qualquer string de consulta. Por exemplo, /cloud/v2/universes/123`. |
| body | Um corpo de solicitação codificado em JSON. Omitir para GET e DELETE. |
| scopes | Os escopos que o endpoint requer, como ["universe:read"]. Opcional, mas retorna um erro claro se um escopo necessário não estiver ativado. |
| files | Arquivos locais para endpoints multipart/form-data, como uploads de ativos. Os arquivos devem estar em uma pasta de upload aprovada. |
Gerenciar permissões
Para gerenciar permissões para o jogo que você tem aberto, clique em MCP no canto inferior direito do Studio e, em seguida, selecione a aba Permissões MCP. Ou, a partir do Assistant:
- Abra Assistant.
- Clique em … ⟩ Configurações.
- Selecione a aba Permissões MCP.
- Ative ou desative permissões. As alterações se aplicam à próxima solicitação do seu cliente.
Níveis de acesso
Escolha um nível de acesso como ponto de partida e, em seguida, ative ou desative permissões individuais. Cada jogo começa em Equilibrado.
| Nível de acesso | O que ativa |
|---|---|
| Seguro | Apenas escopos de baixo risco. A maioria das permissões está desativada. |
| Equilibrado | Escopos de baixo e moderado risco. |
| Acesso total | Todos os escopos, incluindo os de alto risco que podem custar Robux, afetar seus jogadores ou publicar no seu jogo ao vivo. |
| Personalizado | Exibido quando você altera qualquer permissão após escolher um nível. |
A Roblox define o nível de risco para cada escopo.
Seções de permissão
As permissões são agrupadas pelo que permitem que seu cliente faça. Cada seção mapeia para um ou mais escopos do Open Cloud ou capacidades de script. Para detalhes sobre cada escopo, veja a referência dos escopos do Open Cloud.
| Seção | O que permite | Escopos |
|---|---|---|
| Ver seu jogo | Ler configurações de jogo e lugar, histórico de versões, análises e instâncias. | universe:read, universe.place:read, universe.analytics:read, universe.place.instance:read |
| Editar seu jogo | Alterar configurações de jogo e lugar, publicar, reiniciar servidores e editar instâncias remotamente. | universe:write, universe.place:write, universe.place.instance:write |
| Jogadores e social | Ler perfis e inventários, enviar notificações, gerenciar grupos e fóruns, gerenciar eventos e ler itens salvos da Loja do Criador. | user.*, group:*, group-forum:read, universe.event:*, creator-store-save:* |
| Salvar e carregar dados | Usar DataStoreService e MemoryStoreService a partir de execute_luau. | universe-datastores.*, universe.ordered-data-store.*, memory-store.* |
| Conectar à internet | Fazer solicitações HTTP de Luau para domínios que você permitir e publicar mensagens entre servidores. | Capacidade Network, universe-messaging-service:publish |
| Publicar e gerenciar ativos | Fazer upload de ativos e verificar seu status, compartilhar ativos, gerenciar listagens da Loja do Criador, publicar versões de lugares e gerenciar miniaturas. | asset:*, asset-permissions:write, creator-store-product:*, universe-places:write, universe.thumbnail:* |
| Dinheiro e monetização | Criar e editar produtos de desenvolvedor, passes de jogo e campanhas publicitárias, e ler assinaturas. | developer-product:*, game-pass:*, ad.campaign:*, ad.billing:read, universe.subscription-product.subscription:read |
| Consequências para jogadores | Ler, criar e remover banimentos. | universe.user-restriction:* |
| Segurança e credenciais | Ler nomes de segredos e criar segredos, e executar Luau na nuvem. | universe.secret:*, universe.place.luau-execution-session:* |
Pastas de upload
Seu cliente só pode fazer upload de arquivos de pastas que você aprovar. Adicione uma pasta antes de pedir ao seu cliente para fazer upload de ativos e mantenha as exportações lá.
O cliente não pode copiar ou mover arquivos para uma pasta aprovada para contornar essa restrição. Se um arquivo estiver em outro lugar, mova-o você mesmo ou aprove sua pasta.
Armazenamentos de dados e armazenamentos em memória
Seu cliente acessa armazenamentos de dados e armazenamentos em memória através de DataStoreService e MemoryStoreService em execute_luau, não através do Open Cloud. Para usá-los:
- Ative os escopos que você precisa em Salvar e carregar dados. Leituras requerem universe-datastores.objects:read. Escritas requerem universe-datastores.objects:update.
- Em Configurações do Jogo ⟩ Segurança, ative Habilitar Acesso do Studio aos Serviços de API. Esta configuração de jogo é separada de suas permissões MCP.
Solicitações HTTP
Para permitir que scripts que seu cliente executa façam solicitações HTTP com HttpService:
- Adicione cada domínio que seu cliente precisa à lista de permissão de domínio HTTP.
O Studio nega solicitações a qualquer domínio que não esteja na lista.
Permissões indisponíveis
Alguns escopos não podem ser concedidos a um cliente MCP. Isso inclui escopos de distintivos, universe-datastores.control:*, universe-datastores.objects:create, alertas de análises e todos os escopos legacy-*. Use o Painel do Criador ou uma chave de API para essas tarefas.
Alguns endpoints também rejeitam o token que o Studio usa, mesmo quando o escopo correspondente está ativado. Se isso acontecer, seu cliente relata o erro e sugere outra maneira de concluir a tarefa.
Importar um modelo 3D
Importar ativos do Blender, Maya ou outra ferramenta 3D é um fluxo de trabalho comum. Seu cliente exporta o modelo, faz upload, insere e, em seguida, compara o resultado com a fonte e corrige o que a importação alterou.
Para importar um modelo:
Ative Publicar e gerenciar ativos ⟩ asset:read e asset:write.
Aprove a pasta para onde suas exportações vão.
Abra o modelo em sua ferramenta 3D ou exporte-o como .glb ou .fbx para a pasta aprovada.
Solicite ao seu cliente. Por exemplo:
Importe o castelo do meu arquivo aberto do Blender para o Studio, ao lado do ponto de spawn.
A habilidade de importação diz ao seu cliente para confirmar antes de fazer o upload. Ele então:
- Verifica cada malha em relação ao limite de triângulos e pergunta se deve dividir ou simplificar qualquer uma que exceda.
- Faz upload do modelo e aguarda moderação.
- Insere o modelo e corrige escala, rotação, texturas ausentes, cores e ancoragem.
- Coloca o modelo no chão, longe de outros objetos e pontos de spawn.
Para tipos de ativos suportados, formatos e limites de tamanho, veja o Guia de uso para ativos.
Habilidades
As seguintes habilidades ensinam seu cliente a usar essas permissões. Clientes conectados através do MCP as recebem automaticamente e as carregam com a ferramenta skill. Para visualizá-las, abra Assistant, clique em … ⟩ Configurações do Assistant, e selecione Habilidades. Para adaptar uma ao seu fluxo de trabalho, selecione-a e clique em Duplicar, depois edite sua cópia. Sua cópia substitui a original, mas não recebe atualizações futuras.
| Habilidade | Descrição |
|---|---|
| rbx-open-cloud-usage | Chama o Open Cloud com open_cloud_invoke, seleciona o endpoint correto e lida com erros. |
| rbx-permissions | Determina quais permissões uma tarefa precisa, verifica quais estão ativadas e pergunta a você apenas pelas que estão faltando. |
| rbx-import-asset | Importa um modelo de uma ferramenta 3D externa e, em seguida, verifica e corrige-o no Studio. |
Solução de problemas
Quando uma solicitação é bloqueada, o cliente relata o que está faltando. Ele nunca contorna uma permissão que você desativou.
| Erro | Causa | Solução |
|---|---|---|
| Scope '<scope>' has not been granted | O escopo está desativado ou o nome está escrito incorretamente. | Ative o escopo na seção correspondente. |
| HTTP 403 ou 401, com o escopo ativado | O endpoint não aceita o token MCP. | Use o Painel do Criador ou uma chave de API para essa tarefa. |
| lacking capability <capability> | Um script precisa de uma capacidade que não está concedida. | Ative Conectar à internet para Network. Outras capacidades não podem ser concedidas. |
| domain <domain> is not in the Assistant HTTP allowlist | O domínio não está na sua lista de permissão. | Adicione-o em Conectar à internet ⟩ lista de permissão de domínio HTTP. |
| 502 … Access forbidden de uma chamada de armazenamento de dados | O escopo correspondente de Salvar e carregar dados está desativado. | Ative o escopo de leitura ou atualização. |
| Studio access to APIs is not allowed | O acesso da API do Studio está desativado para este jogo. | Ative Configurações do Jogo ⟩ Segurança ⟩ Habilitar Acesso do Studio aos Serviços de API. |
| InternalError de uma chamada de armazenamento em memória | Os escopos memory-store.* estão desativados. | Ative os escopos de armazenamento em memória em Salvar e carregar dados. |
| Arquivo não está em um diretório de upload aprovado | O arquivo está fora de suas pastas aprovadas. | Aprove a pasta ou mova o arquivo para uma. |