MCP do Mercado Livre no Cursor: como conectar e o que dá para fazer

Integrar com o Mercado Livre costuma envolver OAuth, webhooks, tópicos que mudam de nome (claims → post_purchase) e dezenas de páginas na documentação oficial. O problema não é falta de material, é encontrar a página certa, na versão certa, no momento certo.

O MCP Server oficial do Mercado Libre resolve isso de um jeito interessante: em vez de expor a API de produção diretamente, ele coloca a documentação técnica oficial dentro do seu IDE agêntico (Cursor, Windsurf, Claude Desktop, etc.). O assistente passa a buscar e ler a doc do ML como ferramenta, sem você alternar entre abas.

Neste artigo mostro como conectar, o que está disponível hoje e casos de uso reais para quem integra marketplaces.

1. O que é MCP (e por que importa)

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como modelos de IA se conectam a fontes externas: APIs, bancos de dados, documentação, ferramentas internas.

No fluxo típico:

[Desenvolvedor] ──(pergunta em linguagem natural)──> [Cursor / IDE Agêntico]
                                                          │
                                                          ├──> [MCP: search_documentation]
                                                          │         └── busca na doc oficial
                                                          │
                                                          └──> [MCP: get_documentation_page]
                                                                    └── lê página completa

O ponto central: as tools do MCP não são chamadas manualmente por você. O IDE agêntico decide quando usá-las com base no contexto da conversa.

2. O que o MCP oficial do Mercado Libre faz (e o que não faz)

Antes de conectar, vale alinhar expectativa.

Existe também um MCP comunitário (dan1d/mercadolibre-mcp) focado em busca de produtos, categorias e trends. É outro servidor, com outro propósito. Neste artigo foco no oficial mantido pelo Mercado Libre.

3. Requisitos

Fonte: Mercado Libre MCP Server, documentação oficial.

4. Como conectar no Cursor

Passo 1, Abrir configuração

Cursor Settings → Tools & Integrations → New MCP Server. Isso abre o arquivo mcp.json (global ou do projeto).

Passo 2, Adicionar o servidor

{
  "mcpServers": {
    "mercadolibre-mcp-server": {
      "url": "https://mcp.mercadolibre.com/mcp"
    }
  }
}

Passo 3, Autenticar via OAuth

Ao salvar, o Cursor deve abrir o navegador para selecionar o país (Brasil, Argentina, México…), autorizar a integração com sua conta Mercado Libre e retornar ao Cursor com credenciais gerenciadas automaticamente.

Passo 4, Verificar conexão

No painel de MCP do Cursor, o servidor deve aparecer como ready, com 3 tools: search_documentation, get_documentation_page e mcp_auth.

5. Tools disponíveis

5.1 search_documentation

Busca palavras-chave em toda a documentação técnica.

*Na prática, sempre passe query para resultados úteis.

Exemplo conceitual (o agente monta a chamada):

{
  "language": "pt_br",
  "query": "webhooks notificacoes claims shipments",
  "siteId": "MLB",
  "limit": 5
}

Resposta típica: lista de páginas com título, categoria e path para leitura completa.

Exemplo real que obtive ao buscar webhooks:

5.2 get_documentation_page

Retorna o conteúdo integral de uma página da documentação.

Exemplo:

{
  "language": "pt_br",
  "path": "gerenciar-reclamacoes",
  "siteId": "MLB"
}

A resposta inclui texto completo, exemplos de payload, endpoints (GET /post-purchase/v1/claims/{id}), campos da API e links relacionados, tudo dentro do contexto do agente.

5.3 mcp_auth

Reautentica o servidor quando a sessão expira ou o status fica em needsAuth. Chamada sem parâmetros; dispara novo fluxo OAuth.

6. Casos de uso práticos

6.1 Implementar webhooks sem caçar doc no site

Prompt sugerido no Cursor: "Consulte a documentação do Mercado Livre via MCP sobre notificações de webhooks. Quais tópicos existem para pedidos, envios e reclamações? Qual o payload esperado e o tempo máximo de resposta HTTP?"

O agente tende a chamar search_documentation para achar produto-receba-notificacoes, get_documentation_page para ler tópicos (orders_v2, shipments, post_purchase) e responder com regras como HTTP 200 em até 500ms e estrutura do payload.

Isso evita implementar com tópico desatualizado, por exemplo, tratar só claims quando a doc atual usa post_purchase com actions: ["claims"].

6.2 Entender migrações de API antes de codar

Cenário real: você tem um controller Rails com when 'claims', mas a doc atual diz:

{
  "resource": "post-purchase/v1/claims/5108684499",
  "topic": "post_purchase",
  "actions": ["claims"]
}

Com o MCP, o agente lê Gerenciar reclamações e Notificações e aponta a divergência antes do deploy.

6.3 Mapear endpoints para implementação

Prompt: "Via MCP do Mercado Livre, qual o fluxo completo para processar uma devolução (claim com return)? Quais GETs preciso fazer após receber o webhook?"

Resposta esperada (baseada na doc):

• ▸GET /post-purchase/v1/claims/{claim_id}
• ▸Verificar related_entities ou type: "return"
• ▸Se aplicável: GET /post-purchase/v2/claims/{id}/returns
• ▸Extrair order_id e atualizar seu sistema

6.4 Onboarding de devs no time

Novo integrante pergunta: "Onde habilito webhooks no painel?" A doc via MCP deixa claro: não é no portal de docs, é no DevCenter, editando a aplicação em Configurações de notificações.

6.5 Gerar código alinhado à doc oficial

Combinando MCP + Agent mode: "Leia via MCP a doc de notificações e crie um service object Rails que receba o webhook, valide topic/resource/user_id e enfileire job assíncrono."

O agente usa a doc como fonte de verdade para nomes de campos, tópicos e tratamento de erro, reduzindo código baseado em Stack Overflow desatualizado.

7. Fluxo recomendado no dia a dia

1. Dúvida sobre integração ML
        ↓
2. Perguntar ao agente (modo Ask ou Agent)
        ↓
3. Agente chama search_documentation
        ↓
4. Agente lê páginas relevantes com get_documentation_page
        ↓
5. Resposta contextualizada + sugestão de código
        ↓
6. Validar sempre contra a URL oficial citada na resposta

8. Troubleshooting

Fonte: seção Erros e soluciones da doc oficial do MCP Server.

9. MCP oficial vs. MCP comunitário

Para desenvolver integrações (webhooks, OAuth, claims, envios), use o oficial. Para análise de mercado ou protótipos de busca, considere o comunitário.

10. Limitações atuais (honestas)

• ▸Só documentação, não substitui MercadoLibreApi::Orders.fetch no seu backend.
• ▸Sem contexto do seu código, o MCP não lê seu repo; combine com o agente no Cursor.
• ▸Busca por relevância, nem sempre a primeira página é a ideal; refine o query.
• ▸Doc multi-país, use siteId: "MLB" para filtrar regras do Brasil quando fizer diferença.

Conclusão

O MCP oficial do Mercado Libre é uma ponte entre a documentação viva da API e o IDE agêntico. Não executa operações na sua conta, mas muda como você integra:

• ▸Menos tempo caçando páginas em developers.mercadolivre.com.br
• ▸Respostas ancoradas na doc oficial (webhooks, OAuth, claims, envios)
• ▸Menos risco de implementar tópicos ou payloads desatualizados
• ▸Onboarding mais rápido para devs que nunca integraram com ML

A pergunta prática ao iniciar uma feature de marketplace: "O agente consultou a doc via MCP antes de sugerir código?" Se não, peça explicitamente, a diferença entre adivinhar e integrar corretamente costuma estar em uma página como Notificações ou Gerenciar reclamações.

Referências

• ▸Mercado Libre MCP Server, documentação oficial: https://developers.mercadolibre.com.uy/mcp-server
• ▸Portal Developers Mercado Livre Brasil: https://developers.mercadolivre.com.br/pt_br
• ▸Notificações (webhooks): https://developers.mercadolivre.com.br/pt_br/produto-receba-notificacoes
• ▸Crie uma aplicação no Mercado Livre: https://developers.mercadolivre.com.br/pt_br/crie-uma-aplicacao-no-mercado-livre
• ▸Gerenciar reclamações: https://developers.mercadolivre.com.br/pt_br/gerenciar-reclamacoes
• ▸DevCenter, Minhas aplicações (Brasil): https://developers.mercadolivre.com.br/devcenter/
• ▸Model Context Protocol, especificação: https://modelcontextprotocol.io/
• ▸mercadolibre-mcp comunitário (GitHub): https://github.com/dan1d/mercadolibre-mcp
• ▸MVC escalável no Rails (artigo relacionado): https://israelsantos.tech/artigos/rails-mvc-escalavel-service-objects-concerns