Integrar o seu serviço

O que é o OkMigo

Um amigo de IA com memória própria — e, para um negócio, quem opera o balcão junto.

O OkMigo é um assistente de IA pessoal. A diferença dele para os que você conhece não é o modelo: é que a memória fica com o usuário, num banco de dados nosso, e o modelo por trás é trocável. Ele lembra do que a pessoa contou semanas atrás, e a pessoa pode ler e apagar cada coisa que ele aprendeu.

Uma pessoa tem um amigo. Quem tem um comércio ganha também um sócio: um segundo assistente, cuja memória é a do negócio e não a de quem fala com ele. Vários funcionários podem operar o mesmo sócio, e ele sabe quem disse o quê.

Um dono de padaria abre o OkMigo e escreve "o fornecedor de farinha atrasou de novo". Isso vira memória do negócio. Meses depois ele pergunta "quantas vezes o moinho atrasou esse ano?" e ele responde. Não há formulário, não há cadastro, não há tela para configurar — ele conversa. É essa a experiência que a sua integração estende.

O que “integrar” significa, na prática

O seu sistema passa a ser operável por conversa, sem que o dono aprenda nada novo.

Hoje o sócio só sabe o que foi contado a ele. Ele não sabe quantos pedidos entraram, quem tem consulta amanhã, quanto tem em estoque — porque isso mora no seu sistema.

Quem executou foi o seu sistema, com a credencial daquele negócio. O dono não abriu o seu app, não aprendeu tela nova e não saiu da conversa — e continua sendo o seu produto que guarda o dado e manda nas regras.

Para você isso significa: mais uso do seu sistema, por um caminho que você não precisa construir nem manter. Você não escreve integração com a gente; você publica um servidor MCP e a gente fala com ele.

Como funciona por dentro

Você nunca fala com o modelo de IA. Você recebe uma chamada de função e devolve dado.

┌──────────────────────────────────────────────────────────┐
│  o dono do negócio conversa com o sócio dele no OkMigo   │
└───────────────────────────┬──────────────────────────────┘
                            │  o modelo decide que isso é
                            │  do serviço "AcmeCRM"
                            ▼
┌──────────────────────────────────────────────────────────┐
│  PONTE  ·  roda na NOSSA infraestrutura                  │
│  · valida os parâmetros contra o schema que VOCÊ declarou│
│  · pede confirmação ao dono se a operação escreve        │
│  · registra a chamada para o dono poder auditar          │
│  · não guarda nada do seu sistema                        │
└───────────────────────────┬──────────────────────────────┘
                            │  MCP sobre HTTP
                            │  Authorization: Bearer <credencial DELE>
                            ▼
┌──────────────────────────────────────────────────────────┐
│  O SEU SERVIDOR MCP  ·  na sua infraestrutura            │
│  na frente da sua API de sempre                          │
└──────────────────────────────────────────────────────────┘

A ponte é um serviço nosso. Ela traduz e esquece: não copia os seus dados, não mantém cache do seu catálogo, não tem banco. Cada negócio que passa a usar o seu serviço vira uma linha de configuração do nosso lado — não um deploy, não um código novo. É por isso que dizemos sim rápido.

O modelo de linguagem nunca fala com você. Ele escolhe qual função chamar e com quais argumentos; a ponte valida esses argumentos contra o schema que você publicou e só então faz a chamada. O que volta, quem interpreta e transforma em frase é o assistente — você devolve dado estruturado.

O que você precisa construir

Um servidor MCP na frente da API que você já tem. Nada mais.

MCP (Model Context Protocol) é um padrão aberto para expor funções a assistentes de IA. Ele existe em várias linguagens e é o mesmo protocolo usado por outras ferramentas do mercado — não é nada nosso.

Exigimos MCP por um motivo prático: ele se descreve sozinho. Seu servidor publica a lista de funções, com tipos e descrições, e a gente aprende tudo lendo essa lista. É o que permite integrar o seu serviço sem escrever uma linha de código específica para ele — e, portanto, sem você entrar numa fila de priorização nossa.

Para expor as funções, você não precisa: instalar SDK nosso, expor o seu banco, manter webhook, criar conta no OkMigo, assinar exclusividade, ou mudar a sua API. O servidor MCP fica na frente dela e chama o que já existe. O okmigo-cartao é opcional nessa etapa e passa a ser o caminho recomendado quando você também declara a tela do seu produto.

from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

mcp = MCPServer(
    "acmecrm",
    instructions=(
        "Ferramentas do AcmeCRM: clientes e pedidos de um negócio. "
        "Confirme com a pessoa antes de chamar qualquer ferramenta que grava."
    ),
)

SO_LEITURA = ToolAnnotations(read_only_hint=True)


@mcp.tool(annotations=SO_LEITURA)
async def buscar_cliente(nome: str) -> dict:
    '''Procura um cliente pelo nome, mesmo parcial ("ana", "ana paula").
    Devolve os que casaram, com id, telefone e cidade. Use antes de
    registrar um pedido, para descobrir o id do cliente.'''
    achados = await acme.clientes.search(nome)          # a sua API de sempre
    return {"clientes": [c.to_dict() for c in achados]}


@mcp.tool()
async def registrar_pedido(cliente_id: str, itens: list[str], observacao: str = "") -> dict:
    '''Cria um pedido para um cliente. SÓ CHAME depois que a pessoa
    confirmar — isto grava no CRM de verdade e não é desfeito pela conversa.

    cliente_id: o id devolvido por `buscar_cliente`.
    itens: lista de códigos de produto.
    observacao: texto livre opcional, vai no campo de observação do pedido.'''
    try:
        pedido = await acme.pedidos.create(cliente_id, itens, observacao)
    except acme.ClienteInexistente:
        return {"erro": "esse cliente não existe mais — busque de novo pelo nome"}
    return {"pedido_id": pedido.id, "numero": pedido.numero, "total": pedido.total}

Qualquer linguagem serve — o que importa é o que sai no protocolo, descrito na seção seguinte.

⚠️ Não há um serviço de exemplo público para você copiar, e é melhor dizer isso do que apontar um repositório que você não consegue abrir. O que está publicado é a peça que mais engana quando falta: o crivo da tela (okmigo-infra/cartao, Apache-2.0), que é o mesmo código que roda aqui dentro, com manifestos de exemplo e uma linha de comando que você aponta para o seu. O resto da especificação é esta página, inteira.

Os dois tipos de serviço — escolha antes de começar

A pergunta é só uma: de quem é a credencial que chega ao seu sistema.

Tudo o mais nesta página vale para os dois. Esta escolha muda uma coisa: como o seu sistema descobre de qual cliente se trata.

Como descrever as suas funções

A descrição é interface, não comentário: é lendo ela que o assistente decide te chamar.

Quando a ponte se conecta ao seu servidor, ela pede a lista de ferramentas (tools/list no protocolo). É esta resposta que vira o contrato:

{
  "tools": [
    {
      "name": "buscar_cliente",
      "description": "Procura um cliente pelo nome, mesmo parcial (\"ana\", \"ana paula\"). Devolve os que casaram, com id, telefone e cidade. Use antes de registrar um pedido, para descobrir o id do cliente.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "nome": { "type": "string", "description": "Nome ou parte do nome." }
        },
        "required": ["nome"]
      },
      "annotations": { "readOnlyHint": true }
    },
    {
      "name": "registrar_pedido",
      "description": "Cria um pedido para um cliente. SÓ CHAME depois que a pessoa confirmar — isto grava no CRM de verdade.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "cliente_id": { "type": "string", "description": "O id devolvido por buscar_cliente." },
          "itens":      { "type": "array", "items": { "type": "string" },
                          "description": "Códigos de produto." },
          "observacao": { "type": "string", "description": "Texto livre, opcional." }
        },
        "required": ["cliente_id", "itens"]
      }
    }
  ]
}

Escreva a descrição para um modelo de linguagem ler, não para um dev. Ela é o único material com que o assistente decide se aquela função serve. Diga quando usar, o formato de cada parâmetro, e principalmente o que a função não faz — é isso que evita que ele te chame na hora errada.

⚠️ E cuidado ao medir: dependendo da biblioteca, a descrição sai com a indentação do texto no seu código, e um cliente pode normalizá-la e outro não. Uma docstring que mede 587 caracteres na sua máquina chega aqui com 624 — e perde a última frase. Meça o que sai no tools/list, não o que você escreveu.

As primeiras linhas são o que mais pesa: ponha ali quando usar a função e, se houver, qual outra é a certa quando não for esta. É a informação que evita a chamada errada — e a primeira a se perder no corte se você a deixar para o fim.

Leitura ou escrita: anote

Sem a anotação, tratamos a função como escrita — e escrita para a conversa para pedir confirmação.

Toda função que muda alguma coisa passa por um portão do nosso lado: a primeira chamada não executa. O assistente descreve a ação à pessoa, termina o turno perguntando, e só depois do "sim" dela, numa mensagem seguinte, a chamada acontece de verdade.

Isso existe porque um modelo de linguagem, sozinho, dá "confirmado" sem ter perguntado — nós medimos isso acontecendo. O portão tira essa caneta dele: a confirmação é registro no nosso banco, não uma promessa do modelo.

Consequência para você: função sem readOnlyHint cai no lado seguro, o de escrita. Se você não anotar as leituras, "quantos pedidos entraram hoje?" vira "confirma que quer ver os pedidos de hoje?" — e a experiência fica ruim por um motivo que você resolve com uma linha.

"annotations": { "readOnlyHint": true }

Quando quem fala NÃO é o dono

O portão acima resolve "o dono confirma antes de gravar". Há um caso diferente: uma pessoa de fora pedindo alguma coisa ao negócio — marcar um horário, reservar uma mesa, segurar uma peça. Aí não basta confirmar: quem confirma teria de ser o dono, e ele não está naquela conversa.

Três coisas que a nossa primeira integração assim ensinou, e que não são óbvias antes de acontecerem:

1. O pedido precisa SEGURAR o recurso, com prazo. Sem segurar, duas pessoas pedem o mesmo horário e o dono aprova as duas — e o conflito só aparece com as duas na porta. Sem prazo, um pedido que ele nunca abrir tranca aquele horário para sempre.
2. O erro de "não disponível" não conta o motivo. Se o horário está tomado por outro pedido, isso é movimento da agenda de um negócio, e quem está de fora não recebe. Responda "não está disponível", nunca "há outro pedido".
3. A operação do dono não pode exigir um id. O assistente dele não deve mostrar identificadores a ninguém — então exigir um põe o modelo a improvisar. Aceite o que a pessoa reconhece (o nome de quem pediu, a hora), e com mais de um candidato devolva a lista em vez de escolher.

⛔ E o que não resolve: dar ao cliente as funções do dono com um aviso no texto. Descrição não é permissão — quem separa os dois lados é o conjunto de funções que cada um alcança.

Autenticação: uma credencial por cliente

Você descobre de qual negócio se trata pela credencial, nunca por um campo do pedido.

Cada negócio que usa o seu serviço através do OkMigo tem a própria credencial no seu sistema — a mesma que ele usaria para chamar a sua API diretamente. O dono a cadastra uma vez, na tela de instalação do OkMigo, e ela fica cifrada conosco. Toda chamada vai com ela:

POST /mcp HTTP/1.1
Host: mcp.acmecrm.com
Authorization: Bearer <a credencial da Barbearia do Zé>
Idempotency-Key: 7f3a9c21-4e0b-4a17-9f2e-1c8d5b6a0e33
Content-Type: application/json

{"jsonrpc":"2.0","id":42,"method":"tools/call",
 "params":{"name":"registrar_pedido",
           "arguments":{"cliente_id":"c_8812","itens":["PA-100","PA-220"]}}}

✅  Authorization: Bearer <credencial da Barbearia do Zé>
⛔  Authorization: Bearer <token do OkMigo>
    { "cliente": "barbearia-do-ze", ... }

Guardar a credencial é nossa responsabilidade: cifrada em repouso, nunca devolvida por nenhuma tela ou endereço nosso, nem para o próprio dono. Ele a remove quando quiser — removeu, o seu serviço para de responder para ele no mesmo instante.

OAuth funciona igual. Se o seu sistema usa OAuth com refresh token, a renovação fica do nosso lado e você recebe sempre um access token válido. Só precisamos do endpoint de refresh e do escopo mínimo.

⚠️ Peça o escopo mínimo. Uma credencial com acesso à conta inteira para uma integração que só registra pedido é risco que ninguém precisa correr — nem você, nem o seu cliente, nem nós.

A outra forma: uma credencial só, e o cliente vem de nós

Se você prefere integrar uma vez e receber todos os negócios por baixo de uma conta.

A seção anterior descreve a forma por cliente: cada negócio cadastra a própria credencial. É a mais forte, e é a que recomendamos — o vizinho não alcança o dado porque não TEM o segredo. Não depende de ninguém acertar.

Há uma segunda forma, para quando você quer uma integração só: uma credencial nossa, e o cliente identificado por um valor que nós mandamos. Ela exige uma coisa de você, e não é negociável.

POST /mcp HTTP/1.1
Host: mcp.acmecrm.com
Authorization: Bearer <a credencial do OkMigo>
X-OkMigo-Tenant: t_9c2f1ab47e0d5836
Content-Type: application/json

Vai num CABEÇALHO, não num parâmetro — e pela mesma razão da seção anterior: parâmetro é texto que um modelo de linguagem compõe. Quem põe esse cabeçalho é a nossa ponte, no servidor, derivando de (o seu serviço × o negócio). O modelo não vê o valor, não escolhe e não alcança. A garantia é idêntica à da credencial.

O que o valor é: uma string opaca, estável para sempre para aquele negócio no seu serviço. Não é nome, não é e-mail, não é um id nosso.

⚠️ Não tente interpretá-lo, e não peça mais nada. Ele é deliberadamente sem significado — inclusive porque o mesmo negócio tem um valor diferente em cada serviço. Isso é de propósito: se fosse o mesmo, dois integradores cruzariam as listas e descobririam que a Barbearia do Zé é a mesma nos dois. Um identificador que atravessa fornecedores é rastreamento, e não vamos construir um.

Nesta forma o cliente nasce da primeira chamada — e nasce sem nada dentro. Uma agenda sem serviços cadastrados não consegue marcar horário; um estoque sem produtos não consegue dar baixa.

Na prática: se você expõe criar_agendamento, exponha também o que ele pressupõe — criar_servico, definir_horario, o que for. Escrita, sem readOnlyHint, e nós pedimos confirmação antes de chamar, como em qualquer outra.

⚠️ Se a configuração inicial tiver mesmo que acontecer no seu painel, tudo bem — mas então diga isso na resposta. Um estado vazio que devolve {"servicos": []} e mais nada faz o assistente concluir que o negócio não tem serviços. Devolva um erro que ensina: onde ir, e o que fazer lá. Ver "O que devolver, e como errar".

Para o seu sistema, o OkMigo vira um cliente só. Isso tem três consequências reais:

• Limite e cobrança são nossos, não de cada negócio. Se você cobra por uso, cobra de nós.
• Se você limitar ou bloquear, bloqueia todos juntos — não dá para suspender um negócio sem suspender o resto, a menos que você trate o identificador como conta de verdade.
• A isolação passa a ser uma promessa sua. Na forma por cliente ela é estrutural; aqui, se os dados se misturarem do seu lado, nem nós nem o dono temos como perceber — os dados voltam certos até o dia em que voltam errados.

Idempotência

É a única coisa que pedimos que você guarde.

Toda chamada leva um cabeçalho Idempotency-Key com um identificador único daquela operação. Se você receber a mesma chave duas vezes, devolva o mesmo resultado e não execute de novo.

Idempotency-Key: 7f3a9c21-4e0b-4a17-9f2e-1c8d5b6a0e33

Sem isso, uma resposta perdida na rede vira dois pedidos idênticos no CRM ou dois agendamentos no mesmo horário — e quem vai reclamar é o seu cliente, do seu produto. Guardar a chave e a resposta por 24 horas cobre qualquer retentativa nossa.

Funções de leitura podem ignorar o cabeçalho.

O que devolver, e como errar

Erro é dado, não exceção — e a mensagem vai ser lida por um assistente no meio de uma conversa.

Devolva sempre um objeto, nunca uma frase pronta: quem escreve a frase para a pessoa é o assistente, e ele precisa dos campos. Sem HTML, sem markdown, sem texto de interface.

{ "pedido_id": "p_44120", "numero": 4412, "total": 189.90 }

{ "erro": "esse cliente não existe mais — busque de novo pelo nome" }
{ "erro": "esse horário acabou de ser ocupado — peça outro horário à pessoa" }
{ "erro": "produto PA-220 está fora de linha — pergunte se pode trocar por outro" }

Repare que cada mensagem diz o próximo passo. É a diferença entre o dono ouvir "não consegui falar com o sistema" e ouvir "esse horário acabou de ser ocupado, quer as 11h?".

HTTP 500 Internal Server Error
{"detail": "NullPointerException at OrderService.java:412"}

Uma exceção de protocolo, ou um erro escrito para o seu log, chega à pessoa como "não consegui" e ela fica sem saber o que houve. Erros de negócio são resultado — devolva 200 com {"erro": "..."}. Reserve os códigos HTTP para o que é de fato falha de infraestrutura.

Prazo: responda em até 10 segundos. Passou disso, o assistente segue a conversa sem o seu resultado — ele nunca deixa a pessoa esperando por um serviço externo. Ficar fora do ar é esperado, não excepcional: não quebramos e não ficamos tentando; o assistente diz que não conseguiu e a pessoa tenta de novo.

A sua TELA dentro do OkMigo

Você descreve a estrutura; quem escolhe a aparência somos nós.

Um serviço integrado não fica só disponível para o assistente: ele ganha um ícone e uma tela dentro do OkMigo. Quem descreve essa tela é você — ninguém aqui sabe o que é um pátio de revenda ou uma agenda de tatuador.

A tela é declarada como um Adaptive Card, num subconjunto. Você pode escrever esse JSON diretamente ou usar o SDK Python do okmigo-cartao. O SDK é autoria tipada: ele ajuda a montar a tela, mas não abre uma segunda porta nem afrouxa o contrato.

código Python com o SDK
        ↓  tela.compilar() ou aplicativo.compilar()
manifesto/cartão JSON restrito
        ↓  crivo de segurança do OkMigo
JSON validado e reconstruído
        ↓  renderer do OkMigo
tela Web ou Flutter

O Python não gera HTML, CSS nem componentes Flutter. Ele descreve a intenção — título, texto, busca, tabela e ações permitidas — e compila isso para o mesmo JSON que você poderia escrever à mão:

from okmigo_cartao import Busca, Navegacao, Tela, Tema

tela = Tela(
    titulo="Meus ativos",
    tema=Tema.MERCADO,
    navegacao=Navegacao.INFERIOR,
    componentes=(
        Busca(
            id="ticker_busca",
            campo="ticker",
            rotulo="Ativo da B3",
            placeholder="Digite PETR4",
            sugestoes_por="buscar_ativos",
        ),
    ),
)

cartao_json = tela.compilar()

compilar() termina o trabalho do SDK; dali em diante, a fronteira é o JSON. O OkMigo recebe esse JSON, descarta ou recusa o que não é permitido e desenha com os próprios componentes. Por isso, o serviço controla conteúdo, estrutura, dados e capacidades; o OkMigo controla aparência, responsividade, acessibilidade e temas. O mesmo contrato serve ao renderer Web e ao Flutter.

O catálogo já cobre estrutura responsiva, texto, métricas, fichas, formulários, campos de texto e número, escolhas em lista/cards/busca, autocomplete remoto, arquivos, documentos, imagens, estados e etapas, repetição de dados, calendário, gráficos, progresso, cronômetro e blocos financeiros. Padrões recorrentes são composições Python dessas primitivas; não viram tipos novos nem ampliam a fronteira de segurança.

Durante o desenvolvimento, nem é preciso gravar o JSON no disco: o preview pode receber arquivo.py:APLICATIVO, chamar compilar() e mostrar todas as telas com navegação, desktop, celular e temas claro/escuro:

python -m okmigo_cartao preview telas.py:APLICATIVO \
    --dados dados-do-preview.json \
    --host 0.0.0.0 --port 4173

O JSON continua sendo o artefato que você registra e a fronteira que o produto consome. O preview só encurta o ciclo até ele.

• Início rápido completo — instale o pacote, declare Aplicativo, abra todas as superfícies no preview e materialize o JSON que será registrado.
• Catálogo do SDK por intenção — encontre o componente Python para formulários, busca, menus, cartões clicáveis, agenda, mídia, tabelas e estados.
• SDK Python e preview — escreva componentes tipados, compile o aplicativo inteiro e veja antes como o OkMigo reconstruirá o JSON. O catálogo e as regras de extensão ficam em docs/CATALOGO-SDK.md.
• Designer — monte o cartão arrastando e copie o JSON, se preferir autoria direta.
• Schema Explorer — cada elemento com todas as propriedades. É onde conferir o que size ou width aceitam.
• Documentação da Microsoft — a referência completa, incluindo o que existe além do que aceitamos.
• O crivo vem no mesmo pacote: é o código que reconstrói a sua tela aqui dentro, rodando na sua máquina. É com ele que você descobre o que vai sumir, antes de registrar — ver Rode o crivo antes de registrar, no fim desta seção.

⚠️ O Designer mostra o cartão com a aparência dele. A sua tela vai sair com a nossa — o que ele serve para conferir é a estrutura, nunca a cor.

TextBlock        size: small|default|medium|large|extraLarge
                 weight: lighter|default|bolder · isSubtle · wrap
Container        style: default|emphasis|accent|good|attention|warning · items · isVisible · id · minHeight
                   accent: a caixa PREENCHIDA com o acento, texto invertido — a
                   «porta recomendada»; good/attention/warning: o TOM da caixa (o
                   estado do que ela carrega — um véu da cor de estado do tema)
                 selectAction: Action.ToggleVisibility (a caixa inteira é o toque)
                 okmigoGrade: true (grade de ~210px) | "larga" (máx. 2 por linha,
                   cada filho é um cartão inteiro) | "compacta" (~150px, o máximo
                   que couber — é a única que dá DUAS colunas num telefone)
                   | "etiquetas" (os filhos viram CHIPS do tamanho do próprio texto)
                 okmigoSobreposto: true (sai do fluxo e aparece por cima)
ColumnSet        columns[] → Column (width: auto|stretch)
FactSet          facts[] → { title, value }
Table            columns[] → { width: N } (proporção) · firstRowAsHeader · showGridLines
                 rows[] → TableRow → cells[] → TableCell { items }
Image            height: small|medium|large|stretch · altText
Input.Text       id · campo · label · value · placeholder · isMultiline · isRequired
Input.Number     idem, e o cliente impede vírgula onde é ponto
Input.ChoiceSet  choices[] → { title, value, okmigoNota, okmigoIcone } · isRequired
                 okmigoQuemOpera: true  as opções são QUEM OPERA o negócio, e
                                        quem as preenche somos NÓS — ver abaixo
                 style: "filtered"  typeahead que deixa DIGITAR por cima
                 style: "filtered" + okmigoEstrito: true
                                    BUSCA: filtra, e só aceita o que está na lista
                 style: "expanded"  desenha as opções como FICHAS tocáveis
                                    (curtas = PÍLULAS; com nota/ícone = TILES com selo ✓)
ActionSet        actions[] → Action.ToggleVisibility · Action.Submit { data.operacao }
                              · Action.Execute { data.operacao } (consulta)
                 style: "positive" (o gesto principal: ocupa a linha)
                 style: "destructive" (destrói algo: outra família de cor)
                 mode:  "secondary" (secundário: vira link)
                 okmigoRodape: true (o bloco fica PRESO ao pé da tela enquanto a
                   caixa dele estiver à vista — o CTA de rodapé de um app)
okmigoArquivo    a ENTRADA de um arquivo — ver «Documentos», abaixo
okmigoDocumento  um arquivo seu, para ver na tela ou baixar — idem
okmigoCopiar     { rotulo, valor } — um botão que copia o valor (código de barras, chave Pix)
okmigoGrafico    { forma: barras|linha, titulo, series[], pontos[] } — a grade vira desenho
okmigoAutorizar  { rotulo, motivo, url } — a ida ao SEU site para a pessoa autorizar
okmigoCalendario { vista, de, eventos[], acoesDoEvento[] } — um mês, e o que há nele
okmigoCronometro { rotulo, segundos } — contagem REGRESSIVA (1 s … 3600 s)
okmigoProgresso  { feito, de, rotulo } — quanto do caminho já andou

{ "type": "Input.ChoiceSet", "id": "prof", "campo": "nome",
  "label": "Quem atende", "okmigoQuemOpera": true, "style": "expanded" }

⭐ As opções em FICHAS (style: "expanded") existem porque a única ação de toque deste contrato é ToggleVisibility, e ela não carrega VALOR. Sem elas, "toco para escolher e depois confirmo" não era declarável: uma fileira de "2 3 4 5 6" tinha de ser uma lista suspensa, ou cada opção tinha de ser um Submit que grava na hora. A ficha é o mesmo Input de sempre — viaja no mesmo Submit, com o mesmo escopo — só desenhado por inteiro. O okmigoNota é a linha de apoio de cada opção, e só aparece nessa forma.

⭐ TELAS que se sucedem não são um recurso: são caixas com id e ToggleVisibility COM SINAL ({elementId, isVisible}) — tocar um cartão mostra a próxima caixa e esconde a atual, e «‹ voltar» é o mesmo gesto ao contrário. Zero escrita, zero ida ao servidor; quem grava é o botão de rodapé (okmigoRodape) de cada tela, e cada escrita reconstrói a superfície no passo seguinte. Este contrato não tem navegação, e não precisa ter uma para isso.

⭐ A ÊNFASE diz o PESO do gesto, nunca a cor. Você declara "este é o principal" ou "este destrói algo"; qual violeta ou qual vermelho isso vira é do cliente, como todo o resto deste vocabulário — é por isso que o color do TextBlock continua sendo descartado. Botão sem marca sai como sempre saiu.

⚠️ okmigoProgresso recebe feito e de, nunca uma porcentagem. "4 de 6" é o que a pessoa quer saber; o "67%" se deriva daí, e o contrário não. de zero derruba o bloco (dividiria por zero) e um feito fora da faixa é prensado, não recusado.

⭐ okmigoAutorizar é a única saída para um endereço seu, e existe porque o Open Finance só funciona assim: quem pergunta a senha do banco é o banco. Não é um link livre — o crivo recusa o que não for https, o que trouxer credencial embutida ([email protected]), porta fora da 443, IP cru, ou um host nosso; e aceita um por cartão. O motivo é obrigatório e o host é desenhado ao lado do botão: quem vai tocar lê para onde vai. Um botão só com "continuar" é o que faz alguém sair no escuro.

⚠️ O endereço viaja no dado, nunca no molde: token de autorização vence em minutos, e molde congela na instalação.

⚠️ Esta lista já disse "só ToggleVisibility" enquanto o Submit estava aceito há dias. O que vale é o crivo — e ele é público, então você não precisa acreditar nesta página: okmigo-infra/cartao. O texto aqui é conferido contra ele, e quando divergirem, é o texto que está errado.

Elemento fora dessa lista some — a menos que você diga o que aparece no lugar, com o fallback do próprio schema. Use-o. É a diferença entre a sua tela degradar do jeito que você escolheu e degradar do jeito que o acaso escolher.

{ "type": "Table", …,
  "fallback": { "type": "TextBlock", "wrap": true, "isSubtle": true,
                "text": "Nenhum agendamento para hoje. Quando alguém marcar, aparece aqui." } }

"fonte": {
  "resumo": { "operacao": "resumo_do_estoque" },
  "lista":  { "operacao": "buscar_veiculos",
              "pedido": { "incluir_indisponiveis": true },
              "caminho": "veiculos" }
}

⛔ São essas duas chaves, e só elas. Uma fonte com qualquer outro nome faz a superfície ser recusada, com uma mensagem dizendo qual chave não existe. Não é rigor: antes ela era ignorada em silêncio, e o efeito era pior que um erro — a tela abria com os campos vazios, sobre dado que existia do outro lado. Num formulário, quem apertasse Salvar apagaria o que estava gravado.

Duas funções de leitura suas. Nós as chamamos com a credencial e o cliente certos — a mesma travessia de sempre — e preenchemos os {campo} do cartão com a resposta. {marca}, {preco_reais}, {total}. Campo que você parar de mandar vira vazio, nunca a chave crua na tela.

Uma lista de coisas com as mesmas colunas — documentos, cobranças, o ano mês a mês — é uma Table, não uma pilha de ColumnSet: só ela alinha as colunas entre as linhas. A largura é proporção (width: 2 é o dobro de 1), a primeira linha é o cabeçalho, e no celular quem decide se a tabela vira fichas empilhadas somos nós — você declara a estrutura.

Cada item da lista repete um bloco, marcado assim:

{ "_repetir_lista": { "type": "Container", "items": [ … ] } }

E, quando o bloco não deve repetir para todos os itens, um _quando ao lado escolhe quais:

{ "_repetir_lista": { "title": "{marca} {modelo}", "value": "{id}" },
  "_quando": { "campo": "situacao", "em": ["retirado"] } }

Um operador só: o campo está entre estes valores. Ele existe porque uma superfície tem uma lista, e um formulário costuma precisar de um recorte dela — uma lista suspensa de "devolver ao pátio" que oferece o estoque inteiro faz o seu serviço recusar opção por opção, e quem usa conclui que a tela está quebrada. A comparação é por texto, com espaços aparados, e campo que não existe na sua resposta não casa: você vê a lista vazia na tela, que é o sinal certo para um erro de digitação no manifesto. Forma diferente desta é ignorada — a lista sai inteira em vez de sair errada.

Se o recorte que você precisa não cabe nisso, ele é seu: declare a fonte já peneirada. Nós não vamos ganhar operadores aqui.

{ "type": "ActionSet", "actions": [
  { "type": "Action.ToggleVisibility", "title": "O pátio",
    "targetElements": [ { "elementId": "aba_patio", "isVisible": true },
                        { "elementId": "aba_numeros", "isVisible": false } ] } ]}

Action.ToggleVisibility não alcança nada: mostra e esconde blocos que já vieram no mesmo cartão. Action.OpenUrl é descartado — é um endereço escolhido por você dentro do aplicativo de outra pessoa.

{ "type": "Container", "items": [
  { "type": "Input.Text", "id": "placa_nova", "campo": "placa", "label": "Placa" },
  { "type": "ActionSet", "actions": [
    { "type": "Action.Submit", "title": "Salvar", "data": { "operacao": "criar_veiculo" } } ] } ] }

Action.Submit nomeia uma operação de escrita do seu contrato — nunca uma URL — e o botão manda os campos da mesma caixa para ela, pela nossa rota, com a credencial e o cliente certos. Operação que não está no seu contrato recusa a tela inteira: botão que aparece e não grava faz a pessoa culpar o produto. O id do campo é único no cartão (é a chave do estado no aparelho); o campo é o nome do argumento na sua função, e pode repetir entre caixas — 42 formulários, um por dia, todos chamando criar_bloqueio(quando, …).

Action.Execute é o par de leitura: envia os campos da mesma caixa para uma operação de consulta e recebe outra ficha declarativa. A resposta atravessa o mesmo crivo antes de substituir o cartão atual; uma operação que não esteja nas leituras do contrato recusa a tela inteira.

{ "tipo": "ponte",
  "slug": "acmecrm",
  "endpoint": "https://mcp.acme.com.br/mcp",
  "descricao": "Os clientes e os pedidos da Acme: buscar, criar e acompanhar.",
  "forma": "do_operador",
  "credencial_sondagem": "...", "tenant_sondagem": "...",
  "para_tipo": "socio", "versao": "0.3.0",
  "superficies": [ { "nome": "patio", "titulo": "O pátio",
                     "hint": "os carros do seu estoque",
                     "fonte": { ... }, "cartao": { ... } } ] }

Authorization: Bearer <credencial_sondagem>
X-OkMigo-Tenant: <tenant_sondagem>

⚠️ A sondagem não é detalhe. Toda capacidade que nomeia uma operação — eventos, avisa_antes, relata_mudancas, convite, quer_a_marca, aceita_contato — é conferida contra o contrato que lemos do seu servidor na hora de registrar, e o que não estiver lá é descartado em silêncio. Não é erro: é a capacidade simplesmente não existir depois, sem nada para procurar. Se a operação ainda não nasceu, ela passa a valer sozinha no dia em que nascer e o registro for refeito.

Uma chave opcional muda o que o assistente enxerga:

"conversa": ["o_que_falta", "recebidos", "marcar_entregue"]

E uma marca no schema de um parâmetro, como a da foto (x-okmigo-foto): "codigo_barras": { "type": "string", "x-okmigo-pagamento": true } diz que o campo é dinheiro para pagar — linha digitável, Pix copia-e-cola. Sem a marca, o nosso filtro de privacidade barraria 47 dígitos como se fossem um CPF, e a guia não chegaria ao cliente.

conversa é a lista das operações que o assistente vê falando com a pessoa. Sem ela, entram todas — e um contrato de trinta operações põe trinta schemas em cada turno, o que estoura o contexto do modelo. A tela continua usando o contrato inteiro; a conversa usa o que faz sentido dizer em voz alta.

⭐ E há outras chaves, que ligam o seu serviço ao resto do OkMigo — a agenda, o lembrete, o contato de quem instalou você. Elas são a seção seguinte, e valem uma leitura antes de você decidir o que construir.

Versione esse arquivo junto do seu código. Quando uma função sua ganhar um campo, quem precisa lembrar de mostrá-lo na tela é quem o acrescentou — e ele está no seu repositório, não no nosso.

⚠️ Nenhum segredo nele. A credencial entra no gesto de registrar.

O crivo é o código que lê o seu cartão aqui dentro e o reconstrói no vocabulário do OkMigo, descartando o que não conhece. Ele está publicado sob Apache-2.0, sem dependência nenhuma, e é o mesmo que roda em produção — a API do OkMigo instala esse pacote:

git clone https://github.com/okmigo-infra/cartao.git
cd cartao
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

python -m okmigo_cartao preview exemplos/sdk_catalogo.py:APLICATIVO

Depois, abra o seu aplicativo inteiro:

python -m okmigo_cartao preview \
    okmigo/gerar_manifesto.py:APLICATIVO \
    --dados okmigo/examples/preview.dados.json

Para investigar uma superfície do JSON já materializado em baixo nível:

python -m okmigo_cartao okmigo/manifesto.json --superficie extrato \
    --dados dados.json --escrituras marcar_pago,estornar --html saida.html

Ele responde três perguntas, e a segunda é a que você não tinha como fazer antes:

Passou?

ou qual regra recusou a tela inteira, com o nome.

O que sumiu?

O modo de falha desta plataforma quase nunca é erro — é a tela abrir sem o pedaço, com tudo respondendo 200. O relatório nomeia cada tipo que entrou e não saiu, e cada chave lida e descartada, com o motivo de cada uma.

Como fica, pelado?

--html escreve o cartão reconstruído em HTML sem uma linha de CSS. O feio é intencional: se o documento pelado não faz sentido, nenhuma aparência conserta.

--escrituras e --leituras são as operações que o seu servidor MCP expõe. Sem elas os botões não são conferidos, e a ferramenta avisa em vez de dizer que passou — um Action.Submit nomeando operação fora do seu contrato recusa a tela inteira, e é o erro mais caro de descobrir depois de registrar.

O contrato de cada tipo — o que ele aceita, o que evapora e por quê — está no CONTRATO.md do repositório, mais longo que esta seção. E se a sua tela não couber no vocabulário, o caminho é um PR ali: o README diz as quatro coisas que um elemento novo precisa trazer junto, e a primeira é a tela real que não cabe hoje. Elemento nasce de observação, não de ideia.

O que já existe aqui — não construa de novo

A agenda, o lembrete e a tela já estão no OkMigo. Você declara; quem executa somos nós.

O erro mais caro de quem integra não é escrever a função errada — é construir de novo o que já existe deste lado. Uma agenda própria, um mecanismo de notificação, uma tela com a sua paleta. Cada uma dessas coisas já está aqui, e o seu serviço alcança todas declarando uma capacidade no manifesto. Quem executa é o OkMigo.

O OkMigo tem uma agenda, e ela vem instalada em toda conta: não é um app que alguém escolheu, e não se remove — quem não quer ver, oculta. Se o seu serviço tem datas — um prazo, um vencimento, uma entrega, uma revisão —, elas aparecem lá sem você desenhar um calendário.

"eventos": { "operacao": "eventos", "parametro": "dias" }

A operação é de leitura, recebe a janela em dias e devolve:

{ "eventos": [
  { "id": "1c3f", "inicio": "2026-10-14T09:00:00-03:00", "status": "ativo",
    "titulo": "Renovar o acesso ao banco",
    "detalhe": "Sem renovar, o extrato para de atualizar." } ] }

Nós varremos, e para cada conta que tem o seu serviço e a agenda anotamos o compromisso lá dentro, com a credencial daquela conta. O que você precisa saber antes de escrever isso:

• ⛔ A operação tem de ser pura — perguntar duas vezes devolve o mesmo. Quem lembra o que já foi anotado somos nós, por uma assinatura de inicio + titulo + detalhe: mudou, o compromisso é refeito; não mudou, nada acontece. Você não ganha estado, fila nem noção de "já mandei".
• O compromisso dura 30 minutos e ocupa a grade. Um prazo não tem hora, e a agenda só sabe guardar coisa que ocupa horário — o custo é o dia de quem atende parecer mais cheio do que está, e foi escolhido assim.
• Remarcar é remover e anotar de novo: a agenda não tem "editar" no contrato. Para você isso é invisível — mude o inicio e devolva.
• status diferente de "ativo" sai da agenda, e o que sair da janela também. Entregue ou dispensado não pode continuar lá parecendo pendência.
• Item sem id ou sem inicio é descartado em silêncio: sem identidade estável não há como não duplicar.
• A varredura é lenta de propósito. Um prazo é sobre daqui a dias, e perguntar de cinco em cinco minutos a cada serviço, por conta, gastaria chamada por nada.

"avisa_antes":     { "operacao": "a_avisar",  "parametro": "janela_minutos" },
"relata_mudancas": { "operacao": "mudou",     "parametro": "janela_minutos" }

avisa_antes declara uma operação pura de leitura que responde "o que venceu para avisar desde a sua última passada": recebe a janela em minutos e devolve { "avisos": [ { "id", "tipo", "inicio", "titulo", "detalhe" } ] }. Nós a chamamos a cada cinco minutos para cada negócio que instalou o seu serviço, lembramos o que já tocou (por tipo:id + inicio) e tocamos no bolso da pessoa.

relata_mudancas é a irmã dela e responde "o que mudou", em { "mudancas": [ { "id", "inicio", "status" } ] }. Serve o caso que o seu sistema não tem como resolver sozinho: alguém marcou um horário com aquele negócio através do OkMigo, e quem precisa saber que foi confirmado, remarcado ou cancelado é essa pessoa — que do seu lado é só um nome em texto. Você relata o fato; quem sabe a quem contar somos nós.

• ⛔ Você não ganha relógio, fila nem noção de notificação, e não deve: as duas são puras, e perguntar duas vezes devolve o mesmo.
• ⚠️ relata_mudancas só é perguntada a quem tem alguém esperando notícia. Um negócio sem nenhum horário nosso em aberto não é consultado — perguntar seria tráfego de robô no sistema de outra empresa, de cinco em cinco minutos, para sempre.
• ⚠️ Compare instante, não texto. 2026-09-08T14:00-03:00 e 2026-09-08T17:00+00:00 são o mesmo momento. Do nosso lado isso já foi um defeito real: com a comparação em texto, toda passada concluía "mudou de horário" e a pessoa recebia o aviso de cinco em cinco minutos — com a hora certa, o que a fazia acreditar.

"propoe_na_vitrine": { "operacao": "o_que_mudou",
                       "parametro": "desde_minutos" }

Todo negócio tem uma página pública no OkMigo, e o que ela mostra é o que aquele negócio oferece. Se o seu serviço é onde isso muda — o preço mudou, entrou um serviço novo, abriu disponibilidade —, você pode propor essa mudança sem que o dono redigite nada.

A operação é de leitura, recebe a janela em minutos e devolve:

{ "novidades": [
  { "id": "svc-31", "titulo": "Corte + barba",
    "detalhe": "1h, R$ 60" } ] }

• ⛔ O id é obrigatório e tem de ser estável — é por ele que a gente sabe que já propôs aquilo. Sem ele, a novidade é descartada.
• ⭐ Mas mudar o TEXTO propõe de novo. Corrigiu o preço do mesmo serviço? Mesmo id, texto novo: entra outra proposta. É a assinatura do conteúdo que decide, não só a chave.
• A varredura é lenta, e mais que as outras: cada novidade custa uma leitura do modelo do negócio. O que se oferece muda devagar.
• Proposta que o assistente recusar não volta na passada seguinte — perguntar de novo para sempre gastaria por nada.

"publico": { "ofertas":    "listar_servicos",
             "expediente": "listar_expediente" }

O irmão do de cima, com a diferença que é a coisa toda: aqui você não propõe, você publica. Cada chave é uma categoria de informação pública e o valor é a leitura por onde ela vem. O que voltar aparece na página do negócio, e o que sumir da sua lista sai da página.

As categorias são nossas e fechadas — chave que não estiver na lista é descartada em silêncio, e categoria nova exige que a nossa página saiba desenhá-la:

• ofertas — o que o negócio oferece. Itens com nome e, se houver, duracao e preco.
• expediente — que horas ele atende. Itens com dia, inicio e fim; dia sem hora é fechado, e nós escrevemos «fechado» — omitir o dia diria outra coisa.

{ "servicos": [ { "nome": "Corte + barba", "duracao": "1h", "preco": "R$ 60" } ] }
{ "expediente": [ { "dia": "Segunda", "inicio": "09:00", "fim": "18:00" },
                  { "dia": "Domingo" } ] }

• ⛔ Aqui vale a mesma regra do que é do NEGÓCIO e não do CLIENTE — com mais força, porque isto vai ao ar sem ninguém no meio. Nome de cliente, telefone, fila do dia: nada disso é informação pública do negócio.
• ⭐ Lista vazia não apaga nada. Se a sua leitura devolver vazio, a gente não mexe: um erro interno do seu lado não pode esvaziar a página de um negócio. Esvaziar de propósito é o dono remover o serviço.
• ⛔ O que o dono apagou não volta. Se ele apagou uma linha na tela da vitrine dele, ela fica apagada, mesmo que você a mande de novo. É a única resposta que ele já deu por escrito.
• ⚠️ Parou de declarar, parou de publicar. Tirar a chave do manifesto e re-registrar tira aquela informação do ar na varredura seguinte.
• A varredura é lenta: cardápio e horário não mudam de cinco em cinco minutos.

"marca_horario": { "operacao": "pedir_horario",
                   "ofertas":  "listar_servicos" }

Se o seu serviço marca hora, declare isto. A primeira operação é a que recebe o pedido; a segunda é a leitura que lista o que você atende — e é ela que faz o roteamento funcionar.

No eventos, um campo a mais muda o que a pessoa vê:

{ "eventos": [
  { "id": "1c3f", "inicio": "2026-09-13T14:00:00-03:00", "status": "ativo",
    "titulo": "Ana · Corte", "detalhe": "…",
    "quem": "Beatriz Nunes" } ] }

O quem é o nome de quem vai atender — o mesmo que você recebeu de nós pelo okmigoQuemOpera. Com ele, quem atende passa a ver na própria agenda que aquele tempo está tomado:

na agenda do NEGÓCIO   Ana · Corte · Beatriz Nunes — confirmado
na agenda da PESSOA    ocupado · Padaria do Bairro

"aceita_contato": { "operacao": "definir_a_vitrine",
                    "parametro": "onde_falam_com_a_loja",
                    "rotulo": "rotulo_do_botao" },
"quer_a_marca":   { "operacao": "definir_a_marca",
                    "nome": "nome", "logo": "logo" },
"convite":        { "operacao": "ligar_os_lados",
                    "parametro": "tenant_de_quem_convidou" },
"so_por_convite": true

aceita_contato

Na primeira instalação mandamos o endereço público do negócio (https://okmigo.com/@handle) e um rótulo pronto — para a sua tela não pedir à dona que digite de novo o que o OkMigo já sabe. ⛔ Só sócio com @, nunca uma conta de pessoa: negócio quer ser encontrado, pessoa não. ⭐ E é o @, nunca o telefone — é o endereço que o produto controla, já público por escolha dela, e que continua valendo se ela trocar de número. ⚠️ Só na primeira vez: reinstalar não sobrescreve o que ela tiver ajustado à mão do seu lado.

quer_a_marca

O nome e o logo de quem instalou, para a sua tela sair com a cara dele em vez da nossa. ⚠️ O tema continua sendo o do OkMigo; o que entra é quem está do outro lado.

convite · so_por_convite

Para quando o seu serviço é uma relação entre dois lados — um escritório e o cliente dele, um profissional e a pessoa que ele atende. Com so_por_convite, ninguém instala passando pela lista; a porta é o convite. Quando o convidado aceita, chamamos a sua operação no contexto de quem aceitou, passando o tenant de quem convidou e o apelido dele. ⭐ Três lados? Cada slug declara o SEU convite com o par que o outro lado instala. Se o convite saiu de um lado que não é o par declarado por quem aceitou (um nutricionista convidando para o mesmo app do aluno que o personal usa), vale a declaração de quem convidou: a operação dele, e o tenant dele sob o slug dele — desde que o par dela aponte para o slug que o convidado instalou. ⛔ Nunca e-mail, handle ou id de conta — os dois tenants são nomes que o seu serviço cunhou, e não significam nada fora dele. ⚠️ Falhar aqui não desfaz o aceite: o serviço já está instalado, e a relação pode nascer pela sua tela.

• A tela — você declara a estrutura, nós desenhamos. Sem cor, sem fonte, sem pixel, e igual nos dois clientes.
• Os documentos — somos o correio, você é o cofre. Não construa armazenamento para trafegar arquivo com o cliente.
• As imagens — quem hospeda somos nós; você guarda a URL.

Documentos: nós somos o correio, você é o cofre

O arquivo de um cliente seu passa por aqui e não fica. Nem um byte.

Uma guia, uma nota fiscal, um contrato, um extrato. Diferente da foto da seção seguinte — que é pública e nossa —, o documento é do seu cliente, tem valor legal e mora no seu armazenamento. O OkMigo o leva de um lado ao outro e o esquece: nada em disco, nada em tabela, e a nossa trilha registra nome, tipo e tamanho — nunca o conteúdo. Nenhum modelo de linguagem o vê, em nenhum dos dois sentidos.

{ "type": "Container", "items": [
  { "type": "Input.Text", "id": "vinc_{id}", "campo": "vinculo_id", "value": "{id}", "isVisible": false },
  { "type": "okmigoArquivo", "id": "arq_{id}", "campo": "arquivo", "label": "O documento",
    "aceita": ["pdf", "imagem", "xml"], "maxBytes": 10485760, "isRequired": true },
  { "type": "ActionSet", "actions": [
    { "type": "Action.Submit", "title": "Enviar", "data": { "operacao": "receber_arquivo" } } ] } ] }

okmigoArquivo é chave nossa — o Adaptive Cards não tem Input.File. Ele abre o seletor de arquivo do aparelho, e no Submit a sua operação de escrita recebe, no campo declarado, este objeto:

"arquivo": { "nome": "extrato-agosto.pdf", "tipo": "application/pdf",
             "tamanho": 184233, "conteudo_base64": "JVBERi0xLjQK…" }

aceita é uma lista de palavras — pdf, imagem, xml, planilha, texto —, não de MIME nem de extensão: quem traduz para cada plataforma somos nós. maxBytes só aperta o nosso teto (10 MB), nunca o afrouxa. Os outros campos da mesma caixa viajam junto, como em todo formulário. E vale conferir do seu lado o que sempre valeria: o tipo pelo conteúdo, não pelo nome; o tamanho; o hash, se você o guarda.

{ "_repetir_lista": {
    "type": "okmigoDocumento", "titulo": "{titulo}", "nome": "{nome}",
    "tipo": "{mime}", "tamanho": "{tamanho}",
    "ler": { "operacao": "ler_arquivo", "pedido": { "par_id": "{id}" } } } }

okmigoDocumento desenha uma linha com o título, o nome e o tamanho, e dois gestos: ver (PDF e imagem abrem na própria tela) e baixar. O nó não carrega o arquivo — carrega o nome de uma operação de leitura do seu contrato e o pedido que identifica o documento. Quando a pessoa toca, nós chamamos essa operação com a credencial e o cliente certos, e ela devolve o mesmo objeto do envio:

{ "nome": "DAS-2026-09.pdf", "tipo": "application/pdf",
  "tamanho": 91230, "conteudo_base64": "JVBERi0xLjQK…" }

Nós entregamos os bytes ao aparelho em fluxo, com o tipo e o nome que você declarou. Operação que não é de leitura do seu contrato recusa a tela, como um Submit fora do contrato. E o que se desenha em linha é lista fechada — PDF e imagem raster; o resto (inclusive SVG e HTML) sai como download, porque servido em linha rodaria na nossa origem, com a sessão de quem abriu.

⭐ O que fica do nosso lado é o TEXTO, e fica na memória de quem carregou ou abriu. Um documento que passa pelo correio entra na memória do OkMigo da pessoa exatamente como um arquivo que ela mesma subisse no chat: o texto em trechos, marcado como citação, o container descartado — e aparece na tela «Documentos» dela. É o que deixa o assistente responder "quanto foi a guia de setembro?". O arquivo em si não fica; o original é o seu. Nunca vai para a memória de quem está do outro lado do seu vínculo — nós não sabemos quem é, e não devemos.

⚠️ Repita a pergunta que você já faz em toda leitura: esse documento é deste cliente? O pedido volta do aparelho tal qual o crivo o entregou, e o cliente é o do cabeçalho — a sua função tem de recusar um id que não seja dele, exatamente como recusaria na conversa.

Imagens: quem hospeda somos nós

Você guarda a URL. O arquivo nunca fica do seu lado.

Foto de produto, de veículo, de imóvel — o arquivo é nosso. Você recebe uma URL numa operação de escrita, guarda essa URL, e devolve ela nas suas leituras. Você não recebe upload, não precisa de bucket e não lida com ciclo de vida de arquivo.

Não é comodidade: a foto chega ao OkMigo pela conversa — a pessoa manda para o assistente dela. Ela já passa pela nossa guarda, é reencodada e perde o EXIF (foto tirada dentro de casa carrega a coordenada de casa). E é servida do nosso domínio por um motivo que vale dizer em voz alta: se a imagem morasse no seu servidor, o aparelho de cada pessoa que abrisse a tela faria uma requisição a você, entregando o IP dela. Ela não escolheu falar com o seu sistema — ela escolheu falar com o amigo dela.

Marque a propriedade no inputSchema da sua função. É a única coisa que você precisa fazer para receber fotos:

"url": { "type": "string", "x-okmigo-foto": true }

O que muda do nosso lado: o campo marcado desaparece do que o modelo enxerga, e no lugar dele fica um com_a_foto: true. Quem escolhe o arquivo somos nós — é sempre a última foto que a pessoa mandou naquela conversa. O modelo não tem como pedir outra, nem como inventar um endereço; se não houver foto na conversa, a chamada falha antes de chegar a você, em vez de chegar sem a imagem.

{ "veiculo_id": "v_8821",
  "url": "https://img.okmigo.com/CMdMPFV4lBVjC4nX6hkQRA.jpg" }

A URL identifica um arquivo, não uma pessoa: cada envio gera uma chave nova e aleatória, e duas fotos da mesma pessoa não se ligam por ela. Continua valendo o que está em O que nunca mandamos para você — a URL é um argumento da sua função, como o modelo do carro.

Toda URL que mandamos começa com https://img.okmigo.com/. Recuse qualquer outra. Se chegar um endereço de outro domínio, não é foto nossa — guardá-la faria o seu sistema apontar para um arquivo que ninguém controla, e o erro só apareceria na tela de um cliente seu, meses depois.

{ "veiculos": [
    { "id": "v_8821", "modelo": "...", "capa": "https://img.okmigo.com/..." }
]}

Devolver a foto só no detalhe de um item é o erro mais comum aqui: quem abre uma lista quer ver, e uma lista sem capa vira texto. Se o seu sistema tem várias fotos por item, mande a capa na listagem e o resto no detalhe.

O carro foi vendido, o produto saiu de linha, alguém trocou a foto: você não precisa nos avisar. O arquivo é nosso, e tirá-lo do ar é responsabilidade nossa — do mesmo jeito que guardá-lo foi.

O que fazemos no lugar: cada arquivo que guardamos sabe de quem é e para que foi entregue, e o que deixa de ser referenciado é apagado por nós. Uma foto que a pessoa acha que tirou do ar não pode seguir alcançável por quem tiver o link — esse é o ponto, e ele é nosso.

Há um teto por negócio. Estourado, a operação devolve erro em vez de guardar — dizendo quanto falta liberar. Hospedar por conta de terceiros sem limite é descobrir o custo pela fatura.

Um pedido, do começo ao fim

As quatro mensagens que atravessam a rede, na ordem.

O assistente vê no catálogo dele que existe acmecrm_buscar_cliente e chama, porque precisa do id. É leitura: não pede confirmação.

Authorization: Bearer <credencial da Padaria>

{"method":"tools/call","params":{
  "name":"buscar_cliente","arguments":{"nome":"Ana"}}}

← 200
{"clientes":[{"id":"c_8812","nome":"Ana Paula Ribeiro","cidade":"Mauá"}]}

O assistente chama registrar_pedido. A ponte vê que a função não é readOnlyHint, não repassa nada para você e devolve ao modelo uma instrução para perguntar. O dono lê:

⚠️ Nesta etapa o seu servidor não foi chamado. Do seu lado, nada aconteceu.

Authorization: Bearer <credencial da Padaria>
Idempotency-Key: 7f3a9c21-4e0b-4a17-9f2e-1c8d5b6a0e33

{"method":"tools/call","params":{
  "name":"registrar_pedido",
  "arguments":{"cliente_id":"c_8812","itens":["PA-100","PA-100"]}}}

← 200
{"pedido_id":"p_44120","numero":4412,"total":189.90}

A chamada inteira — o que foi mandado, o que voltou, quanto demorou — fica registrada e visível para o dono do negócio. Ele consegue ver depois o que o assistente fez em nome dele no seu sistema.

O que nunca mandamos para você

Não é uma configuração que alguém pode mudar: não existe caminho no nosso código.

Quem a pessoa é

Nenhum id de usuário, e-mail, telefone ou identificador estável nosso atravessa. Você não consegue ligar duas chamadas à mesma pessoa por nada que a gente mande.

O que o OkMigo sabe sobre ela

O assistente conhece bem quem conversa com ele — gostos, rotina, opiniões. Nada disso vai no pedido. Só o que a pessoa declarou para aquela ação: o nome do cliente, o produto, a data.

O conteúdo da conversa

Você recebe os argumentos da função, não a fala. Não mandamos histórico, não mandamos o texto da mensagem.

Vai junto do pedido, além dos argumentos: a credencial daquele negócio e a chave de idempotência. Mais nada.

Os argumentos ainda passam por um filtro nosso antes de sair — se o modelo tentar enfiar um dado sensível num campo de texto livre, a chamada é bloqueada e nem chega em você.

11987654321        → recusado (parece documento)
5511987654321      → recusado (parece cartão)
(11) 98765-4321    → passa
[email protected]   → passa

Isso é bom para você também: quanto menos dado pessoal atravessa, menor a sua responsabilidade. A integração não te transforma em operador de dados de terceiros; ela te dá comandos sobre os dados que já eram seus.

Mudanças no contrato

Lemos a sua lista de funções uma vez, na instalação, e congelamos.

Função nova, schema alterado ou anotação trocada não entram sozinhos: viram uma revisão que uma pessoa nossa aprova antes de valer.

Isso protege os dois lados. Você publica quando quiser, sem medo de quebrar integrações no ar; e ninguém aqui acorda com uma função de escrita que apareceu de madrugada num servidor que a gente já chama todo dia.

Não dependemos só do seu aviso. No registro guardamos um hash do seu manifesto inteiro, e o painel compara o hash vivo com o guardado: se a sua lista de funções mudou e ninguém re-registrou, aparece contrato mudou do nosso lado. É o hash que pega isso, não a versão — quem altera o contrato sem subir a versão é exatamente o caso que se quer pegar. Declarar versao no manifesto é opcional e ajuda a conversa; o hash é o que mede.

O que pedimos em troca: avise quando o contrato mudar, e não mude o significado de uma função existente mantendo o mesmo nome e o mesmo schema. Essa é a única mudança que nenhuma verificação automática pega — o hash continua igual, a versão continua igual, e nada acusa. É também a única que pode fazer o assistente prometer ao dono uma coisa e o seu sistema fazer outra.

Como testar antes de falar com a gente

Dá para validar quase tudo sem nós.

1. Suba o servidor e liste as ferramentas. Qualquer cliente MCP (inclusive o mcp dev do SDK oficial) mostra o que você está publicando. Leia as descrições com olhos de quem não conhece o seu produto: é assim que o assistente vai ler.
2. Confira as anotações. Toda função que não grava precisa ter readOnlyHint: true. Conte-as.
3. Use duas credenciais de clientes diferentes e confirme que a mesma chamada devolve dados diferentes — e que não existe parâmetro capaz de trocar de cliente.
4. Repita uma escrita com a mesma Idempotency-Key e confirme que o segundo pedido não criou nada.
5. Provoque um erro de negócio (cliente inexistente, produto fora de linha) e leia a mensagem em voz alta: ela diz o que fazer em seguida?
6. Se você declara uma tela, passe o cartão pelo crivo — o nosso, em okmigo-infra/cartao, com dados que pareçam os seus e com as suas operações de escrita. Registrar não vai te dar esse aviso: o que o crivo descarta some em silêncio, e a tela abre sem o pedaço.

Passou nesses seis, a conversa com a gente é curta.

Perguntas que sempre aparecem

Vocês guardam os dados do meu sistema?

Não. A ponte traduz e esquece — sem cópia, sem cache, sem banco. O que guardamos é o registro de que uma chamada aconteceu, para o dono do negócio poder auditar.

Preciso mudar minha API?

Não. O servidor MCP fica na frente dela e chama o que já existe.

E se o modelo de IA inventar um argumento errado?

A ponte valida contra o schema que você declarou antes de chamar. E toda operação que grava passa pela confirmação do dono, com a ação descrita em português, antes de chegar em você.

Quem responde se algo for gravado errado?

O registro mostra exatamente o que foi enviado, quando, e que o dono confirmou. É por isso que a confirmação é estrutural e não uma instrução ao modelo.

Quanto custa? Tem exclusividade?

Não cobramos pela integração e não pedimos exclusividade. Seu cliente continua sendo seu.

Meu sistema é local, sem endereço na internet.

Aí não dá — precisamos alcançar o servidor MCP. Um túnel resolve, mas é decisão sua e do seu cliente.

Meu serviço não fala MCP e não vai falar.

Escrevemos um integrador por protocolo, nunca um por serviço — é o que mantém "instalar" sendo configuração em vez de projeto. Hoje o caminho é MCP. OpenAPI/Swagger está planejado, pelo mesmo motivo: a especificação descreve as operações sozinha. API própria sem especificação legível por máquina a gente não consegue integrar.

Antes de nos procurar

Oito itens, e o sexto é o que mais volta.

• Servidor MCP no ar, sobre HTTP, com TLS e endereço alcançável
• Lista de funções com descrição escrita para um modelo ler
• readOnlyHint: true em todas as funções de leitura
• Uma função por operação, parâmetros nomeados no schema
• Retorno sempre em objeto; erro de negócio como dado, dizendo o próximo passo
• Idempotency-Key respeitado nas escritas
• Escopo mínimo documentado
• O cliente NUNCA vem de um parâmetro do pedido
• Contato opcional — o filtro de saída pode recusar a chamada inteira por causa do FORMATO de um argumento
• Telefone e e-mail opcionais — o filtro de saída recusa a chamada inteira quando eles vêm junto

• Cada cliente tem a própria credencial no seu sistema
• O cliente é derivado dela, e de mais nada
• Revogar a credencial de um cliente para o acesso dele na hora

• Aceita o cabeçalho X-OkMigo-Tenant em toda chamada
• Cria a conta na primeira vez que um valor aparece
• Isola por ele: nenhuma chamada com outro valor enxerga aquele dado
• Não tenta interpretar o valor, e não exige nenhuma outra identificação
• Recusa a chamada quando o cabeçalho não vier — em vez de escolher um padrão, que é como dois clientes viram um
• Consegue suspender ou limitar um valor sem derrubar os outros
• Um cliente recém-criado consegue se configurar por função — ou o estado vazio devolve um erro que diz onde ir

Depois disso, escreva para [email protected] com o endereço do seu servidor e a lista de funções.

1. Lemos o seu list_tools() e fixamos o contrato. Sai um hash — que é como a gente percebe depois que ele mudou — e a lista de operações com o efeito de cada uma. ⚠️ Essa leitura vai autenticada (Authorization: Bearer + X-OkMigo-Tenant), com o par de sondagem que você mandou no arquivo: sem ele, o passo 1 morre em 401 e nada é criado.
2. Conferimos com você as anotações de leitura. É a única conversa necessária, e é rápida.
3. Registramos o seu serviço no catálogo — e nesse momento ele ainda não aparece para ninguém.
4. O primeiro negócio instala e cola a credencial dele. A partir daí o serviço existe para aquele negócio, e só para ele.
5. O assistente passa a usar as suas operações na conversa: leitura respondendo na hora, escrita perguntando antes.

Glossário

Os termos nossos que aparecem nesta página.

amigo

O assistente pessoal de um usuário. Memória dele, dele só.

sócio

O assistente de um negócio. A memória é do negócio, e várias pessoas podem operá-lo — é ele que vai chamar o seu serviço.

ponte

O serviço nosso que fala MCP com você. Traduz, valida, registra e esquece.

portão de confirmação

A regra que faz a primeira chamada de uma operação de escrita nunca executar, obrigando o assistente a perguntar antes.

instalar

O dono do negócio cadastrar a credencial dele do seu sistema no OkMigo. Do seu lado não acontece nada.

crivo

O código que lê o cartão que você declara e o reconstrói no nosso vocabulário, descartando em silêncio o que não conhece. É público (okmigo-infra/cartao) e roda na sua máquina, antes de registrar.