Tray MCP Server

Servidor MCP (Model Context Protocol) que conecta agentes de IA como Claude à plataforma Tray Commerce. Permite gerenciar produtos, pedidos e clientes em linguagem natural, sem abrir o painel administrativo.

Demonstração

Você: "Quais pedidos aprovados ainda não foram enviados hoje?"

Claude: Encontrei 3 pedidos aprovados pendentes de envio:
  - #12340 — João Silva — R$ 299,90 — aprovado às 09:15
  - #12345 — Maria Souza — R$ 149,00 — aprovado às 11:30
  - #12350 — Carlos Lima — R$ 599,90 — aprovado às 14:00

Você: "Manda o 12345 como Enviado com rastreio BR999888777BR"

Claude: Pedido #12345 atualizado para "Enviado" com rastreio BR999888777BR ✓

Requisitos

• Node.js 20+

• Credenciais de parceiro Tray (Consumer Key + Consumer Secret)

• Claude Desktop, Claude Code ou outro cliente MCP

Instalação e Autenticação

Passo 1 — Autenticar (uma única vez):

npx @tray/mcp-server auth

O assistente interativo vai pedir suas credenciais de parceiro e o code gerado quando o lojista instala o app na loja. Ao final, salva os tokens em ~/.tray-mcp/tokens.json e imprime o bloco de configuração pronto para usar.

Passo 2 — Adicionar ao Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "tray": {
      "command": "npx",
      "args": ["-y", "@tray/mcp-server"],
      "env": {
        "TRAY_API_HOST": "https://loja.com.br/web_api",
        "TRAY_ACCESS_TOKEN": "SEU_ACCESS_TOKEN",
        "TRAY_REFRESH_TOKEN": "SEU_REFRESH_TOKEN",
        "TRAY_CONSUMER_KEY": "SUA_CONSUMER_KEY",
        "TRAY_CONSUMER_SECRET": "SEU_CONSUMER_SECRET",
        "TRAY_TOKEN_EXPIRATION": "2024-03-02 14:58:21"
      }
    }
  }
}

Se tiver rodado tray-mcp auth, pode omitir o bloco env — o servidor lê os tokens do arquivo salvo automaticamente.

Passo 3 — Reiniciar o Claude Desktop. O servidor aparece como conjunto de ferramentas "tray".

Ferramentas disponíveis

Produtos

Pedidos

Clientes

Recursos de contexto (Resources)

Exemplos de uso

"Quais produtos têm menos de 5 unidades em estoque?"
"Coloca o produto 84 em promoção por R$ 199,90"
"Me mostra os detalhes do pedido 12345"
"Atualiza o status do pedido 99999 para Cancelado"
"O cliente joao@email.com já cadastrou na loja?"

Variáveis de ambiente

O servidor renova o access_token automaticamente 5 minutos antes de expirar — nenhuma intervenção manual necessária.

Limites de API

A Tray impõe os seguintes limites, respeitados automaticamente pelo servidor:

• 180 requisições/minuto por loja

• 10.000 requisições/dia por loja

O servidor avisa quando 80% do limite diário for consumido.

Desenvolvimento local

git clone https://github.com/seu-usuario/tray-mcp-server
cd tray-mcp-server
npm install
npm run build       # compila TypeScript → dist/
npm run dev         # roda direto via tsx (sem compilar)

Roadmap

• Fase 1 — MVP: produtos, pedidos, clientes, auth + rate limiter

• Fase 2 — Catálogo completo: variações, categorias, marcas, kits

• Fase 3 — Promoções: cupons, listas de preço B2B, NF-e, multi-loja

Referências

• Documentação da API Tray — referência técnica coletada

• PRD do projeto — especificação de produto

• Tray Developers

• MCP TypeScript SDK