BestPrice MCP

The official Model Context Protocol server for
BestPrice.gr, Greece's price-comparison service. It gives AI
assistants read-only access to shopping decisions, live product search, offer comparison,
and price history. No account or API key is needed.

https://mcp.bestprice.gr/mcp

• Transport: Streamable HTTP over HTTPS, no authentication
• Official Registry ID: gr.bestprice/mcp
• Server version: 1.8.0
• Public guide: https://www.bestprice.gr/mcp
• Support: https://www.bestprice.gr/contact

This repository holds everything that lives outside the hosted service: the install
manifests for each AI client, a local stdio bridge for hosts that cannot speak HTTP, and
the browser-native WebMCP layer. The server itself is not in this repository.

Tools

All four tools are read-only. They never place orders, create alerts, or read account
data. Results link to a BestPrice product page, never directly to a merchant. Unknown
shipping is reported as unknown, not as free. Search covers safe physical products;
digital goods, services, and age-restricted categories are excluded.

Protocol details

Measured against the live endpoint on 22 September 2026.

• Versions. initialize negotiates 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  and 2024-10-07; a client that asks for any other version is answered with 2025-11-25.
  The 2026-07-28 per-request revision is also served: send the MCP-Protocol-Version,
  Mcp-Method (and, for tools/call, Mcp-Name) headers, and put
  io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in
  every request's _meta. A request that names the revision without that envelope is refused
  with -32602.
• Stateless. No MCP-Session-Id is issued and none is required; DELETE answers 405.
  A GET with Accept: text/event-stream opens a keep-alive stream, but the server never sends
  requests or notifications on it, so a client loses nothing by not opening it.
• Capabilities. tools and resources (the optional MCP Apps UI at
  ui://bestprice/shopping-results-v1.html and the server card at mcp://server-card.json).
  There are no prompts, completions or logging; those methods answer -32601.
• Responses. A client that accepts both application/json and text/event-stream gets a
  one-event SSE response. Accept: application/json, */* or no Accept header gets a single
  JSON body. Every tool returns structuredContent that validates against its outputSchema,
  plus the same result as text for clients that do not pass structured content to the model.
• Errors. An unknown tool is a JSON-RPC error (-32602). Invalid arguments and service
  failures such as an unknown product are tool results with isError: true, so the model can
  read and correct them.
• Limits. JSON request bodies up to 256 KiB (413 above that), a 12-second request
  deadline, and per-client rate limits answered with HTTP 429, JSON-RPC error -32029 and a
  Retry-After header. JSON-RPC batch arrays are refused with 400.
• Browsers. Desktop, CLI and server-side clients send no Origin header and are not
  affected. A browser page may call the endpoint from an allowlisted AI-host origin, from
  bestprice.gr, or from localhost (so MCP Inspector works in direct mode); any other origin
  gets 403.
• Authentication. None. There is deliberately no /.well-known/oauth-protected-resource
  document: clients that probe for one get 404 and connect without OAuth.

Quick start

Every client below connects to the same endpoint. Detailed, provider-specific
instructions including OpenAI, Grok, GitHub Copilot, and Microsoft Copilot Studio are in
docs/provider-setup.md.

Claude

Connect BestPrice to Claude
opens the custom-connector flow with the endpoint prefilled. For Claude Code:

claude mcp add --transport http bestprice-shopping https://mcp.bestprice.gr/mcp

The bundled .mcp.json is the equivalent project-scoped configuration.

Cursor

Add BestPrice Shopping to Cursor
shows the decoded configuration before adding it. The .cursor-plugin/
directory holds the marketplace plugin and an agent skill.

VS Code

Add BestPrice Shopping to VS Code

Gemini CLI and Qwen Code

gemini extensions install https://github.com/TheBestCo/bestprice-mcp
qwen extensions install https://github.com/TheBestCo/bestprice-mcp --consent

Both extensions restrict the imported tools to the four listed above.

Codex, Claude plugins, and Agent Skill hosts

The root plugin.json, mcp.json, and
skills/bestprice-shopping/SKILL.md form a portable
Agent Plugins package: the MCP supplies live shopping data and the Skill teaches the host when and
how to route unbranded Greek shopping intent. .codex-plugin/ remains the
Codex compatibility manifest. .claude-plugin/plugin.json plus the
same root Skill and .mcp.json also make this repository a Claude plugin package.

Gemini API, DeepSeek, Z.ai

Runnable examples live in examples/: the Gemini Interactions API and Genkit,
a DeepSeek Harness plugin entry, and a Z.ai GLM call. Each needs the provider's own API key.
BestPrice needs none.

Any other MCP client

Add a Streamable HTTP server at https://mcp.bestprice.gr/mcp. If the host only supports
stdio servers, use the bridge in this repository:

git clone https://github.com/TheBestCo/bestprice-mcp.git && cd bestprice-mcp
npm ci
node stdio.mjs

The bridge forwards everything to the public endpoint and accepts two environment
variables: BESTPRICE_MCP_URL (default: the public endpoint) and
BESTPRICE_MCP_TIMEOUT_MS (default: 60000). A Dockerfile builds the same bridge for
Glama and similar hosts.

A safe first conversation

1. Ask for a decision: Θέλω κινητό έως 500 ευρώ με NFC και 5G υποχρεωτικά.
   (I want a phone up to 500 euros, NFC and 5G required.)
2. Or search: Find Sony WH-1000XM5 under 300 euros.
3. Pass a returned product_id to compare_offers with postal code 10558.
4. Pass the same product_id to get_price_history for 180 days.

Queries work in Greek or English. Result summaries, catalog data and merchant names come back in Greek.

Search	Compare offers	Price history

Browser-native WebMCP

BestPrice pages register 14 contextual WebMCP tools in compatible browsers, covering the visible
search, filter, sort, product, offer, specification, price-history, and one visible-offer action while
leaving the merchant choice to the shopper. The contracts, fail-closed runtime, deterministic
evaluator, and the 47-case natural-language dataset are in webmcp/.

Discovery

• Official MCP Registry
• Open agent discovery: ard.json,
  ai-catalog.json,
  server card, and the
  provider-neutral BestPrice Shopping skill.
  The ARD examples are deliberately unbranded shopper intents so discovery can match
  “what should I buy?”, delivered-price, and price-timing requests before a user knows BestPrice.
• webmcp.json describes the contextual
  browser tools exposed by BestPrice pages.
• The repository is tagged for the Gemini CLI extension gallery; Google crawls tagged public
  extension repositories, while GitHub Agent Finder can ingest the public MCP catalog and ARD resources.
• Community indexes: Glama,
  WebMCP Registry,
  webmcp.com,
  cursor.directory

Development

npm ci
npm run check   # Biome lint and format
npm test        # node --test: bridge, WebMCP, manifests, dataset

Tests need no network: the bridge is exercised against an in-process fake remote. Node 20
or newer is required; .nvmrc pins 22.

Versioning

Two versions appear in this repository on purpose:

• Package version in package.json and every plugin or extension manifest. It changes
  when this repository's manifests, bridge, or WebMCP layer change, and is tagged vX.Y.Z.
• Server version in server.json and the line near the top of this README. It is the
  version the hosted service reports and is published to the official MCP Registry.

CHANGELOG.md tracks the package version.

Timestamped hosted-service checks are recorded separately. The
7 September Shopping Brain v12 verification
includes its exact gateway revision, sanitized canary results, and scope limits.

Security

Report vulnerabilities privately as described in SECURITY.md.

Contributing

See CONTRIBUTING.md. Issues and pull requests are welcome.

License

Apache License 2.0. Copyright The Best Company S.A. See LICENSE.

Privacy: https://www.bestprice.gr/policies/privacy · Terms: https://www.bestprice.gr/policies/terms