Model Context Protocol · para agentes de IA

Conecte seu agente
ao BuscaZap.

Uma ferramenta MCP que descobre produtos reais à venda em Mercado Livre, Amazon, Shopee, Shein e +100 lojas — já com o link de compra pronto. Seu agente chama sozinho, sem programar cada request.

POST Streamable HTTP · JSON-RPC 2.0stateless sem sessãoOAuth 2.0 client_credentials + authorization_code (PKCE)API Key Bearer / X-API-Key

01 — conectar

Endereço e transporte

O MCP fala Streamable HTTP: seu cliente faz POST no endpoint com uma mensagem JSON-RPC e recebe uma resposta JSON. Sem SSE, sem sessão.

Endpoint MCP: https://buscazap.com.br/mcp
Token OAuth: https://buscazap.com.br/oauth/token
Authorize: https://buscazap.com.br/authorize
Discovery: https://buscazap.com.br/.well-known/oauth-authorization-server
Protocolo: MCP 2025-06-18

Credenciais: seu client_id / client_secret (OAuth) ou sua API key são entregues por canal seguro separado — nunca aparecem nesta página nem no repositório.

02 — autenticar

Dois jeitos de autenticar

Escolha conforme o seu host. Apps interativos (ex.: Claude) usam OAuth com descoberta automática; integrações máquina-a-máquina usam client_credentials ou uma API key.

OAuth 2.0

Client credentials (máquina-a-máquina)

Troque client_id + client_secret por um access token (Bearer, validade 1h) e use no /mcp. Também suportamos authorization_code + PKCE para conectores interativos.

curl -X POST https://buscazap.com.br/oauth/token \
  -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET" \
  -d grant_type=client_credentials

API Key

Chave estática (mais simples)

Se você recebeu uma API key, mande direto no header — sem passo de token.

curl -X POST https://buscazap.com.br/mcp \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

03 — configurar o cliente

Cole a config e conecte

É aqui que a maioria empaca — então já vai pronto pra colar.

Claude (app / web) — Conector personalizado

Em Settings → Connectors → Add custom connector, cole a URL abaixo. O Claude descobre o OAuth sozinho e pede seu client_id / client_secret.

https://buscazap.com.br/mcp

Claude Desktop — arquivo de config

No claude_desktop_config.json, use a ponte mcp-remote (o OAuth abre no navegador na 1ª conexão):

{
  "mcpServers": {
    "buscazap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://buscazap.com.br/mcp"]
    }
  }
}

04 — a ferramenta

A ferramenta

Seu agente descobre isto sozinho via tools/list. Você não monta o termo de busca: passa o contexto da conversa e o BuscaZap deriva o termo e ranqueia os produtos contra ele.

buscar_produtos_por_contexto

Dado o RESUMO de uma conversa com um cliente, encontra produtos reais à venda em Mercado Livre, Amazon, Shopee, Shein e mais de 100 lojas, já com o link de compra pronto. Use esta ferramenta assim que o cliente demonstrar intenção de comprar algo. Você NÃO precisa montar o termo de busca: passe o contexto (o que a pessoa quer, para quem, cor/tamanho/faixa de preço, marcas rejeitadas) e o BuscaZap deriva o termo e ranqueia os produtos contra esse contexto. Retorna uma lista de produtos padronizados.

Parâmetro	Tipo		Descrição
context	string	obrigatório	Resumo/histórico da conversa em texto livre: o que a pessoa quer, para quem, cor/tamanho/faixa de preço, marcas que ela rejeitou. Quanto mais limpo, melhor o termo gerado e o ranqueamento.
limit	integer	opcional	Máximo de produtos a retornar. Omita para receber todos os relevantes.
llm	string · gemini deepseek kimi grok	opcional	Qual LLM conduz a busca (extrai o termo do contexto e ranqueia os produtos). Omita para o padrão 'gemini' (mais rápido e já ajustado).

Escolha de LLM (opcional): o campo llm deixa você escolher o modelo que conduz a busca por chamada. Omita para o padrão (gemini, o mais rápido e já ajustado); os demais rodam sob demanda.

05 — chamar

Exemplo ponta a ponta

Liste as tools e faça uma busca. Troque $TOKEN pelo access token do passo 02 (ou use a API key direto).

tools/list

curl -X POST https://buscazap.com.br/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/call

curl -X POST https://buscazap.com.br/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "buscar_produtos_por_contexto",
      "arguments": {
        "context": "quero um fone bluetooth ate 200 reais pra corrida",
        "limit": 5
      }
    }
  }'

resposta

{
  "jsonrpc": "2.0", "id": 2,
  "result": {
    "isError": false,
    "structuredContent": {
      "products": [
        {
          "store_name": "Mercado Livre",
          "short_description": "Fone Bluetooth Esportivo ...",
          "price": 149.9, "price_from": 199.9, "discount": "25%",
          "thumbnail": "https://...", "url": "https://..."
        }
      ]
    }
  }
}

06 — erros

Como os erros chegam

O MCP separa erro de protocolo de erro de execução da tool — trate os dois diferente.

Situação	Formato	O agente faz
Método/tool inexistente, request inválido	error (-32601/-32602/-32600)	trata como falha de chamada
A busca lançou exceção (ex.: llm inválido)	result + isError: true	lê o texto do erro e decide
Contexto sem intenção de compra	result + products: []	é sucesso, não erro
Credencial ausente/errada	HTTP 401 + WWW-Authenticate	descobre o OAuth pela metadata