Como Configurar um Client MCP

Visão Geral

Este guia mostra como conectar um client MCP (Claude Desktop, Cursor, ou qualquer outro client compatível com o protocolo) a um dos servidores MCP da Uappi. Antes de continuar, veja a Visão Geral dos servidores MCP para escolher qual dos três servidores faz sentido para o seu caso — este guia usa como exemplo o servidor Uappi Staff Panel (user/mcp), por ser o único com fluxo de autorização pensado especificamente para clients externos como o Claude.

Passo a passo (qualquer client MCP)

• Descubra a URL do servidor MCP da sua loja — é sempre https://sua-loja-uappi.com.br/api/v3/{endpoint}, onde {endpoint} é user/mcp, customer/mcp ou publics/mcp (ver tabela na Visão Geral). https://sua-loja-uappi.com.br/api/v3 sempre inclui o prefixo /api/v3 (ex.: https://sualoja.com.br/api/v3) — veja o porquê na Visão Geral.
• Adicione o servidor no client MCP, informando essa URL como um servidor remoto via HTTP (não stdio).
• Autentique: no user/mcp, a maioria dos clients modernos (Claude Desktop incluso) faz o fluxo OAuth 2.1 automaticamente — ele descobre os endpoints via /.well-known/oauth-authorization-server, se registra como client (POST /oauth/user/register) e abre o navegador para a tela de consentimento do painel (veja o fluxo completo em OAuth 2.1). Se o client não suportar OAuth, também é possível autenticar enviando um token de sessão do painel diretamente no header Authorization: Bearer {token}.
• Teste a conexão chamando tools/list (ou o equivalente na interface do client) — se a lista de ferramentas aparecer, a conexão está funcionando.
⚠️ Atenção

O path do servidor público é publics/mcp, no plural — atenção ao configurar o servidor errado por engano.

Configurando via OAuth (ex.: Claude Desktop)

Estes passos usam o servidor Uappi Staff Panel (user/mcp) como exemplo, autenticando via OAuth.

• Abra Configurações no Claude Desktop e clique em Personalizar.



• Clique no ícone de Conectores e depois em Adicionar.



• No formulário de conector personalizado, informe um nome e a URL do servidor MCP da sua loja (ex.: https://sua-loja-uappi.com.br/api/v3/user/mcp), depois clique em Continuar.



• O Claude Desktop detecta que o servidor exige OAuth e abre o navegador na tela de consentimento do painel Uappi. Revise os escopos solicitados e clique em Autorizar.



• O conector aparece como Conectado, já com a lista de ferramentas disponíveis.



• Em uma nova conversa, o Claude já consegue listar e chamar as ferramentas do servidor.



📝 Nota

As imagens acima são ilustrativas — o menu exato pode variar entre versões do Claude Desktop, mas o fluxo (adicionar conector → informar URL → autorizar) é o mesmo.

Configurando sem OAuth (ex.: customer/mcp)

Só o user/mcp (Uappi Staff Panel) tem fluxo OAuth 2.1. O customer/mcp (Uappi My Account) não tem — o token precisa ser enviado manualmente no header Authorization. Exemplo, usando o customer/mcp:

1{
2  "mcpServers": {
3    "uappi-my-account": {
4      "url": "https://sua-loja-uappi.com.br/api/v3/customer/mcp",
5      "headers": {
6        "Authorization": "Bearer SEU_TOKEN_DE_CLIENTE"
7      }
8    }
9  }
10}

📝 Nota

O publics/mcp também não tem OAuth, mas nesse caso não é preciso enviar token nenhum — basta declarar a url.

Configuração via JSON (avançado)

Alguns clients MCP (e versões mais antigas do Claude Desktop) configuram servidores remotos editando diretamente o arquivo de configuração, em vez de usar uma tela de conectores. O formato para um servidor remoto via HTTP é:

1{
2  "mcpServers": {
3    "uappi-staff-panel": {
4      "url": "https://sua-loja-uappi.com.br/api/v3/user/mcp"
5    }
6  }
7}

Troque https://sua-loja-uappi.com.br/api/v3 pela URL real da loja, sempre com o prefixo /api/v3 (ex.: https://sualoja.com.br/api/v3). Para os outros servidores, use a URL correspondente:

1{
2  "mcpServers": {
3    "uappi-my-account": {
4      "url": "https://sua-loja-uappi.com.br/api/v3/customer/mcp"
5    },
6    "uappi-storefront": {
7      "url": "https://sua-loja-uappi.com.br/api/v3/publics/mcp"
8    }
9  }
10}

📝 Nota

O arquivo de configuração do Claude Desktop normalmente fica em %APPDATA%\Claude\claudedesktopconfig.json (Windows) ou ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS). Depois de editar, é necessário reiniciar o Claude Desktop.

Testando a conexão

Independente do client usado, uma forma rápida de validar a configuração é pedir para o assistente listar as ferramentas disponíveis ou chamar uma ferramenta simples de leitura (ex.: get_current_user no user/mcp). Se a chamada retornar dados em vez de um erro de autenticação, a configuração está correta.

Problemas comuns

• Erro de autenticação (401): o token expirou ou a autorização OAuth não foi concluída — repita o passo de autorização.
• Ferramenta aparece em tools/list mas retorna erro de permissão: o usuário autenticado (ou o escopo concedido no OAuth) não tem a permissão exigida por aquela ferramenta específica — ver Autenticação e Permissões.
• Servidor não conecta: confirme que o path está correto (publics/mcp no plural) e que a URL usa https://.