# Periskop — Shopping Decision MCP

> Periskop is a Shopping Decision MCP for AI agents. It turns a
> natural-language shopping request into a structured product decision:
> best picks, alternatives, bundles, caveats, a suggested user-facing
> reply, and merchant links. Periskop returns decision support only — it
> does not check out, take payments, create merchant carts, reserve
> inventory, or place orders. The user completes any purchase on the
> merchant's own site.

## Docs

- [Quickstart](https://periskop.ai/developer/docs?step=quickstart): what Periskop is, who it is for, and your first call in under 5 minutes
- [Manual API-key setup](https://periskop.ai/developer/docs?step=api-key-setup): create a project, generate a key, paste the MCP config
- [OAuth Connect setup](https://periskop.ai/developer/docs?step=oauth-connect): an MCP host connects on a user's behalf
- [Custom agent / REST fallback](https://periskop.ai/developer/docs?step=rest-fallback): call the discovery endpoint directly
- [Workflow platforms](https://periskop.ai/developer/docs?step=workflow-platforms): use Periskop from Dify, n8n, and Pipedream with a dp_ API key
- [Billing wallet](https://periskop.ai/developer/docs?step=billing-wallet): prepaid credits, top-up, monthly cap
- [Response schema](https://periskop.ai/developer/docs?step=response-schema): answer_type, items, bundles, examples
- [Error codes](https://periskop.ai/developer/docs?step=error-codes): HTTP statuses and machine codes
- [Security & commerce boundary](https://periskop.ai/developer/docs?step=security-boundary): what Periskop does not do

## Reference

- [Full agent guide](https://periskop.ai/llms-full.txt): complete agent-readable integration guide
- [MCP server metadata](https://periskop.ai/mcp/server.json): MCP registry descriptor
- [Service status](https://status.periskop.ai): live service status, incidents, and maintenance updates
- [OpenAPI spec](https://periskop.ai/openapi/periskop-shopping-discovery.openapi.yaml): REST discovery endpoint, importable into Dify and other OpenAPI tools (JSON twin at the same path with a .json extension)

## Notes

- MCP endpoint: POST https://mcp.periskop.ai/v1/mcp · REST fallback: POST https://mcp.periskop.ai/v1/mcp/shopping/discover
- Auth: `Authorization: Bearer dp_...` (API key) or a `dpo_...` OAuth token
- Billing: prepaid wallet, €0.007 (70 credit_micros = 0.07 credits) per
  successful shopping decision; the live rate is shown on https://periskop.ai/developer/billing.
  Failures and hard no-match are never billed. HTTP `402 billing_required`
  means top up the wallet — it is a billing signal, never an auth/OAuth
  re-auth signal.
- Coverage requests: when a store is unsupported or results are weak/no_match,
  call `suggest_store_coverage` to record the missing-store demand. It is
  NON-BILLABLE, does not search/scrape the suggested store, and does not
  guarantee Periskop will add it.
- Transport: request/response JSON-RPC 2.0 over HTTP POST. No SSE/streaming.
- Every response body (and the X-Request-ID header) carries `request_id`.