Servidor MCP

Ligue agentes de IA a dispositivos IoT através do servidor IoT MCP do Kilo, protegido por OAuth, e trabalhe com uma implementação em tempo real dentro das permissões do utilizador.

MCP — o Model Context Protocol — é um padrão aberto que permite a um cliente de IA descobrir e chamar ferramentas num servidor remoto. O Kilo IoT Server publica um endpoint MCP, pelo que qualquer cliente compatível com MCP — Claude Code, Claude Desktop, ChatGPT, Codex, Cursor e outros — pode ligar-se à sua organização e trabalhar com a sua implementação real: dispositivos, conectores, regras, alarmes e dashboards.

Este é um dos caminhos de integração para a Plataforma de IA Física para Agentes de IA. O Kilo continua a ser a camada de execução governada entre o cliente e a infraestrutura real, pelo que o modelo não precisa de recriar protocolos de dispositivos, limites de organização ou o ciclo de vida operacional em torno de uma alteração.

Como o MCP é um padrão aberto e não uma integração por fornecedor, esta não é uma lista fixa. Qualquer cliente que fale MCP sobre Streamable HTTP pode ligar-se, e os passos abaixo cobrem os dois fluxos que a maioria dos clientes segue: uma configuração por linha de comandos e uma caixa de diálogo de conetor.

O endpoint é:

https://mcp-auth.kiloiot.io/mcp

Autoriza a ligação no seu navegador com a sua conta habitual do Kilo. Não há nenhuma API key para gerar, nenhum token para colar e nada para guardar na máquina que executa o cliente.

Porque é importante

Sem MCP, colocar um assistente a trabalhar numa implementação em produção significa primeiro escrever uma integração: uma chave, uma biblioteca cliente, um script por pergunta. Isso é aceitável para um trabalho agendado e pesado para um incidente às 2 da manhã.

Com o servidor MCP ligado, o cliente que já usa torna-se uma consola de operador sobre a sua implementação — e pode agir, não apenas ler. Um engenheiro de operações pode perguntar que dispositivos num local deixaram de reportar e rever os alarmes em torno de uma janela de falha numa única conversa, com base em dados em tempo real. Um integrador a fazer um rollout pode provisionar um lote de dispositivos no conetor certo em vez de clicar no mesmo diálogo cinquenta vezes. Um líder de equipa pode pedir estatísticas de alarmes em aberto antes de uma passagem de turno. E como o conjunto de ferramentas inclui comandos de dispositivos, a mesma conversa pode alterar um intervalo de reporte ou comutar um relé. O que governa isso — e porque é que uma IA a atuar sobre infraestrutura física é uma proposta diferente de uma a atuar sobre dados — está descrito em IA Física.

Como a ligação transporta a sua própria conta, o assistente não é uma identidade adicional para governar. Pode fazer o que você pode fazer, na organização em que está a trabalhar, e mais nada.

Ligar o Claude Code

1. Adicione o servidor, dando-lhe o nome kilo:

   claude mcp add --transport http kilo https://mcp-auth.kiloiot.io/mcp

2. Inicie o Claude Code no seu projeto e execute:

   /mcp

3. Selecione o kilo servidor. O Claude Code abre o seu navegador para autorização.

4. Inicie sessão com a sua conta habitual do Kilo e aprove o pedido. O navegador confirma a autorização e pode regressar ao terminal.

5. Execute /mcp novamente se quiser verificar o resultado. Quando o kilo servidor é apresentado como ligado, as suas ferramentas ficam disponíveis e pode começar a fazer perguntas em linguagem natural.

Ligar o Claude Desktop

1. Abra Definições → Conetores.

2. Clique em Adicionar conetor personalizado.

3. Cole o URL do endpoint — https://mcp-auth.kiloiot.io/mcp — no campo URL.

4. Clique em Ligar. O Claude Desktop abre o seu navegador para autorização.

5. Inicie sessão com a sua conta habitual do Kilo e aprove o pedido.

6. De volta ao Claude Desktop, confirme que o conetor aparece como ativo. As suas ferramentas já estão disponíveis em qualquer conversa.

Ligar outro cliente MCP

ChatGPT, Codex, Cursor e outros clientes compatíveis com MCP seguem uma das mesmas duas formas. Onde o cliente tiver um diálogo de conetor ou integrações, adicione um servidor MCP personalizado e cole o URL do endpoint, tal como nos passos do Claude Desktop acima. Onde é configurado a partir de uma linha de comandos ou de um ficheiro de configuração, registe o endpoint como um Streamable HTTP servidor — o transporte que este endpoint fornece — tal como nos passos do Claude Code.

Em qualquer caso, a autorização é a mesma: o cliente abre o seu navegador, inicia sessão com a sua conta habitual do Kilo e a ligação transporta as suas permissões. Consulte a documentação do próprio cliente para saber onde guarda os servidores MCP; nada neste endpoint é específico de um cliente.

Como é uma sessão ligada

Uma sessão autenticada do Claude Code a trabalhar numa implementação em tempo real: quando lhe é pedido para configurar um sensor LoRaWAN, recomenda o provisionamento através da plataforma, chama uma ferramenta do Kilo e pára para pedir permissão antes de continuar

O cliente pode responder com base na sua implementação real porque pode ler as ligações e os dispositivos disponíveis para a sua conta. O pedido de aprovação pertence ao cliente: o Kilo publica informação de segurança com cada ferramenta, e os clientes compatíveis podem usá-la para pedir confirmação. O Kilo impõe as permissões da sua conta independentemente de como o cliente trata essa informação. Veja Segurança e permissões.

Escolher a organização

https://mcp-auth.kiloiot.io/mcp trabalha contra a organização atualmente selecionada na aplicação web do Kilo. Este é o comportamento predefinido certo para a maioria das pessoas: aquilo em que está a trabalhar na plataforma é o que o seu cliente vê.

Se mudar a organização ativa na aplicação web, volte a ligar o cliente para que o endpoint predefinido reflita a alteração.

Para fixar um cliente a uma organização, independentemente do que estiver selecionado na aplicação web, ligue-o à forma do endpoint com âmbito de organização em vez disso:

https://mcp-auth.kiloiot.io/o/{organizationId}/mcp

Substitua {organizationId} pelo ID da organização na aplicação web. Fixar vale a pena quando um cliente deve operar sempre contra uma única organização de produção — por exemplo, um integrador que mantém a implementação de um cliente ou uma estação de trabalho que nunca deve tocar em pré-produção.

Se não for membro da organização para a qual fixou, o pedido é recusado.

O que o assistente pode fazer

Depois de ligado, o cliente vê um conjunto de ferramentas que chama em seu nome. Você não as chama diretamente — descreve a tarefa e o cliente escolhe as ferramentas de que precisa.

Área	O que o cliente ligado pode fazer
Dispositivos	Listar dispositivos na organização, provisionar dispositivos LoRaWAN, MQTT e trackers, ler perfis de dispositivos e inspecionar mapeamentos de sensores. device_list, device_provision_lorawan, device_provision_mqtt, device_provision_tracker, device_profile_list, sensor_map
MIOTY	Navegue no catálogo de dispositivos de uma ligação MIOTY — fabricantes, modelos de dispositivos e os respetivos blueprints, tanto nos âmbitos System como Custom — e comissione um endpoint a partir dele. mioty_catalog_list, device_provision_mioty
Hardware	Pesquise no catálogo de parceiros e na web aberta equipamento que corresponda a uma necessidade descrita e, em seguida, apresente uma lista curta desses produtos. Estas são as duas ferramentas que saem da sua organização. hardware_search, recommend_products
Comandos	Liste os comandos configurados num dispositivo, execute um por trás de uma confirmação e verifique se foi entregue. device_command_list, device_command_execute, device_command_status
Emulador	Navegue pelos presets de dispositivos, provisionar um dispositivo emulado, leia e atualize a sua configuração e intervalo, envie uma leitura pontual e mova um dispositivo entre o emulador e o hardware real — qualquer dispositivo real para o Emulador, e um dispositivo emulado para uma ligação LoRaWAN real. emulator_preset_list, emulator_preset_get, device_provision_emulator, emulator_config_get, emulator_config_update, emulator_send_once, device_connection_swap
Conectores	Revise os conectores definidos na organização e crie uma ligação pela qual um dispositivo possa reportar. connector_list, connection_create
Regras	Revise regras, prepare e implemente automação mediante confirmação, simule a lógica antes de chegar à produção e inspecione o histórico de execução. rule_list, rule_provision, rule_simulate, rule_execution_history
Alarmes	Liste alarmes e resuma a atividade de alarmes para um turno ou um local. alarm_list, alarm_stats
Dashboards	Liste dashboards e consulte os dados por trás de um widget, para que o cliente possa raciocinar sobre os mesmos números que os seus operadores observam. dashboard_list, widget_data_query
Organização	Leia os detalhes da organização, liste equipas, convide utilizadores e atribua funções. org_get, team_list, user_invite, user_role_assign

Como os clientes distinguem ações de leitura e escrita

O Kilo publica um título, uma descrição e anotações de segurança com cada ferramenta MCP. Os clientes compatíveis podem ler estas anotações antes de escolherem se devem executar a ferramenta imediatamente ou pedir-lhe confirmação.

Anotação	Exemplos	O que isso indica ao cliente
Apenas leitura	Listar dispositivos, ler histórico de alarmes, consultar dados de widgets	A ferramenta não altera a sua implementação.
Altera ou remove dados	Eliminar um dispositivo, atualizar um dashboard, trocar uma ligação, enviar um comando a um dispositivo	A ferramenta pode afetar a sua implementação ou equipamento, pelo que o cliente pode pedir confirmação.
Sai da sua organização	Pesquisar no catálogo de parceiros ou na web aberta hardware	A ferramenta acede a informação para além dos dados da sua organização.

Criar um dispositivo ou dashboard altera a sua organização, mas não substitui nem pára um recurso existente e pode ser desfeito eliminando o novo recurso. Por isso, o Kilo não descreve a criação como destrutiva.

As anotações de segurança são informação para o cliente, não um controlo de autorização. Os clientes decidem como apresentar confirmações. As suas permissões no Kilo continuam a ser o limite imposto, pelo que um cliente não pode executar uma ação que a sua conta não esteja autorizada a executar.

Segurança e permissões

• Inicia sessão você, não uma conta de serviço. A autorização acontece no seu navegador com a sua conta normal do Kilo. Não é gerada, copiada nem guardada nenhuma chave para a ligação.

• As suas permissões são o teto. A ligação transporta o seu próprio acesso. O cliente só pode fazer o que a sua conta está autorizada a fazer — se você não puder implementar uma regra ou convidar um utilizador, ele também não pode.

• Os limites da organização mantêm-se. Um pedido para uma organização da qual não é membro é recusado, quer venha do endpoint predefinido quer de um fixado.

• As ações mantêm os seus registos operacionais. As alterações e execuções de regras aparecem no histórico de regras, os despachos de comandos a dispositivos aparecem no histórico de execução de comandos e as alterações de acesso à organização aparecem no trilho de auditoria. Estes são registos separados para os respetivos fluxos de trabalho, não um único registo genérico de conversa.

Trate um cliente autorizado como uma sessão com sessão iniciada: deve ficar em máquinas que controla.

Como isto difere do assistente integrado

O Kilo tem um Assistente de IA IoT integrado na aplicação web — abra-o em Chat de IA e ele trabalha a sua implementação consigo, sem qualquer configuração. Esse é o caminho mais rápido para a maioria das pessoas, e é aí que vivem os portões de confirmação, os gráficos embutidos e a base de conhecimento da plataforma.

O servidor MCP aponta na outra direção: traz o seu próprio cliente à mesma implementação. Use-o quando quiser a sua implementação na ferramenta que já tem aberta — um terminal ao lado do código da integração que está a construir, ou um cliente de ambiente de trabalho onde a implementação fica ao lado do seu outro contexto. Ambos falam com a mesma plataforma, pelo que qual usar é uma questão de onde está a trabalhar.

Como isto difere de REST e gRPC

A API REST pública e a API gRPC destinam-se a programas que você escreve: um trabalho de sincronização, um pipeline de relatórios, uma ponte SCADA. Autenticam-se com uma API key com âmbito, que funciona sem supervisão. MCP destina-se a um cliente de IA a agir em seu nome, autorizado pelo seu próprio início de sessão e limitado pelas suas próprias permissões. Se estiver a escrever código, use REST. Se estiver a trabalhar com um assistente, use MCP.

Dicas

• Dê um nome ao servidor kilo no Claude Code. O comando acima faz isso e dá-lhe um identificador curto quando quiser apontar o cliente para um servidor específico.

• Comece apenas com leitura. Peça uma lista de dispositivos ou um resumo de alarmes antes de pedir uma execução de provisionamento. É uma forma rápida de confirmar que a ligação ficou na organização que esperava.

• Confirme a organização antes de trabalho em lote. Pergunte ao cliente a que organização está ligado, ou fixe o endpoint, antes de qualquer coisa que crie ou altere recursos.

• Fixe produção, deixe a pré-produção no predefinido. Um endpoint fixado não pode ser movido por um clique acidental no seletor de organização da aplicação web.

• Volte a ligar depois de mudar de organização na aplicação web, se estiver a usar o endpoint predefinido — a ligação existente mantém a organização para a qual foi autorizada.

Ver também

• Plataforma de IA Física para Agentes de IA — como os modelos, o Kilo e a infraestrutura física dividem a responsabilidade.

• Assistente de IA IoT — o assistente integrado na plataforma.

• API REST pública — o caminho de integração para programas que você escreve.

• Autenticação e chaves de API — como é feita a autorização das pedidos de API baseados em chave.