Integração por MCP: gere pedidos e clientes em linguagem natural

As equipes de lealdade e operações estão cada vez mais automatizando com agentes de IA: campanhas que criam pedidos, scripts que ajustam carteiras de pontos, assistentes que consultam o catálogo antes de lançar uma promoção. Até agora, isso envolvia integrar manualmente a API REST, lidar com idempotência e memorizar endpoints. O TPP Ops fecha essa lacuna com um servidor MCP (Modelo de Protocolo de Contexto) que envolve a API pública /api/v1/* como ferramentas que um agente pode invocar em linguagem natural.

Não é uma segunda API nem um acesso diferente ao backoffice interno. É um adaptador de protocolo: cada chamada MCP se traduz em uma solicitação HTTP para a API que os parceiros já usam, com o mesmo portador, os mesmos escopos e as mesmas regras de sub-marca. Se o token não puder criar pedidos, a ferramenta retorna forbidden — o agente não pode contornar a autorização.

O que um agente conectado pode fazer

As ferramentas são geradas automaticamente a partir do log de operações da API. Quando adicionamos um novo endpoint, ele aparece como uma ferramenta MCP sem trabalho extra. O catálogo cobre o ciclo operacional que importa para integradores e equipes de produto.

• Clientes: listar, criar, atualizar, consultar moedas e ajustar saldos (bulk_adjust_customer_coins incluído).

• Pedidos: reserve_order, listar, consultar detalhes, cancel_order e gerenciar envio.

• Catálogo: lojas, catálogos e search_products com preços mascarados.

• Sessões: create_store_session para transferência de SSO do jogador.

Autenticação e escopo

O servidor MCP não armazena suas próprias credenciais. Ele pega o cabeçalho Autorização: Bearer da solicitação de entrada — sua chave de API tpp_live_* ou tpp_test_* — e a encaminha como está para a API. A chave é restrita a uma sub-marca: o agente só vê e manipula dados daquele inquilino. O véu do provedor, limite de taxa, auditoria e idempotência são herdados do wrapper withApiKey; o MCP não reimplementa a lógica de negócios.

Princípio do menor privilégio: crie uma chave com apenas os escopos que o agente precisa. Um token somente de leitura não pode escrever mesmo que o prompt solicite — a API responde 403 e o agente recebe um erro acionável com o escopo ausente.

Idempotência em operações financeiras

Endpoints que movimentam dinheiro ou criam clientes requerem Idempotency-Key. Um agente que tenta novamente por dúvida poderia duplicar uma cobrança sem uma chave estável. O MCP gera automaticamente um UUID por chamada e expõe um argumento opcional idempotency_key para tentativas deliberadas: a API retorna a mesma resposta em cache com Idempotent-Replay: true.

Como conectá-lo

No back office do TPP Ops, vá para Sub-marca → Chaves de API e crie um token com os escopos mínimos. No ChatGPT (Modo Desenvolvedor), adicione um conector personalizado com a URL https://<seu-domínio>/api/mcp e autenticação de chave de API / Bearer. Claude, Cursor e n8n usam a mesma URL e cabeçalho.

O guia humano vive em /api/v1/mcp; o manifesto legível por máquina com JSON-Schema para cada ferramenta, em /api/mcp/tools — o equivalente do MCP ao OpenAPI. ChatGPT executa tools/list ao se conectar e já pode operar: "criar um pedido para este cliente", "quantas moedas o segmento VIP tem?", "procurar presentes de jogos no catálogo".

Por que MCP e não apenas REST

REST ainda é a opção para integrações clássicas de servidor para servidor. O MCP desbloqueia o mesmo backend para fluxos agentes: prototipagem rápida, operações assistidas por IA, conectores no ChatGPT sem escrever seu próprio middleware. Uma única fonte de verdade, duas maneiras de consumi-la.

O servidor é sem estado (HTTP transmitível), escala horizontalmente sem Redis, e é implantado com o mesmo aplicativo em POST /api/mcp. Se você já está operando fidelidade com TPP e quer que seus agentes criem pedidos, verifiquem estoque ou ajustem moedas sem usar curl, o MCP é a camada que falta.