> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/api/mcp-server.md).

# 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](/kilo-docs-pt/kilo-iot-server/physical-ai.md). 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](/kilo-docs-pt/kilo-iot-server/physical-ai.md).

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`:

   ```bash
   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

<figure><img src="https://585438662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNQh1wBSHSaknslMdOXm%2Fuploads%2Fgit-blob-c76dbc8c4ecd947cc8440377d59be70c5367d640%2Fmcp-claude-session.jpg?alt=media" alt="A Claude Code session connected to Kilo over MCP, calling the connection_list tool and asking permission before continuing"><figcaption><p>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</p></figcaption></figure>

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](#security-and-permissions).

## 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](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md), 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](/kilo-docs-pt/kilo-iot-server/ai-assistant.md) 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](/kilo-docs-pt/kilo-iot-server/api/public-rest-api.md) e a [API gRPC](/kilo-docs-pt/kilo-iot-server/api/grpc-api.md) 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](/kilo-docs-pt/kilo-iot-server/settings/api-keys.md) 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](/kilo-docs-pt/kilo-iot-server/physical-ai.md) — como os modelos, o Kilo e a infraestrutura física dividem a responsabilidade.
* [Assistente de IA IoT](/kilo-docs-pt/kilo-iot-server/ai-assistant.md) — o assistente integrado na plataforma.
* [API REST pública](/kilo-docs-pt/kilo-iot-server/api/public-rest-api.md) — o caminho de integração para programas que você escreve.
* [Autenticação e chaves de API](/kilo-docs-pt/kilo-iot-server/api/authentication-and-api-keys.md) — como é feita a autorização das pedidos de API baseados em chave.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/api/mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.