Epicure MCP Server

Public, anonymous, read-only Model Context Protocol (MCP) server for the Epicure ingredient-embedding model.

The server is stateless and deterministic: every tool call is a pure function of the request arguments plus the bundled artefacts. There are no external model calls, no embedding fallback, and no user state.

Designed for Azure Container Apps deployment with a replica cap to bound spend.

Logging and analytics

Each tool call produces one structured JSON log line containing the tool name, the call arguments, a truncated preview of the result (max 4 KB), the latency, success flag, and a hashed client IP (SHA-256 with a salt that rotates at UTC midnight and never leaves the running replica). Raw IPs are never stored or logged. Logs are forwarded to the deployment operator's log store (Azure Log Analytics by default) for aggregate usage analytics only.

Tools

Local development

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Build the data bundle from a local epicure-data checkout
python scripts/build_data.py --source-repo /path/to/epicure-data --out-dir data
python scripts/verify_data.py --data-dir data

# Run server
python -m epicure_mcp.server

# Smoke-test
curl http://localhost:8080/healthz

Endpoints:

Environment variables

The server is fully self-contained: there is no upstream API call. find_pairings runs the graph algorithm locally against the bundled embeddings + ingredient metadata.

Bundled data

The data/ directory is committed to this repo (~13 MB) so the server is fully self-contained: clone, build, deploy. No external data checkout required.

Refreshing the bundle when the model changes

When a new epicure-data training run lands, regenerate the bundle from a local checkout and commit the diff:

python scripts/build_data.py --source-repo /path/to/epicure-data --out-dir data
python scripts/verify_data.py --data-dir data
git add data/ && git commit -m "data: refresh bundle from <run-id>"

Azure Container Apps deployment

One-time setup

You need the Azure CLI installed and an authenticated session:

# Install az (Ubuntu/Debian)
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

az login
az account set --subscription "<your-sub-id>"

# Provision RG + ACR + ACA env + container app + GitHub OIDC federation
./scripts/azure_setup.sh

The script prints the GitHub Actions secrets / variables you must set on the repo for the deploy workflow to function.

Continuous deployment

.github/workflows/deploy.yml runs on every push to main:

1. Checks out the repo (the data bundle is already inside it).

2. Builds & pushes the Docker image to ACR via OIDC.

3. Calls az containerapp update and waits for the new revision to answer /healthz.

Scaling and rate limit

• --max-replicas 3 puts a hard cap on burst spend.

• --min-replicas 0 allows scale-to-zero (cold start ~3-5 s while the bundle loads).

• The in-process token bucket limits each client IP to 60 req/min with a burst of 10. Limits drift across replicas; precision is bounded by the replica cap.

Connecting clients

Once deployed, the MCP endpoint is https://<aca-fqdn>/mcp.

Claude.ai

Add a custom MCP server in Settings -> Integrations -> Add custom:

Name: Epicure
URL : https://<aca-fqdn>/mcp
Auth: None

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "epicure": {
      "transport": "streamable-http",
      "url": "https://<aca-fqdn>/mcp"
    }
  }
}

ChatGPT (custom GPT)

Use Actions with the OpenAPI schema generated from the MCP tools/list response.

License

MIT