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.

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.