Documentação de MCP (Model Context Protocol)

Visão Geral

A plataforma Uappi expõe sua lógica de negócio para agentes de IA através do protocolo MCP (Model Context Protocol). Isso permite que clientes MCP externos (ex.: Claude Desktop, Cursor, ChatGPT com conectores, ou qualquer outro cliente compatível) se conectem diretamente à API da loja e naveguem/operem seus dados através de ferramentas (tools) estruturadas — sem precisar integrar cada endpoint REST manualmente.

Existem três servidores MCP, um por tipo de identidade, cada um com sua própria autenticação:

> Atenção ao path do servidor público: é publics/mcp, no plural — não public/mcp. Essa é uma decisão intencional para evitar colisão com regras de reescrita de URL do servidor web.

Cada servidor conversa via JSON-RPC sobre HTTP (initialize, tools/list, tools/call, etc.), no padrão MCP. Um cliente MCP típico:

1. Chama initialize para obter nome/versão do servidor e instruções gerais. 2. Chama tools/list para descobrir o catálogo de ferramentas disponíveis (nome, descrição, schema de entrada). 3. Chama tools/call para executar uma ferramenta específica com argumentos.

Como cada identidade é escopada

• Staff (user/mcp): exige uma sessão de staff válida ou um access token OAuth 2.1 (fluxo pensado para clients externos como o Claude, com tela de consentimento por escopo — ver OAuth). Cada ferramenta ainda reforça um escopo de permissão específico — o mesmo sistema de permissões usado no painel administrativo. Um colaborador sem a permissão exigida recebe erro de autorização antes mesmo da ferramenta rodar.
• Cliente (customer/mcp): exige sessão de cliente autenticado. As ferramentas operam apenas sobre os próprios dados do cliente autenticado (pedidos, endereços, cartões, wishlist, etc.) — não existe hoje um sistema de escopos granular para esta identidade.
• Público (publics/mcp): acesso anônimo, sem exigir login. Um token ausente ou expirado é tolerado; um token malformado/inválido ainda assim é rejeitado.

Organização por domínio

As ferramentas de cada servidor são agrupadas por domínio de negócio (ex.: Order, Product, Customer, Cart, Shipping, Marketplace, Notification, etc.), seguindo a convenção de nomes {verbo}_{domínio} (ex.: list_orders, get_order_detail, create_coupon). Cada ferramenta corresponde a uma única operação de negócio e retorna o mesmo tipo de dado que a operação equivalente no painel.

Alguns gotchas estruturais, válidos em qualquer domínio:

• O campo fields, quando presente no schema de uma ferramenta de listagem/detalhe, é somente aditivo — nunca reduz a resposta padrão, apenas adiciona campos extras opcionais.
• Um campo marcado como opcional no schema de uma ferramenta ainda pode ser exigido pela validação real do backend.
• Entidades relacionadas podem ter exclusão em cascata — um "não encontrado" inesperado em uma chamada seguinte pode significar que uma chamada anterior já removeu algo vinculado ao id usado, não que o id em si esteja errado.
• Um fluxo de negócio pode atravessar mais de um servidor. Como a separação entre os três servidores é por identidade, e não por assunto, um fluxo executado por mais de um ator começa em um servidor e termina em outro — as etapas do cliente final não são expostas no servidor de staff, e vice-versa. Quando a etapa seguinte de um fluxo não existe como ferramenta no servidor em que você está, normalmente é esse o motivo: ela pertence a outro servidor. O que atravessa a fronteira é sempre um valor explícito devolvido pela etapa anterior — um código, um token, um id — usado como argumento da ferramenta do outro lado.

Relação com o Chat de IA

O Chat de IA do painel (assistente conversacional para staff) opera sobre a mesma base de capacidades exposta pelo servidor Uappi Staff Panel — ou seja, o que o assistente consegue consultar/operar durante uma conversa corresponde ao que está documentado nos domínios abaixo.

Como Configurar

Veja o passo a passo de Como Configurar um Client MCP — inclui um exemplo completo de configuração no Claude Desktop, com imagens.

Servidores

• Uappi Staff Panel (user/mcp)
• Uappi My Account (customer/mcp)
• Uappi Storefront (publics/mcp)