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

Category	Tool	Description
Ported	compare_on_axis	Project two ingredients onto a named axis and compare.
Ported	pairing_score	Overall cosine affinity (300-d) between two ingredients.
Ported	find_pairings	Cluster + bridge graph computed in-process from the bundled embeddings.
Ported	flavour_correlations	Which axes correlate with each other.
Ported	cultural_profile	Cosine to each cuisine direction.
Novel	neighbors	Top-k cosine neighbours.
Novel	morph	Unified SLERP toward a direction, mode, or ingredient.
Novel	list_targets	Catalogue of valid morph targets + angle_deg primer.
Novel	list_factors	Residualised ICA factor catalogue (Claude-labelled poles).
Novel	ingredient_on_factor	Signed projection onto an ICA factor.
Novel	pareto_navigate	Pareto frontier on (proximity, pole-projection).
Novel	closest_mode	Which named GMM mode the ingredient lives in.
Novel	where_on_atlas	Precomputed UMAP (x, y) + nearest-in-2D peers.

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:

Path	Method	Description
/healthz	GET	Liveness probe (does not load the bundle).
/mcp	POST	Streamable HTTP MCP JSON-RPC endpoint.

Environment variables

Var	Default	Description
EPICURE_DATA_DIR	<repo>/data	Bundled-artefact directory.
HOST	0.0.0.0	Bind address.
PORT	8080	Bind port.
RATE_LIMIT_PER_MINUTE	60	Token-bucket refill rate.
RATE_LIMIT_BURST	10	Token-bucket capacity.
MCP_SERVER_NAME	epicure	Reported in the MCP initialize response.

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.

File	Source	Size
embeddings.csv	epicure-data: deploy/payload/embeddings.csv	~10 MB
ingredient_list.csv	epicure-data payload	~75 KB
ingredient_tags.csv	epicure-data payload	~100 KB
consolidated_nodes.csv	epicure-data payload	~70 KB
factor_labels_ica_cooc.json	application/paper/results/	~75 KB
mode_explorer_cooc.json	application/exploratory/results/	~2 MB
supervised_directions.npz	computed (38 axes)	~55 KB
factor_dirs_ica_n20.npy	computed (20 unit vectors)	~25 KB
mode_poles_cooc.npy	computed (150 unit vectors)	~180 KB
umap_coords.csv	computed (1,790 x 2)	~55 KB

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