Pular para o conteúdo
SHCDocumentação SHC

API local e MCP

A API local deixa um assistente de IA fazer no Studio SHC o que você faria clicando. Você abre o Studio e pede ao assistente, por exemplo: “crie as ações do botão da sala e envie para o equipamento”.

  • Funciona com o Claude Code, o Codex e outros assistentes que usam MCP, a forma padrão de um assistente de IA se ligar a outro programa.
  • Funciona no Studio SHC instalado: macOS, Windows, Android, iPhone e iPad.
  • No iPhone e no iPad, o Studio precisa estar na tela, com o aparelho desbloqueado. Com o Studio em segundo plano ou a tela bloqueada, a API local não responde.
  • Aceita programas deste aparelho e de outros aparelhos da mesma rede. A janela de permissão aparece sempre no Studio SHC e mostra de qual aparelho veio o pedido.
  • Copie o endereço ou o comando em Configurações → API local. Eles já saem com o IP da rede escolhida em Networking.
  • Os exemplos abaixo usam 127.0.0.1, que só vale no próprio aparelho do Studio.
  • Quem está na mesma rede é considerado de confiança: a comunicação não é criptografada.
  • Aplicativos que conectam pela nuvem, como os conectores do app do Claude no celular ou no tablet, não alcançam a rede local. O Claude Code em outro computador funciona.
  • Funciona só com o Studio aberto e com uma conta conectada. Com o Studio fechado, nada responde.
  • O assistente usa a sua conta e segue as mesmas regras da tela. O que a tela não deixa fazer, ele também não consegue.

A API local já vem ligada e não pede usuário nem senha: cada programa pede a sua permissão na janela Permitir. Para desligar, abra Configurações, vá até a seção API local e desligue a chave.

No celular e no tablet, toque onde esta página diz “clique”.

Conectar o assistente

Seção intitulada “Conectar o assistente”

Para conectar o Claude Code:

  1. Abra o Studio SHC.
  2. Em Configurações, vá até a seção API local.
  3. No quadro Exemplo para o Claude Code (Terminal ou PowerShell), clique no ícone de copiar ao lado do comando.
  4. Cole o comando no Terminal (macOS) ou no PowerShell (Windows) do computador onde o Claude Code roda.
  5. Abra o Claude Code.
  6. Quando o Studio mostrar a janela Permitir, clique em Permitir.

Na porta padrão, o comando é este:

Janela do terminal
claude mcp add --transport http studio-shc http://127.0.0.1:5280/mcp --header "X-Shc-Cliente: Claude Code"

O comando não leva chave nem senha. O cabeçalho X-Shc-Cliente só dá o nome que aparece na janela Permitir.

Para outro assistente, copie o Endereço do MCP na mesma seção e informe esse endereço na configuração de MCP do assistente.

A janela Permitir

Seção intitulada “A janela Permitir”

Quando um programa novo se conecta, o Studio pergunta:

Permitir que nome do programa configure o Studio SHC?

  • Permitir: o programa passa a ler e alterar as configurações com a sua conta.
  • Recusar: nega só aquele pedido. Se o programa pedir de novo, a janela volta.
  • Sem resposta em 60 segundos: a janela fecha e o pedido é negado.

A tecla Esc e o clique fora da janela não fecham a janela. Escolha Permitir ou Recusar.

Em De onde vem o pedido, a janela mostra Este computador ou Outro aparelho da rede, com o IP do aparelho.

Depois do Permitir, o mesmo programa no mesmo aparelho passa sem janela.

A permissão vale até uma destas situações:

  • você fechar o Studio SHC;
  • você desligar a API local;
  • você sair da conta ou trocar de conta;
  • você trocar a porta;
  • você clicar em Revogar, ao lado do programa, na lista Programas permitidos nesta sessão.

Depois disso, o programa precisa pedir permissão de novo.

Programas e scripts

Seção intitulada “Programas e scripts”

Um programa ou script seu também pode usar a API local, com a mesma janela Permitir.

  1. Faça a primeira chamada. O cabeçalho X-Shc-Cliente é opcional: ele mostra o nome do programa na janela.

    Janela do terminal
    curl -i -H "X-Shc-Cliente: Meu script" http://127.0.0.1:5280/v1/saude

  2. Clique em Permitir no Studio.

  3. Faça as chamadas seguintes do mesmo aparelho, com o mesmo programa. Elas passam sem janela e sem chave:

    Janela do terminal
    curl http://127.0.0.1:5280/v1/projects

O Studio reconhece o programa pelo IP do aparelho e pela identificação que o programa envia (o cabeçalho User-Agent). Pedido de outro aparelho, ou de outro programa no mesmo aparelho, abre a janela Permitir de novo.

Para usar a mesma permissão nesses casos, use a chave:

  1. Na resposta do Permitir, copie a chave do cabeçalho X-Shc-Chave. Maiúsculas e minúsculas não fazem diferença no nome: o curl mostra x-shc-chave.

  2. Mande a chave nas chamadas:

    Janela do terminal
    curl -H "Authorization: Bearer SUA_CHAVE" http://127.0.0.1:5280/v1/projects

A chave vale só nessa sessão, nas mesmas condições da permissão. Pedido com chave inválida é tratado como pedido sem chave.

No PowerShell, escreva curl.exe no lugar de curl.

A janela Permitir espera até 60 segundos. Deixe o tempo limite do seu programa acima disso.

A lista do que a API faz está em http://127.0.0.1:5280/v1/openapi.json, no formato OpenAPI. Esse endereço pede a mesma permissão das outras chamadas. Os endereços dessa lista usam 127.0.0.1. De outro aparelho, troque pelo IP do aparelho do Studio. O formato de um preset está em http://127.0.0.1:5280/v1/schemas/preset.json, no formato JSON Schema.

A lista de todos os endereços, com o que cada um pede e devolve, está em Endereços da API local.

Para um cliente MCP próprio, use o endereço /mcp:

  1. Mande a mensagem initialize. O Studio mostra a janela Permitir.
  2. Copie o cabeçalho Mcp-Session-Id da resposta.
  3. Mande esse cabeçalho em todas as mensagens seguintes. Ele vale como permissão, sem chave.

Se a resposta disser “Sessão MCP não encontrada”, mande o initialize de novo. A versão do protocolo MCP preferida é 2025-11-25. O Studio também aceita 2025-06-18 e 2025-03-26.

Porta

Seção intitulada “Porta”

A porta padrão é 5280. Para trocar:

  1. Na seção API local, clique no lápis ao lado de Porta.
  2. Digite um número de 1024 a 65535.
  3. Confirme.

Ao trocar a porta, todas as conexões caem e todas as permissões são retiradas. Reconfigure cada programa com o endereço novo. No Claude Code, rode claude mcp remove studio-shc no Terminal (macOS) ou no PowerShell (Windows) e depois o comando novo que aparece na seção API local.

O que dá para pedir

Seção intitulada “O que dá para pedir”

Fale com o assistente com as suas palavras. Estes são exemplos por tema.

Tema Exemplo de pedido
Acionar uma saída “Ligue a luz da sala.”
Executar um botão “Execute as ações do botão da entrada” ou “qual botão foi apertado por último?”
Criar ações em botões “Faça o botão da entrada apagar todas as luzes da sala ao segurar.”
Agendar um botão “Agende o botão Boa noite para as 23h, de segunda a sexta.”
Enviar ao equipamento “Envie as pendências aos equipamentos.” É o mesmo que Atualizar tudo.
Resolver divergência “Mostre o que está diferente neste equipamento e mantenha os dados da nuvem.” Veja Dados divergentes.
Abrir projeto “Abra o projeto da casa de praia.”
Projeto e compartilhamento “Crie um projeto chamado Casa Nova”, “mude a imagem do projeto”, “compartilhe este projeto com este e-mail” ou “tire esta pessoa do projeto.”
Ambientes “Crie o ambiente Varanda” ou “ponha esta foto como fundo da Sala.”
Entradas e saídas “Mude o nome da saída 1 para Lustre e ponha na Sala”, “oculte a saída 4” ou “quais botões controlam a luz da cozinha?”
Adicionar equipamento “Procure equipamentos na rede e adicione o novo ao projeto” ou “procure equipamentos nos IPs de 192.168.0.10 a 192.168.0.50.”
Equipamento “Mostre as configurações deste equipamento”, “conecte o equipamento” ou “vincule o acesso externo a este projeto.”
O programa que roda dentro do equipamento. Cada versão nova pode trazer correções e melhorias. “Qual é a versão do firmware deste equipamento? Tem versão nova?” O assistente só consulta.
Exportar e importar “Exporte este equipamento” ou “importe este arquivo neste equipamento.” A importação recusa Wi-Fi e parâmetros internos.
Um aparelho de outro fabricante, como uma TV, que o Studio SHC aciona por um comando de rede pronto. “Adicione esta TV ao projeto e faça o pareamento” ou “a TV está ligada?” No pareamento, aceite o pedido na tela do aparelho.
Presets “Valide e crie um preset para esta TV”, “teste o comando Ligar antes de salvar” ou “dê nota 5 a este preset.”
Um cartão com várias ações que o Studio SHC e o app do morador acionam com um toque, sem botão na parede. Fica salva no projeto, não no equipamento, e não precisa de Atualizar tudo. “Crie uma cena Cinema que apaga as luzes da sala” ou “execute a cena Cinema.”
Planta “Mostre a planta deste projeto” ou “ajuste a planta como vou descrever.”
Consultar “Mostre o resumo do projeto”, “o que precisa de atenção?”, “mostre os logs” ou “mostre o tráfego na rede.”

As ações criadas em botões ficam guardadas no projeto. Elas só chegam ao equipamento depois do envio.

O que fica só no Studio

Seção intitulada “O que fica só no Studio”

Estas tarefas você faz na tela do Studio:

Boas práticas

Seção intitulada “Boas práticas”
  • Confira antes de confirmar. Leia o que o assistente vai fazer, principalmente quando ele vai mover carga real, como uma persiana, ou substituir dados.
  • Abrir projeto troca a tela. Quando o assistente abre um projeto, o Studio muda para esse projeto e mostra um aviso. Salve o que estiver editando antes de pedir.
  • Salve a planta antes. Com alterações não salvas na tab Visual, o Studio recusa abrir outro projeto ou gravar a planta pelo assistente. Veja Salvar e conflitos.
  • Mantenha a tela Projeto fechada enquanto o assistente edita o projeto. A tela não recarrega sozinha, e clicar em Salvar nela desfaz a mudança do assistente.

Problemas comuns

Seção intitulada “Problemas comuns”

O assistente não conecta. Confira se o Studio está aberto e se o estado da seção API local é Ligada. Depois, reconecte o assistente.

A janela Permitir não apareceu. Traga o Studio para a frente e veja se o programa já está em Programas permitidos nesta sessão. Se estiver, ele já tem acesso. Se a janela ficou 60 segundos sem resposta, reconecte o assistente para pedir de novo.

O assistente diz “Abra este projeto”. A tarefa precisa do projeto aberto no Studio. Abra o projeto na tela ou peça ao assistente para abrir.

O estado é Porta em uso. Outro programa já usa essa porta. Troque a porta.

O pedido foi negado. A mensagem diz o motivo:

Mensagem O que fazer
O acesso não foi permitido no Studio SHC. Peça de novo e clique em Permitir.
Nenhum usuário está logado no Studio SHC. Entre na sua conta no Studio.
Só o dono do projeto altera a configuração. Peça a alteração ao dono do projeto.
Seu perfil não acessa… neste projeto. Seu perfil não tem acesso a essa parte do projeto. Fale com o dono do projeto ou com o administrador.
O equipamento está offline. Confira se o equipamento está ligado e na rede. Depois, peça ao assistente para conectar de novo.