Periskop

Descoberta de produtos web aberta para Agentes de IA

Documentação

Periskop — Descoberta de Produtos para Agentes de IA

Descoberta de produtos para agentes de IA. Uma única chamada MCP transforma uma intenção de compra em linguagem natural em resultados de produtos estruturados e ranqueados — melhores escolhas, alternativas, combos, ressalvas, preços e links para lojas — de diversas lojas independentes na web comercial aberta.

Periskop é um servidor MCP remoto e hospedado (código fechado). Você se conecta pelo endpoint HTTPS público com uma chave de API Periskop — nada para instalar ou executar. É a camada de descoberta para o comércio agêntico: um agente pergunta em linguagem natural e o Periskop retorna produtos ranqueados com links de volta para a loja. Ele para na descoberta — sem checkout, sem pagamentos, sem pedidos.

Site: https://periskop.ai
Portal do desenvolvedor / obter chave de API: https://periskop.ai/developer
Documentação: https://periskop.ai/developer/docs
Endpoint MCP: https://mcp.periskop.ai/v1/mcp (HTTP Streamable, JSON-RPC 2.0)

Para quem é

Qualquer produto que precise transformar intenção em resultados de produtos confiáveis sem possuir checkout — plataformas e orquestradores de agentes, plataformas de trabalhadores de IA, assistentes de compras com IA, agentes de navegador, copilotos de comércio, sistemas de recomendação, fluxos de compras e sourcing B2B, monitores de preços e ofertas, bots de reposição/novo pedido, aplicativos de presentes, fluxos de revenda e arbitragem, e ferramentas de compras acessíveis. Concretamente: um agente que planeja uma viagem de acampamento e retorna o equipamento, um copiloto de compras comparando opções entre fornecedores, ou um assistente de voz que apresenta o produto certo a partir de uma única frase.

O que faz (e o que não faz)

O Periskop retorna resultados de produtos e links para lojas apenas. Ele não conclui checkout, não cria carrinhos na loja, não processa pagamentos, não reserva estoque nem compra itens. O usuário sempre conclui qualquer compra no site da própria loja. Cada resposta traz um bloco purchase_boundary reafirmando isso.

Conexão


Endpoint	`https://mcp.periskop.ai/v1/mcp`
Transporte	HTTP Streamable — JSON-RPC 2.0 sobre HTTP POST (uma resposta JSON por POST; sem SSE)
Protocolo de rede	`2024-11-05`
Autenticação	`Authorization: Bearer <YOUR_PERISKOP_API_KEY>` (as chaves têm o formato `dp_…`)
Obter uma chave	https://periskop.ai/developer

Requisições não autenticadas recebem 401 com um cabeçalho WWW-Authenticate: Bearer.

Nota: o Periskop também suporta OAuth 2.1 (Authorization Code + PKCE) para hosts que preferirem (os tokens têm o formato dpo_…). A chave de API é o caminho mais simples e é tudo que você precisa para as configurações abaixo.

Ferramentas

Todas as ferramentas aceitam um único argumento de objeto JSON. Os esquemas abaixo são a superfície pública das ferramentas.

`run_shopping_discovery`

Encontre, escolha, navegue, recomende, obtenha o melhor produto ou monte um combo a partir de uma solicitação em linguagem natural. O único campo obrigatório é prompt.

Campo	Tipo	Obrigatório	Observações
`prompt`	string	✅	Intenção de compra em linguagem natural
`mode`	string \| null		`auto` \| `browse` \| `recommend` \| `best` \| `bundle` (padrão `auto`)
`store`	string \| null		`auto`, um ID de loja ou um nome/dica de loja
`country`	string \| null		ex.: `PT`, `ES`
`currency`	string \| null		ex.: `EUR`
`language`	string \| null		ex.: `en`, `pt`
`max_results`	integer \| null		Limite de produtos retornados
`response_format`	string \| null		`full` (padrão) \| `simple`

`get_discovery_result`

Recupere um resultado anterior pelo result_id. Os resultados são temporários e podem expirar.

Campo	Tipo	Obrigatório
`result_id`	string	✅
`response_format`	string \| null

`discover_supported_stores`

Inspecione as lojas públicas que o Periskop pode usar. Retorna apenas as capacidades públicas das lojas.

Campo	Tipo	Obrigatório
`country`	string \| null
`category`	string \| null
`capability`	string \| null (`search` \| `bundle` \| `product_links`)

`report_result_feedback`

Informe se um resultado foi bom, ruim ou misto.

Campo	Tipo	Obrigatório
`result_id`	string	✅
`rating`	string (`good` \| `bad` \| `mixed`)	✅
`reason`	string \| null
`selected_product_id`	string \| null
`freeform_feedback`	string \| null

`suggest_store_coverage`

Sugira uma loja/comerciante/marketplace que o Periskop deva suportar no futuro. Não cobrável. Não pesquisa nem rastreia a loja e não garante suporte futuro.

Campo	Tipo	Obrigatório
`store_name`	string	✅
`store_url`	string \| null
`country` / `region` / `category`	string \| null
`context`	string \| null (ex.: `unsupported_store`, `no_match`)

Exemplo

Requisição (JSON-RPC `tools/call`)

curl -sS -X POST https://mcp.periskop.ai/v1/mcp \
  -H "Authorization: Bearer YOUR_PERISKOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "run_shopping_discovery",
      "arguments": { "prompt": "wireless noise-cancelling headphones for travel under 200€", "mode": "best" }
    }
  }'

Resposta (reduzida — dados de exemplo/fictícios, não reais)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result_id\":\"res_example_8f2a1c\",\"mode_used\":\"best\",\"products\":[{\"title\":\"SampleAudio Aero NC\",\"price\":\"€179.00\",\"currency\":\"EUR\",\"merchant\":\"Example Store\",\"url\":\"https://store.example/p/aero-nc\",\"role\":\"best_pick\"},{\"title\":\"Acme Quietline 2\",\"price\":\"€149.00\",\"currency\":\"EUR\",\"merchant\":\"Example Store\",\"url\":\"https://store.example/p/quietline-2\",\"role\":\"alternative\"}],\"caveats\":[\"Prices and availability may change on the merchant site.\"],\"purchase_boundary\":{\"checkout_created\":false,\"payment_processed\":false,\"stock_reserved\":false,\"user_must_complete_purchase_on_merchant_site\":true}}"
      }
    ]
  }
}

O payload estruturado é retornado como texto em result.content[0].text. Cada resposta e o cabeçalho de resposta X-Request-ID carregam um ID de requisição por chamada.

Preços (resumo)

Carteira pré-paga, cobrada apenas em requisições de descoberta bem-sucedidas. Erros de autenticação, requisições malformadas, falhas internas/em tempo de execução, limites de taxa e ausência de correspondência nunca são cobrados. Veja a taxa atual em https://periskop.ai/developer/billing.

Configuração do cliente

Configurações prontas para copiar e colar estão em config-snippets/: Cursor (.cursor/mcp.json), Claude Desktop, Claude Code e um exemplo bruto de curl.