MCP Integration

The MealCP MCP server exposes the API as tools for AI clients - ask in plain language, and your client queries live grocery prices for you. It’s the standalone mealcp-mcp package (PyPI). It runs as a subprocess of your client over stdio and queries the API over HTTP - no separate deployment, no secrets beyond your API key.

The Model Context Protocol is an open standard that lets AI applications discover and call external tools. Instead of writing HTTP clients yourself, you register the MealCP server once and the client’s model decides when to call it - “how much is oat milk at Tesco in Hungary?” becomes a tool call to search_products without any glue code.

How a tool call flows

1. Your client starts (or reuses) the mealcp-mcp subprocess over stdio.
2. The model picks a tool - search_products or get_price_history - based on the user’s question, and fills in the arguments.
3. The server forwards the call to the matching REST endpoint over HTTPS, authenticated with your MEALCP_API_KEY.
4. Structured JSON returns to the client, and the model composes the answer.

Tool calls map 1:1 to REST endpoints and cost the same 1 credit each (Credits & limits). Everything the tools expose is also available directly over the REST API.

Tools

Tool	Maps to	Description
search_products	GET /v1/search	Keyword search with filters
get_price_history	GET /v1/prices/{id}	Aggregated price-history stats

• search_products accepts a free-text query plus the familiar search filters - country, retailer, brand, category, tag, price bounds, sorting, pagination - and returns product hits with latest prices, unit prices, and retailer links in the same JSON shape as the endpoint it wraps.
• get_price_history accepts a product id from a search hit and a date range, and returns first/last/min/max/average prices, the change over the window, and the observation count - enough for the model to answer “is this cheaper than last month?”

When to use MCP vs REST

• MCP fits interactive use: exploring the data, ad-hoc price checks, and agents that answer questions about grocery prices on demand. Setup is configuration only - no HTTP code to write or maintain.
• REST fits products: fixed query patterns, tight latency control, and budgeted credit usage in a backend you own. Many teams prototype the tool experience over MCP, then implement the same calls against /v1/search in production.

Python

No install step - uvx (ships with uv) runs the server on demand:

uvx mealcp-mcp

opencode (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mealcp": {
      "type": "local",
      "command": ["uvx", "mealcp-mcp"],
      "enabled": true,
      "environment": {
        "MEALCP_API_URL": "https://api.mealcp.com",
        "MEALCP_API_KEY": "mcp_live_..."
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mealcp": {
      "command": "uvx",
      "args": ["mealcp-mcp"],
      "env": {
        "MEALCP_API_URL": "https://api.mealcp.com",
        "MEALCP_API_KEY": "mcp_live_..."
      }
    }
  }
}

Restart the client after editing. It spawns the server, which forwards each search_products / get_price_history call to the API and returns the structured results.

Environment variables

Variable	Required	Description
MEALCP_API_URL	yes	API base URL - https://api.mealcp.com
MEALCP_API_KEY	yes	Your API key (Quickstart)

If tools don’t appear

• Restart the client. Both opencode and Claude Desktop read their config at startup; edits take effect on relaunch.
• Check uvx resolves. Run uvx mealcp-mcp in a terminal - if the command is missing, install uv first.
• Verify the key. A rejected key surfaces as failed tool calls with a 401 underneath. Check the key and its credit balance with GET /v1/me.

JavaScript

npm package coming soon - the Python server works everywhere today.