# Solução de problemas

Comece sempre pelo mesmo teste: peça ao agente para chamar
**`connection_status`**. É grátis, não conta na cota e é a única checagem que
realmente busca o token do Mercado Livre.

| `status` | Significa |
|---|---|
| `ok` | mcplace, conector e Mercado Livre estão respondendo. O problema está no pedido ou no cliente. |
| `reconnect_required` | A autorização do Mercado Livre caiu. Reconecte no painel. |
| a tool nem aparece | O cliente não conectou. Veja abaixo. |

O botão **Testar conexão** do painel confere outra coisa: que o mcplace está no
ar, que o conector está ativo e que existe uma autorização gravada. Ele **não
fala com o Mercado Livre**, então verde no painel não prova que o token ainda
vale. Na dúvida, use `connection_status`.

## As tools não aparecem no cliente

1. **A URL está inteira?** É o host, uma barra e o trecho que você copiou. Se
   você estreitou a conexão, pode vir seguido de `/a/<apelido>` (uma conta sua)
   ou de `/c/<cliente>` (um cliente da organização) — e desse de `/t/leitura`,
   nessa ordem. O que nunca aparece é `/mcp` no fim: esse é o endereço do
   OAuth, não da sua URL. Copie de novo em **Seu agente**, sem espaço nem
   quebra de linha.
2. **Girou a URL?** A antiga parou de funcionar na hora — cole a nova.
3. **O cliente pegou a URL nova?** No Claude Desktop, confira em **Customize >
   Connectors** se o conector do mcplace aparece; se você trocou a URL, edite o
   conector e cole a nova. No Cursor, confira em Settings → MCP se o servidor
   aparece ativo.
4. **Uma ferramenta documentada não aparece no ChatGPT?** O conector guarda a
   lista de ferramentas como ela era quando foi adicionado. Depois que uma
   ferramenta muda do nosso lado, atualize o conector no ChatGPT para ele
   buscar a lista de novo.
5. **O JSON continua válido?** Uma vírgula sobrando em `~/.cursor/mcp.json`
   derruba **todos** os servidores MCP do arquivo, não só o mcplace.
6. **No Claude Code**, rode `claude mcp list` e veja se `mcplace` aparece
   conectado.

## O cliente recebe 401 ou 404

- **401** — URL errada ou girada, API key revogada ou conector suspenso.
  Confira o estado do conector no painel (`ativo` ou `suspenso`).
- **404** — URL cortada ao colar, ou trechos fora de ordem: `/t/` antes de
  `/a/` ou `/c/`. O `/c/` num espaço de trabalho pessoal ou Enterprise responde
  `narrowing_not_applicable`.
- Com **API key**, o header é `Authorization: Bearer mcpk_…` e o endpoint é
  `https://mcp.mcplace.com.br/mcp`.
- Com **OAuth**, aponte para `https://mcp.mcplace.com.br/mcp` e faça login
  quando o cliente pedir.

## "Este conector está suspenso"

A mensagem fala em plano ou pagamento, e são essas as **duas** causas:

1. Downgrade de plano deixou conectores acima do limite. Eles são suspensos,
   não apagados.
2. Pagamento pendente.

Se a autorização foi removida dentro do Mercado Livre, a mensagem é outra:
*"Esta conta precisa de reautorização no marketplace. Reautorize no painel."*

## "Mais de uma conta pode responder" ou "Diga a conta"

O agente não disse em qual conta agir, e o espaço de trabalho tem mais de uma.

- Numa **leitura**, o erro é [`account_ambiguous`](/erros-e-limites#account_ambiguous)
  e traz `candidates`: os endereços das contas que servem. O agente escolhe um
  e repete a chamada com `account`.
- Numa **escrita**, o erro é [`account_required`](/erros-e-limites#account_required),
  mesmo com uma conta só: toda escrita diz a conta, o servidor nunca escolhe.

`account` aceita o apelido da conta, o id do vendedor no marketplace ou o
endereço que `connection_status` devolve. Com a URL estreitada com `/a/`, a
conta já está definida.

## O agente diz que não pode alterar nada

- Conector em **Somente leitura**, ou API key criada como somente leitura.
- **Confirmação exigida**: a primeira tentativa volta pedindo `confirm=true`.
  Isso não é falha, é o agente devendo uma pergunta a você.

Detalhes em [Segurança e controle](/seguranca).

## O número não bate com o painel do Mercado Livre

- **Resultado parcial.** Acima de 2000 pedidos no período a soma vem com
  `_truncated: true`. Reduza o período.
- **Qual data?** `aggregate_orders` usa a data de **fechamento** do pedido por
  padrão, e só pedidos `paid`.
- **`net` não é lucro:** desconta apenas a tarifa de venda.
- **Cache de até 60 segundos** nas leituras.
- **Ads** do dia corrente só fecha às 10:00 (horário de Brasília).

Veja [Erros e limites](/erros-e-limites) e as
[Receitas](/conectores/mercado-livre/receitas).

## "Limite diário atingido" no meio do dia

O plano Grátis tem 50 chamadas por dia, por 7 dias a partir da primeira chamada de tool, e o contador zera às **21:00 de
Brasília** (00:00 UTC). Um agente que lê pedido por pedido gasta a cota em
minutos; peça a resposta agregada (`aggregate_orders`, `rank_items`) em vez de
listar e somar.

## Nada disso resolveu

Peça ao agente para chamar **`open_support_ticket`** descrevendo o problema: é
grátis, abre um chamado e você acompanha em **Ajuda** no painel. São até 5
chamados ou sugestões por dia. O estado dos serviços fica em
[status.mcplace.com.br](https://status.mcplace.com.br).