Para desenvolvedores

Esta página é para quem integra ou testa o servidor MCP: configuração em clientes locais, como o servidor decide quais ferramentas mostrar, seleção de grupos e descoberta dinâmica.

Endereço

https://mcp.magalu.com/mcp

O transporte é HTTP (streamable HTTP). A autenticação é OAuth 2.1 com registro dinâmico de cliente: o cliente MCP se registra sozinho e abre o login do ID Magalu no navegador. O token emitido é o próprio token do ID Magalu.

ChatGPT e Claude acessam o servidor a partir da nuvem deles, não do seu computador. Para testes de integração, os clientes locais abaixo dão mais controle sobre a configuração.

Clientes locais

Claude Code

claude mcp add --transport http magalu https://mcp.magalu.com/mcp

Dentro do Claude Code, digite /mcp, escolha magalu e faça o login.

VS Code

Crie .vscode/mcp.json:

{
  "servers": {
    "magalu": {
      "type": "http",
      "url": "https://mcp.magalu.com/mcp"
    }
  }
}

Abra o arquivo e clique em Start, acima do nome do servidor.

Codex

Em ~/.codex/config.toml, use o perfil compacto:

[mcp_servers.magalu]
url = "https://mcp.magalu.com/mcp?profile=compact"

Depois, faça o login com codex mcp login magalu.

Quais ferramentas cada conexão recebe

O servidor aplica três filtros, nesta ordem. Eles valem tanto para a lista de ferramentas (tools/list) quanto para a execução (tools/call).

Módulos do servidor. A variável MODULES define quais toolsets o servidor carrega. Em produção, todos estão ligados.
Escopos do token. Cada ferramenta exige um escopo, listado na Referência de ferramentas. A ferramenta só aparece se o claim scopes do token tiver esse escopo. Só contam escopos no formato open:<produto>-<recurso>-<seller|channel>:<read|write>. Escopos antigos, sem seller ou channel, são ignorados. É por isso que uma conta seller vê só ferramentas seller_*, uma conta de canal vê só channel_*, e um token só com :read não vê ferramentas de escrita.
Seleção da conexão (opcional). Restringe a conexão a alguns toolsets, como explicado abaixo.

Se o cliente chamar uma ferramenta que não passou pelos filtros, por exemplo usando uma lista antiga em cache, o servidor não chama a API e responde com um erro que diz qual escopo falta.

Cada ferramenta também informa ao cliente três marcações, que os clientes usam para pedir confirmação:

readOnlyHint: a ferramenta só lê dados.
destructiveHint: a ferramenta sobrescreve, remove, cancela ou finaliza algo, por exemplo atualizar preço, estoque ou SKU, ou efetivar alterações de uma promoção.
openWorldHint: o efeito chega ao comprador ou à outra parte do pedido, por exemplo publicar no catálogo, mudar preço ou enviar a nota fiscal.

Leituras saem com readOnlyHint: true e as outras duas false.

Canais de venda

O marketplace é multicanal. As operações de seller que a API associa a um canal recebem o parâmetro channel_id: cadastro de SKU, preço, estoque, scores, escritas de entrega e promoções. O valor é o UUID do canal, no mesmo formato de channel.id das APIs.

Para preço, estoque, cadastro, scores e promoções, o assistente obtém o ID pela meta-tool magalu_list_channels, que lista os canais em que o seller opera. Com um canal só, ele usa esse canal sem perguntar.
Nas escritas de entrega (nota fiscal, despacho e finalização), o canal é o do próprio pedido: order.channel.id, devolvido na consulta da entrega.

Fluxos que o servidor ensina ao assistente

Quando há ferramentas de seller, as instructions do servidor descrevem a ordem das chamadas nos fluxos mais comuns. O detalhe de cada parâmetro fica na descrição da própria ferramenta.

Fluxo	Ordem
Cadastro de produto	`magalu_list_channels` → `seller_categories_search` → `seller_categories_get_sku_template` → `seller_products_create_sku` → `seller_products_create_price` → `seller_products_create_stock`
Variações	O primeiro SKU é criado sem `group_id`, e os demais reusam o `group_id` devolvido
Entrega	`seller_orders_create_delivery_invoice` → `seller_orders_ship_delivery` → `seller_orders_finish_delivery`
Promoção do canal	`seller_promotions_get` → `seller_promotions_subscribe` → `seller_promotions_update_sku` → `seller_promotions_apply`
Promoção própria	`seller_promotions_create` → `seller_promotions_get` → `seller_promotions_update_sku`

Cadastro guiado pela categoria

Antes de enviar um SKU, seller_products_create_sku, seller_products_update_sku e seller_products_patch_sku conferem a ficha técnica e os atributos contra a categoria. Quando falta campo obrigatório ou um valor está fora dos aceitos, a ferramenta devolve um erro com a lista de problemas e não chama a API. O metadado da categoria fica em cache no servidor por até uma hora.

Respostas assíncronas

Cadastro de SKU, preço, estoque e criação de promoção são processados pela API depois da resposta. Nesses casos, a ferramenta devolve status: "aceito_para_processamento", a resposta original em result e, em next_step, a ferramenta que confirma o resultado.

Escolher os grupos de ferramentas

Sem configuração, a conexão recebe tudo o que o token permite. Uma conta seller com acesso completo recebe 55 ferramentas. Quanto maior a lista, mais contexto o modelo gasta só com a descrição das ferramentas e mais ele erra na escolha.

Para limitar, informe os toolsets no header X-MCP-Toolsets, separados por vírgula:

claude mcp add --transport http magalu https://mcp.magalu.com/mcp \
  --header "X-MCP-Toolsets: seller:orders,seller:products"

{
  "servers": {
    "magalu": {
      "type": "http",
      "url": "https://mcp.magalu.com/mcp",
      "headers": { "X-MCP-Toolsets": "seller:orders,seller:products" }
    }
  }
}

Clientes que não deixam configurar headers, como ChatGPT e Claude, aceitam a seleção na própria URL do conector:

https://mcp.magalu.com/mcp?modules=seller:orders,seller:products

Se o header e a URL forem usados juntos, vale o header. seller:* seleciona todos os toolsets de seller. A seleção nunca amplia o que o token permite: um toolset sem escopo no token continua de fora. Nomes de toolset desconhecidos são ignorados.

Perfil compacto (ChatGPT e Codex)

O ChatGPT e o Codex limitam o tamanho das ferramentas de cada conector: somam nome, descrição, schema de entrada e as instruções do servidor de cada uma e, quando o total passa do limite, ocultam o excedente sem avisar. Com o catálogo completo de seller, só cerca de metade das ferramentas cabe.

Nesses clientes, use o perfil compacto, pela URL ou pelo header X-MCP-Profile: compact:

https://mcp.magalu.com/mcp?profile=compact

No perfil compacto:

a descrição de cada ferramenta fica só com o primeiro parágrafo;
as descrições de campos aninhados saem do schema (os campos de primeiro nível mantêm a sua);
as instruções do servidor viram um lembrete curto.

O schema validado na execução continua o completo, e as marcações (readOnlyHint etc.) não mudam. O perfil combina com ?modules= e ?dynamic=true, por exemplo ?profile=compact&modules=seller:orders. Claude e Claude Code não têm esse limite e funcionam melhor com o perfil completo, que traz as descrições inteiras.

Descoberta dinâmica

Na descoberta dinâmica, a conexão começa quase vazia e o próprio assistente ativa os toolsets de que precisa durante a conversa. É a melhor opção quando o assistente atende pedidos variados e você não quer escolher os grupos com antecedência.

Como ligar

Adicione ?dynamic=true ao endereço ou envie o header X-MCP-Dynamic: true:

https://mcp.magalu.com/mcp?dynamic=true

O que o assistente recebe

No começo da sessão, a lista tem só as ferramentas de descoberta e as do servidor:

Ferramenta	O que faz
`list_toolsets`	Lista os toolsets que o token permite, com a quantidade de ferramentas e se já estão ativos
`get_toolset_tools`	Mostra as ferramentas de um toolset (nome, descrição, leitura ou escrita) sem ativar
`enable_toolset`	Ativa um toolset na sessão
`magalu_list_modules`	Lista os toolsets permitidos com a descrição de cada um

Uma conversa, passo a passo

O lojista pergunta "em quais promoções eu posso entrar este mês?".

O assistente chama list_toolsets e recebe os grupos permitidos:

{
  "toolsets": {
    "seller:orders": {
      "description": "Pedidos do seller no Marketplace Magalu",
      "allowed_tools": 10,
      "active": false
    },
    "seller:promotions": {
      "description": "Promoções do seller no Marketplace Magalu",
      "allowed_tools": 11,
      "active": false
    }
  }
}

Pelo nome e pela descrição, escolhe seller:promotions e chama enable_toolset("seller:promotions"). O servidor responde Toolset 'seller:promotions' ativado com 11 tools.
Em seguida, o servidor envia a notificação notifications/tools/list_changed.
O cliente pede a lista de ferramentas de novo e passa a ver as seller_promotions_*.
O assistente chama seller_promotions_list com as datas do mês e responde ao lojista.

Se o assistente quiser conferir o conteúdo de um grupo antes de ativar, ele usa get_toolset_tools("seller:promotions"), que não muda a lista da sessão.

Regras

Permissões continuam valendo. list_toolsets só mostra toolsets com pelo menos uma ferramenta permitida pelo token, e enable_toolset recusa um toolset sem permissão, com uma mensagem explicando o motivo. Ativar um toolset libera só as ferramentas cujo escopo o token tem.
Combina com a seleção. Com X-MCP-Toolsets ou ?modules=, a descoberta fica restrita aos toolsets selecionados.
A ativação vale para a sessão. Os toolsets ativados ficam associados à sessão MCP. Uma nova conexão começa vazia de novo. Não existe desativar: para recomeçar, reconecte.

O que o cliente precisa suportar

A descoberta depende de o cliente tratar notifications/tools/list_changed e buscar a lista de novo. Claude Code e VS Code fazem isso. Em outros clientes, teste antes: se depois de enable_toolset as ferramentas novas não aparecerem, o cliente não trata a notificação. Nesse caso, use X-MCP-Toolsets ou ?modules=.

Quando usar cada opção

Situação	Opção
O assistente sempre trabalha com os mesmos assuntos	`X-MCP-Toolsets` ou `?modules=`
O assistente atende pedidos variados e o cliente trata `list_changed`	Descoberta dinâmica
Conta com poucas permissões ou cliente que lida bem com muitas ferramentas	Sem configuração

Endereço​

Clientes locais​

Claude Code​

VS Code​

Codex​

Quais ferramentas cada conexão recebe​

Canais de venda​

Fluxos que o servidor ensina ao assistente​

Cadastro guiado pela categoria​

Respostas assíncronas​

Escolher os grupos de ferramentas​

Perfil compacto (ChatGPT e Codex)​

Descoberta dinâmica​

Como ligar​

O que o assistente recebe​

Uma conversa, passo a passo​

Regras​

O que o cliente precisa suportar​

Quando usar cada opção​