MCP

A mesma API, dirigida a um assistente em vez de a um cenário. Um cliente MCP escolhe o que chamar enquanto roda, a partir das descrições das ferramentas, então alcança exatamente o que as credenciais dele alcançam, e sob cada ferramenta há uma chamada da API pública.

Um endpoint só

Tudo vai para POST /v1/mcp. Não há sessão a abrir nem fluxo a manter: GET e DELETE respondem 405, e cada mensagem é a própria requisição.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

As revisões do protocolo de 2025-03-26 a 2026-07-28 são todas atendidas. Um cliente que começa com initialize recebe o aperto de mão que espera; o que declara a versão em cada requisição é atendido assim.

Conectar com uma chave de API

O caminho mais rápido, e o certo para uma ferramenta que você mesmo executa. Qualquer chave funciona como token bearer, e as ferramentas oferecidas são cortadas para os escopos dessa chave.

A maioria dos clientes aceita um bloco como este:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Conectar via OAuth

Para um conector no diretório de outra pessoa, onde ninguém manuseia uma chave. A descoberta segue RFC 9728 e RFC 8414, os clientes se registram sozinhos por RFC 7591, e cada autorização usa PKCE com S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

Uma chamada não autorizada diz por si onde ir e o que pedir:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

Quem aprova está logado no Mosaqo, escolhe o espaço a que se aplica e só pode fazê-lo onde é proprietário ou administrador — a mesma linha que decide quem pode emitir uma chave de API. Depois dá para desconectar em Bulk & API.

O que um assistente pode fazer

Os escopos que você já conhece, sem mudança. Uma ferramenta que as credenciais não permitem não aparece em tools/list e não é chamada nem nomeando-a, então a resposta viva para qualquer conexão é o próprio tools/list.

Tarefas prontas

Além das ferramentas, o servidor oferece alguns prompts — um relatório de leituras, uma revisão de avaliações, o redirecionamento de uma campanha — que os clientes mostram como comandos. Cada um nomeia as ferramentas que espera e repete o limite em que se apoia, para que uma conexão nova tenha por onde começar em vez de uma lista de quinze verbos. São filtrados por escopo com mais rigor que as ferramentas: um prompt aparece só quando as credenciais têm todos os escopos de que seu trabalho precisa.

O que ele nunca alcança

O que as pessoas escreveram numa pesquisa. reviews:read abre seus locais, suas pesquisas e como estão indo: as contagens, as notas, a distribuição por pergunta. As frases que um visitante digitou não são devolvidas aqui mais do que em qualquer outro lugar que credenciais alcancem, pela mesma razão que os eventos feedback.* levam uma nota e nunca as palavras.

Apagar um código. A rota REST pede confirmação digitada porque destruir o redirecionamento de um código impresso não se desfaz, e essa não é uma confirmação que um assistente dá no lugar de alguém. Em vez disso há arquivar, e isso se reverte.

Escrita é marcada como escrita. Uma ferramenta que muda algo leva readOnlyHint: false, e arquivar leva destructiveHint: true — é isso que faz um cliente parar e perguntar a uma pessoa antes de agir.