@gridscoot/mcp

@gridscoot/mcp

MCP server for Gridscoot — AU price comparison for AI agents.

What It Does

A Model Context Protocol (MCP) server that lets Claude, Cline, Continue.dev, and other MCP-compatible clients call Gridscoot's catalogue to find the cheapest in-stock listing of any product at an Australian retailer. Includes 365-day price history (so an agent can tell a genuine deal from a "marked up to mark down" trick) and live stock signals.

Six tools cover the full price-discovery loop: free-text search, per-product comparison across retailers, price history, real-time stock check, retailer directory, and a price-drop alert subscription.

The same tool registry is the canonical source for both this stdio package and the HTTP transport at /api/mcp on the deployed Gridscoot host (per ADR-0004).

Quickstart

npx -y @gridscoot/mcp

You'll typically not invoke the binary directly — point your MCP client config at it instead (see below).

Configure Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gridscoot": {
      "command": "npx",
      "args": ["-y", "@gridscoot/mcp"],
      "env": {
        "GRIDSCOOT_API_KEY": "gs_test_..."
      }
    }
  }
}

Restart Claude Desktop. The six Gridscoot tools then appear in the tool picker.

Configure Cline (VS Code)

Open Cline's MCP settings (Cline: Open MCP Settings) and add to the mcpServers block:

{
  "mcpServers": {
    "gridscoot": {
      "command": "npx",
      "args": ["-y", "@gridscoot/mcp"],
      "env": {
        "GRIDSCOOT_API_KEY": "gs_test_..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configure Continue.dev

In ~/.continue/config.yaml (or the JSON variant):

mcpServers:
  - name: gridscoot
    command: npx
    args:
      - "-y"
      - "@gridscoot/mcp"
    env:
      GRIDSCOOT_API_KEY: gs_test_...

Tool Reference

Tool	Description	Write?	Required	Optional
search_products	Free-text search across all connected AU retailers; returns ranked offers with current pricing, availability, and delivery estimates.	no	query	max_price_aud, min_price_aud, location_postcode, delivery_by, in_stock_only (default true), category_hint, max_results (default 10, max 50)
compare_product	All retailer offers for a known canonical product.	no	product_id	gtin, location_postcode, include_shipping (default true), sort_by (total_price | item_price | delivery_speed | retailer_rating)
get_price_history	Trailing price history across retailers — used to evaluate whether a current deal is genuine or business-as-usual.	no	product_id	days (default 90, max 365), retailers
check_availability	Real-time stock check at a specific retailer, including click-and-collect where supported.	no	product_id, retailer_id	postcode
list_retailers	Lists retailers indexed by Gridscoot. Useful for meta queries and as a filter for other calls.	no	—	category, country (default AU; NZ from Phase 2+)
track_price	Subscribes a user to price-drop alerts; returns a subscription ID. Write tool — dry-run-gated when the calling key is in dry-run mode.	yes	product_id, user_token	target_price_aud, retailers

All tools return a single text-content MCP response with a JSON envelope; isError: true is set on failure. Every input field has a Zod-described shape and a .describe() annotation that surfaces in tools/list.

Scopes

API keys carry one or more scopes. Each tool requires a scope to be callable:

• mcp:read — grants search_products, compare_product, get_price_history, check_availability, list_retailers.
• mcp:track_price — grants track_price (the only write tool in the v0 surface). Independently grantable so a buyer can issue read-only keys to subagents and reserve write capability for a trusted parent.

Keys bound to an agent identity in dry-run mode have their write calls queued for review instead of executed directly. See Authentication.

Authentication

The MCP server reads the Bearer token from the GRIDSCOOT_API_KEY environment variable and forwards it to Gridscoot's backend in the Authorization header on every outbound request. Tokens have the format gs_<env>_<random> (e.g. gs_test_..., gs_live_...). The env var is read per-call, so rotated keys take effect without restarting the MCP server.

If GRIDSCOOT_API_KEY is unset, the server logs a one-time warning to stderr and lets requests proceed unauthenticated — the backend will respond with 401 and the tool result surfaces the error to the agent.

Create a key from the Gridscoot dashboard at /account/keys. Plaintext is shown once at creation — copy it into your MCP client config immediately and don't commit it to source control.

Dry-run mode

Set GRIDSCOOT_MCP_DRY_RUN=true (or 1) in the MCP client's env block to put the server into dry-run mode. Write tools (track_price) are not invoked; the server returns a { dryRun: true, would_call: { tool, params } } envelope instead. Read tools are unaffected. Use this when wiring a new agent and you want to inspect what it would mutate before letting it loose. The HTTP transport at /api/mcp enforces the same gate based on the resolved agent's dry_run_until window in the database.

Rate Limits

Per the Gridscoot terms, the default per-key limits are:

• 60 calls/min across the five read tools (search_products, compare_product, get_price_history, check_availability, list_retailers).
• 20 calls/hour for track_price (the write tool).

A 429 response includes the reset window. Treat these as upper bounds; for catalogue-scale workloads use the bulk REST surface at /api/v1/* instead of fanning out through MCP.

Local-LLM Users

Gridscoot ships a free local-LLM tier — zero cost to users running Ollama, llama.cpp, or any local Claude-compatible runtime. Configure the MCP server the same way; the tier difference is enforced server-side based on the calling key's plan. The full search/compare/history surface is open on the free tier; the only restriction is track_price, which requires an authenticated buyer account.

Development

git clone https://github.com/TBD/gridscoot.git
cd gridscoot
npm install
npm run typecheck                       # full monorepo
npm run --workspace=@gridscoot/mcp build

The MCP package shares its tool registry with the HTTP transport at apps/web/src/app/api/mcp/route.ts. Edits to packages/mcp/src/tools/*.ts apply to both surfaces.

To run the stdio server against a local backend:

GRIDSCOOT_API_BASE=http://localhost:3000 \
GRIDSCOOT_API_KEY=gs_test_... \
  node --experimental-strip-types ./src/server.ts

Optional Peers

The @gridscoot/mcp/middleware subpath (auth + rate-limit + dry-run helpers for self-hosted HTTP deployments) declares @supabase/supabase-js and @gridscoot/observability as optional peer dependencies. The stdio binary and the tool registry never load them; they're only resolved if you import from @gridscoot/mcp/middleware. External consumers running the stdio server can ignore them entirely — npm install @gridscoot/mcp succeeds with no peer warnings.

License + Provenance

MIT (see LICENSE). Per ADR-0005 the tool registry is recreated in-tree — there are no runtime third-party MCP wrapper dependencies; the only MCP runtime is the official @modelcontextprotocol/sdk. Schemas are authored in Zod and converted to JSON Schema via zod-to-json-schema for the MCP tools/list response.

Contact

• Issues: https://github.com/TBD/gridscoot/issues
• Email: TBD (zero-spend posture; no project domain yet)

Gridscoot is in Phase 7 launch prep. Status, ADRs, and roadmap live in the monorepo README.