> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Conecte agentes de IA ao Portal usando o protocolo MCP (Model Context Protocol)

# MCP Server

O Portal disponibiliza um servidor MCP (Model Context Protocol) completo que permite que LLMs e agentes de IA controlem dispositivos, automações, scripts, dashboards e muito mais — tudo usando linguagem natural.

## O que e o MCP?

O [Model Context Protocol (MCP)](https://modelcontextprotocol.io) e um protocolo aberto que padroniza como aplicações de IA se conectam a fontes de dados e ferramentas externas. O Portal implementa um MCP Server com **Streamable HTTP transport**, expondo mais de 55 ferramentas que cobrem todas as funcionalidades da plataforma.

Com isso, você pode usar assistentes como **Claude Code CLI**, **Gemini CLI** ou qualquer agente compatível com MCP para controlar sua casa inteligente por texto.

## Endpoint

```
https://portal.unicontrol.me/v1/mcp
```

<Info>
  O transporte utilizado e **Streamable HTTP** — o padrão recomendado pelo MCP para servidores remotos.
</Info>

## Autenticação

O MCP Server utiliza **OAuth 2.1** via Logto. A autenticação e automática: ao conectar um cliente MCP pela primeira vez, o fluxo OAuth será iniciado no navegador para autorizar o acesso.

Não e necessário configurar tokens manualmente — o protocolo MCP OAuth cuida de tudo.

## Ferramentas Disponíveis

O servidor expoe as seguintes ferramentas, organizadas por domínio:

### Dispositivos e Entidades

| Ferramenta         | Descrição                                                                   |
| ------------------ | --------------------------------------------------------------------------- |
| `list_devices`     | Listar todos os dispositivos                                                |
| `get_device`       | Obter detalhes de um dispositivo                                            |
| `list_entities`    | Listar todas as entidades                                                   |
| `get_entity_state` | Obter estado de uma entidade                                                |
| `get_all_states`   | Obter estados de todas as entidades                                         |
| `call_service`     | Chamar um serviço (light, switch, cover, climate, fan, media\_player, etc.) |

### Automações

| Ferramenta           | Descrição                          |
| -------------------- | ---------------------------------- |
| `list_automations`   | Listar todas as automações         |
| `get_automation`     | Obter detalhes de uma automação    |
| `create_automation`  | Criar uma nova automação           |
| `update_automation`  | Atualizar uma automação existente  |
| `delete_automation`  | Excluir uma automação              |
| `toggle_automation`  | Ativar/desativar uma automação     |
| `trigger_automation` | Executar uma automação manualmente |

### Scripts

| Ferramenta       | Descrição                     |
| ---------------- | ----------------------------- |
| `list_scripts`   | Listar todos os scripts       |
| `get_script`     | Obter detalhes de um script   |
| `create_script`  | Criar um novo script          |
| `update_script`  | Atualizar um script existente |
| `delete_script`  | Excluir um script             |
| `trigger_script` | Executar um script            |

### Tags (NFC/QR Code)

| Ferramenta          | Descrição                    |
| ------------------- | ---------------------------- |
| `list_tags`         | Listar todas as tags         |
| `create_tag`        | Criar uma nova tag           |
| `update_tag`        | Atualizar uma tag            |
| `delete_tag`        | Excluir uma tag              |
| `simulate_tag_scan` | Simular a leitura de uma tag |

### Dashboards

| Ferramenta              | Descrição                        |
| ----------------------- | -------------------------------- |
| `list_dashboards`       | Listar todos os dashboards       |
| `get_dashboard`         | Obter detalhes de um dashboard   |
| `create_dashboard`      | Criar um novo dashboard          |
| `update_dashboard`      | Atualizar um dashboard           |
| `delete_dashboard`      | Excluir um dashboard             |
| `add_card_to_dashboard` | Adicionar um card a um dashboard |

### Transferências

| Ferramenta        | Descrição                          |
| ----------------- | ---------------------------------- |
| `list_transfers`  | Listar transferências              |
| `create_transfer` | Criar uma transferência de recurso |
| `accept_transfer` | Aceitar uma transferência          |
| `reject_transfer` | Rejeitar uma transferência         |
| `cancel_transfer` | Cancelar uma transferência         |

### Organizações

| Ferramenta                        | Descrição                               |
| --------------------------------- | --------------------------------------- |
| `list_my_organizations`           | Listar suas organizações                |
| `get_organization_members`        | Listar membros de uma organização       |
| `create_organization`             | Criar uma organização                   |
| `invite_to_organization`          | Convidar membro para organização        |
| `list_pending_invitations`        | Listar convites pendentes               |
| `accept_organization_invitation`  | Aceitar convite de organização          |
| `decline_organization_invitation` | Recusar convite de organização          |
| `get_org_permissions`             | Obter permissões da organização         |
| `set_org_permissions`             | Definir permissões da organização       |
| `list_org_shares`                 | Listar compartilhamentos da organização |
| `share_resource_with_org`         | Compartilhar recurso com organização    |

### Suporte

| Ferramenta                  | Descrição                   |
| --------------------------- | --------------------------- |
| `list_support_tickets`      | Listar tickets de suporte   |
| `get_support_ticket`        | Obter detalhes de um ticket |
| `create_support_ticket`     | Criar um ticket de suporte  |
| `reply_support_ticket`      | Responder a um ticket       |
| `upload_support_attachment` | Enviar anexo em um ticket   |

### Produtos & Checkout

| Ferramenta                | Descrição                                               |
| ------------------------- | ------------------------------------------------------- |
| `list_products`           | Listar todos os produtos disponíveis no catalogo        |
| `get_product`             | Obter detalhes de um produto pelo ID                    |
| `list_my_products`        | Listar produtos adquiridos pelo usuário                 |
| `get_my_product`          | Obter detalhes de um produto do usuário pelo UUID       |
| `create_product_checkout` | Criar sessão de checkout Stripe para comprar um produto |

### Agendamento

| Ferramenta                       | Descrição                          |
| -------------------------------- | ---------------------------------- |
| `list_scheduling_event_types`    | Listar tipos de evento disponíveis |
| `get_available_scheduling_times` | Obter horários disponíveis         |
| `create_scheduling_link`         | Criar link de agendamento          |
| `list_scheduling_appointments`   | Listar agendamentos                |
| `cancel_scheduling_appointment`  | Cancelar um agendamento            |

## Conectando o Claude Code CLI

<Steps>
  <Step title="Adicionar o servidor MCP">
    Execute no terminal:

    ```bash theme={null}
    claude mcp add portal --transport streamable-http https://portal.unicontrol.me/v1/mcp
    ```
  </Step>

  <Step title="Autorizar o acesso">
    Na primeira vez que você usar uma ferramenta do Portal, o Claude Code abrira automaticamente o navegador para você fazer login e autorizar o acesso via OAuth.
  </Step>

  <Step title="Começar a usar">
    Agora você pode pedir ao Claude para controlar seus dispositivos diretamente:

    ```
    > Apague todas as luzes da sala
    > Crie uma automação que ligue o ar-condicionado às 18h
    > Qual o estado do sensor de temperatura do quarto?
    ```
  </Step>
</Steps>

## Conectando o Gemini CLI

<Steps>
  <Step title="Editar o arquivo de configuração">
    Adicione ao arquivo `~/.gemini/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "portal": {
          "httpUrl": "https://portal.unicontrol.me/v1/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Autorizar o acesso">
    Ao usar uma ferramenta pela primeira vez, o fluxo OAuth será iniciado no navegador.
  </Step>

  <Step title="Começar a usar">
    Use linguagem natural para controlar seus dispositivos pelo Gemini CLI.
  </Step>
</Steps>

## Conectando o OpenClaw

O [OpenClaw](https://openclaw.ai/) e um assistente pessoal de IA open-source que suporta MCP servers para estender suas capacidades.

<Steps>
  <Step title="Editar o arquivo de configuração">
    Adicione ao arquivo `~/.openclaw/openclaw.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "portal": {
          "url": "https://portal.unicontrol.me/v1/mcp",
          "transport": "streamable-http"
        }
      }
    }
    ```
  </Step>

  <Step title="Reiniciar o OpenClaw">
    Reinicie o gateway do OpenClaw para que a nova configuração seja carregada.
  </Step>

  <Step title="Autorizar o acesso">
    Na primeira interação com uma ferramenta do Portal, o fluxo OAuth será iniciado no navegador para autenticação.
  </Step>

  <Step title="Começar a usar">
    Agora você pode pedir ao OpenClaw para controlar seus dispositivos usando linguagem natural.
  </Step>
</Steps>

## Usando em Agentes Customizados

Você pode conectar qualquer agente ao Portal usando o SDK oficial do MCP.

### TypeScript

```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://portal.unicontrol.me/v1/mcp")
);

const client = new Client({
  name: "meu-agente",
  version: "1.0.0",
});

await client.connect(transport);

// Listar ferramentas disponiveis
const { tools } = await client.listTools();
console.log(`${tools.length} ferramentas disponiveis`);

// Chamar uma ferramenta
const result = await client.callTool({
  name: "get_all_states",
  arguments: {},
});
console.log(result);
```

### Python

```python theme={null}
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://portal.unicontrol.me/v1/mcp") as (
    read_stream,
    write_stream,
    _,
):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()

        # Listar ferramentas
        tools = await session.list_tools()

        # Chamar uma ferramenta
        result = await session.call_tool("get_all_states", {})
        print(result)
```

<Warning>
  Para agentes customizados, você precisara implementar o fluxo OAuth 2.1 manualmente ou fornecer um token de acesso válido nos headers da requisição.
</Warning>

## Exemplos de Uso

Aqui estão alguns exemplos de comandos em linguagem natural que um agente conectado ao Portal pode executar:

| Comando                                             | Ferramentas utilizadas                                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| "Apague todas as luzes"                             | `list_entities` → `call_service`                                                            |
| "Qual a temperatura do quarto?"                     | `get_entity_state`                                                                          |
| "Crie uma automação para ligar a luz ao por do sol" | `create_automation`                                                                         |
| "Liste meus dispositivos offline"                   | `list_devices`                                                                              |
| "Adicione um card de clima ao dashboard"            | `get_dashboard` → `add_card_to_dashboard`                                                   |
| "Execute o script de bom dia"                       | `list_scripts` → `trigger_script`                                                           |
| "Abra um chamado de suporte"                        | `create_support_ticket`                                                                     |
| "Agende uma visita técnica"                         | `list_scheduling_event_types` → `get_available_scheduling_times` → `create_scheduling_link` |

<Tip>
  Os agentes de IA entendem contexto. Você pode usar linguagem natural sem precisar saber o nome exato das ferramentas — o agente escolhe automaticamente quais ferramentas usar.
</Tip>