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.

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 se só lê dados (readOnlyHint) ou se remove ou cancela algo (destructiveHint). Os clientes usam essas marcações para pedir confirmação.

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.

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​

Quais ferramentas cada conexão recebe​

Escolher os grupos de ferramentas​

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​