Servidor MCP — Uappi Staff Panel

Descrição

Servidor MCP voltado para ferramentas de staff/back-office da loja — o mesmo tipo de operação disponível no painel administrativo Uappi. Requer uma sessão de staff autenticada.

• Nome MCP: Uappi Staff Panel
• Versão: 0.1.0
• Ferramentas expostas: ~595

Autenticação e Permissões

O acesso ao endpoint exige um token válido em Authorization: Bearer {token}, por uma de duas formas:

• Token de sessão do painel: o mesmo token emitido pelo login tradicional do painel administrativo.
• Access token OAuth 2.1: obtido através do fluxo authorization_code + PKCE, pensado justamente para

Além da autenticação, cada ferramenta individualmente reforça um escopo de permissão — o mesmo sistema de permissões usado no painel administrativo (ex.: ORDER_READ, PRODUCT_WRITE, AI_CHAT_READ). Um staff autenticado, mas sem o escopo exigido por uma ferramenta específica, recebe um erro de autorização ao chamá-la — mesmo que consiga ver a ferramenta listada em tools/list. Quando a autenticação é via OAuth, o escopo efetivo também é limitado pelo que o usuário concedeu na tela de consentimento, além do que o perfil dele já permite.

Domínios cobertos

Exemplo de Requisição

1curl --request POST \
2  --url https://sua-loja-uappi.com.br/api/v3/user/mcp \
3  --header "Authorization: Bearer SEU_TOKEN_DE_STAFF" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "jsonrpc": "2.0",
7    "id": 1,
8    "method": "tools/call",
9    "params": {
10      "name": "get_order_detail",
11      "arguments": { "orderId": 1234 }
12    }
13  }'

✅ Resposta de Sucesso

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "result": {
5    "content": [{ "type": "text", "text": "{...detalhe do pedido em JSON...}" }],
6    "structuredContent": { "id": 1234, "status": "..." },
7    "isError": false
8  }
9}

⚠️ Erros de ferramenta

Erros de validação de argumentos, permissão insuficiente ou falha ao executar a operação não retornam HTTP 500 — voltam como HTTP 200 com isError: true no corpo do resultado JSON-RPC, contendo a mensagem de erro relevante. Apenas falhas de autenticação (token ausente/inválido) retornam HTTP 401 real, no nível da rota.