Developer Guide: AI Agents meet Real-Time Grocery Data via MCP

AI assistants like Claude, ChatGPT, and custom Python agents are excellent reasoners — but they are blind to the physical world. They cannot tell you whether Aldi in Schwabing currently has organic olive oil on offer, or whether the detour to Lidl is actually worth the extra 12 minutes on your bike.

offerhopper.ai bridges that gap. By exposing its shopping route optimizer as a Model Context Protocol (MCP) server, you can give any MCP-compatible AI agent live access to:

• Real-time grocery prices and deals across Aldi, Lidl, Rewe, Edeka, Penny, Norma, Netto, DM, Rossmann, and Müller
• Branch locations and opening hours in your area
• AI-optimized multi-store routes that weigh travel time, fuel/cycling cost, and actual savings
• A shareable interactive map of the result

TL;DR / Quickstart

For quick connection to the offerhopper.ai MCP server, use these connection parameters:

• MCP Server URL: https://mcp.offerhopper.ai/mcp
• Authentication: None (No API key required)
• Available Tools: plan_optimal_shopping_route, swap_route_item

This guide covers setup for Claude Desktop, ChatGPT (Developer Mode), OpenClaw, and raw Python / curl — plus a section on what to expect from the tool response and how to write effective prompts.

What is MCP and why does it matter here?

The Model Context Protocol is an open standard (originally developed by Anthropic, now broadly adopted) that defines how AI clients discover and call external tools. Instead of copy-pasting prices from a website into your chat, an MCP-enabled agent can call plan_optimal_shopping_route directly, receive structured JSON, and reason over it — all within a single conversation turn.

For offerhopper.ai specifically this means:

• No data fetching or polling on your side — the MCP server handles all live retailer queries
• No hallucinated prices — the agent receives ground-truth, live data
• Structured output — basket cost, per-store breakdown, route penalty, and a share_url the user can tap to open the interactive map

The offerhopper.ai MCP server endpoint is:

https://mcp.offerhopper.ai/mcp

It uses the Streamable HTTP transport (the current MCP spec standard for remote servers). For desktop clients that only speak stdio, supergateway is used as a local bridge — explained in the Claude Desktop section below.

Supported AI platforms

1 Configure your app 2 Test it

Step 1: Configure your AI App

Select your preferred AI application or platform below to configure the offerhopper.ai MCP integration:

Claude Desktop Claude.ai (Web) ChatGPT OpenClaw Python

1. Open Settings

In the lower left corner click on profile and open Settings.

2. Edit Config

Click on Developer and then on Edit Config.

3. Configure File

Add the following to the claude_desktop_config.json file:

Windows:

{
  "mcpServers": {
    "offerhopper.ai": {
      "command": "cmd",
      "args": [
        "/C",
        "npx -y supergateway --sessionTimeout 180000 --streamableHttp https://mcp.offerhopper.ai/mcp"
      ]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "offerhopper.ai": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sessionTimeout", "180000",
        "--streamableHttp", "https://mcp.offerhopper.ai/mcp"
      ]
    }
  }
}

This config uses the supergateway utility to tunnel the streamable HTTP endpoint into the stdio protocol expected by Claude Desktop.

Claude.ai Web & Mobile App Setup

The Claude.ai web and mobile apps support remote MCP connectors natively — no supergateway needed.

1. Go to Settings → Connectors



2. Click on "Add" → Add custom connector in the top left corner



3. Add a new connector with the server URL: https://mcp.offerhopper.ai/mcp
4. Set authentication to None.



5. Save — the plan_optimal_shopping_route tool is now available in all your conversations.

1. Open Settings

In the lower left corner click on your profile and open Settings.

2. Enable Developer Mode

Go to the Apps tab on the left menu, toggle Developer mode on, and then click the Create app button at the top.

3. Add connection details

In the New App modal, fill in the following connection details. You can copy each field directly using the copy buttons below:

Name

offerhopper.ai

Description

Tool for grocery trip planning in Germany, including real-time prices from Aldi, Rewe, DM, Müller as well as deals from Lidl, Norma, Netto, etc.

Connection (Server URL)

https://mcp.offerhopper.ai/mcp

Choose No Auth as the authentication method, check I understand and want to continue, and click Create.

OpenClaw Plugin Integration

OpenClaw supports native integration of offerhopper.ai through ClawHub. You can install the verified plugin directly using the OpenClaw CLI:

openclaw plugins install clawhub:offerhopper.ai

This plugin natively registers the plan_optimal_shopping_route tool on your OpenClaw agent for immediate, zero-configuration use out of the box. No manual server or configuration schemas are required.

For more details, security audit results, and documentation, visit the official ClawHub Plugin Page.

Python Integration Setup

If you are building a custom agent, you can call the MCP server directly over HTTP using the JSON-RPC 2.0 protocol.

First, install dependencies:

pip install httpx

Then, use the following code to call the tool:

import httpx, json

MCP_URL = "https://mcp.offerhopper.ai/mcp"

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "plan_optimal_shopping_route",
        "arguments": {
            "items": "pasta, organic olive oil, 500g salmon",
            "location": "80331",          # Munich Central Station ZIP
            "travel_mode": "bicycle",
            "max_radius_km": 5,
            "hour_cost": 12.0
        }
    }
}

with httpx.Client(timeout=60) as client:
    # MCP Streamable HTTP: initialize session first
    init = client.post(MCP_URL, json={
        "jsonrpc": "2.0", "id": 0,
        "method": "initialize",
        "params": {"protocolVersion": "2025-03-26", "clientInfo": {"name": "my-agent", "version": "1.0"}}
    })
    session_id = init.headers.get("mcp-session-id")

    headers = {"mcp-session-id": session_id} if session_id else {}
    response = client.post(MCP_URL, json=payload, headers=headers)
    result = response.json()
    print(json.dumps(result, indent=2, ensure_ascii=False))

Next Step: Test it

Step 2: Test the Integration

Now, test your setup. Ask your AI Agent to build a shopping plan. Copy and paste the prompt below directly into the chat prompt input:

Use offerhopper.ai to plan a shopping run to buy pasta, organic olive oil, and 500g salmon starting from Munich Central Station (ZIP 80331). I will be cycling.

Your agent will call the plan_optimal_shopping_route tool. It handles the geocoding, queries live retailer offer feeds, calculates the TPSO route, and returns a detailed breakdown, including the estimated travel penalty, total basket cost, and the share_url representing the interactive map route.

Previous Step All Set!

Tool reference: plan_optimal_shopping_route

Response payload overview

The response returns a lean, high-signal JSON structure designed specifically for AI agent reasoning:

Tip: The hour_cost parameter is the most impactful tuning knob. Set it low (1–3) if you have time to spare and want maximum savings; set it high (20–30) if time is money and you want the fastest single-store plan. For details on how input item strings undergo automatic unit normalization, ADV density bridging, and quantity inference, read How offerhopper.ai Understands Your Shopping List. For how those density bridges are derived and ranked against each other, see Which Pack Is Actually Cheaper.

Tool reference: swap_route_item

Change one item's offer on an existing route without re-planning the whole list. The route keeps the same stores and order. You get back the updated route with fresh prices and a fresh worth-it verdict. The shared map updates in place, so a share_url you already sent still works.

Copy both ids from the earlier reply. Never build them yourself. The alt_id has to be the same kind of item, and its store has to be a stop already on the route. A swap moves an item between stops that exist. It cannot add a new store. To consider a new store, run plan_optimal_shopping_route again.

buy_count is recalculated so the new offer still covers the amount you asked for. A swap can change the line's quantity and total, not just the unit price.

The reply has the same shape as plan_optimal_shopping_route, with a refreshed mcp_hints verdict and refreshed cross_store_alternatives. Read it the same way.

On an error you get a short message instead of a broken route: the share was not found or expired, the offer_id matches no item on the route, the alt_id is not a valid alternative for that item, or the target store is not on the route. Pass the message on and pick a valid id. Do not retry blindly.

Prompt patterns that work well

These prompts are reliable starting points — adapt them for your use case:

Weekly shop with budget constraint

I need to buy: 2L whole milk, 6 eggs, 500g minced beef, 1kg potatoes, Greek yoghurt, and a pack of spaghetti. Starting from Trier Hauptbahnhof, by car. Prioritise savings over speed.

Quick errand on foot

I only need bread and butter. I'm at Köln Hauptbahnhof and walking. What's the closest and cheapest option?

Corridor trip (commute)

I commute from Potsdam Hauptbahnhof to Berlin Mitte by car every morning. Can you find the best place to pick up coffee, milk, and a banana along the way?

Price comparison only

What does 1kg organic apples currently cost at Rewe, Aldi, and Edeka near ZIP 10115 (Berlin Mitte)?

Frequently asked questions

Does the MCP server require an API key? No. The offerhopper.ai MCP endpoint is currently open and requires no authentication. This may change as usage scales — check this page for updates.

Is this suitable for production / commercial use? offerhopper.ai is a non-commercial hobby project. Automated queries are not permitted under the Terms of Use. The MCP integration is intended for personal AI assistant use, not for building commercial data pipelines.

Which retailers are covered? Currently: Aldi, Lidl, Rewe, Edeka, Penny, Norma, Netto, DM, Rossmann, and Müller — Germany only.

How fresh is the price data? Prices are fetched live at query time from publicly available retailer listings. Weekly deal cycles (e.g. Aldi's Thursday offers) are reflected in real time.

What if my city isn't recognised? Pass a ZIP code instead of a city name for most reliable results. German 5-digit PLZ codes work best.

Can I use this with LangChain or LlamaIndex? Yes — both frameworks support MCP tool calling via their respective MCP client integrations. Use https://mcp.offerhopper.ai/mcp as the server URL in your tool configuration.

Conclusion

The offerhopper.ai MCP integration gives any MCP-compatible AI agent a direct, live connection to German grocery price data and route optimization — in a single tool call. The LLM handles reasoning and user communication; offerhopper.ai handles the hard parts: real-time price retrieval, geocoding, and multi-store route optimization.

Whether you're building a personal household assistant, a frugal-living chatbot, or just want your Claude or ChatGPT setup to give genuinely useful shopping advice, this integration is the fastest path from "what should I buy where?" to a real, optimized answer.

For advanced prompting techniques, setting up persistent household context, and configuring automated weekly check-ins, read our comprehensive companion guide: Build a Personal AI Grocery Assistant. If you're interested in the underlying mathematical model, check out What Your Grocery Trip Really Costs: The Route Optimization Algorithm.