Skip to content

Deploying over HTTP

Defaults

server.run("http") binds to 127.0.0.1:8000 and validates Host and Origin (SEC-8), which blocks DNS-rebinding attacks from web pages against a local server. For a public deployment, name the hostnames clients use:

server.run("http", host="0.0.0.0", port=8080,
           allowed_hosts=["mcp.example.com"], allowed_origins=["https://app.example.com"])

Binding a non-loopback address without allowed_hosts raises an error. Behind a reverse proxy that already checks Host and Origin, pass host_origin_protection=False. For ASGI servers, use server.http_app(), which has the guard on.

Running more than one replica

Anything that must survive a restart or be seen by another replica lives in the store: idempotency records, single-use approval receipts, handles and jobs. Give every replica the same store and signing keys:

import redis.asyncio as redis
from ouncemcp import OunceServer, RedisStore

server = OunceServer("tickets", store=RedisStore(redis.Redis.from_url(REDIS_URL)))

and set OUNCEMCP_CURSOR_KEYS (comma-separated, newest first) to the same value everywhere. MemoryStore, the default, is for one process only.

Health, readiness and metrics

Route Answers
GET /healthz 200 {"status": "ok"} while the process serves requests
GET /readyz 200 when the store answers and every readiness=[...] check returns True, else 503 with the failing names
GET /metrics With OunceServer(metrics=True): calls, errors by category, truncations, result tokens and latency per tool, in Prometheus format

Probes send the Host header too, so include the name or address they use in allowed_hosts.

/healthz, /readyz and /metrics need no token, so that probes and scrapers can reach them. /metrics lists your tool names and call counts: expose these three paths only to your own network (a proxy rule or a network policy), not to the internet. Calls to names that are not tools are counted together as (unknown tool), so a caller cannot inflate the metrics.

Configuration file

Keep budgets, limits, discovery and security settings in ouncemcp.toml and build the server with OunceServer.from_config("tickets", "ouncemcp.toml"); keyword arguments override the file. See ouncemcp.core.config for every key.

Container

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir . redis
EXPOSE 8080
CMD ["python", "-c", "from server import server; server.run('http', host='0.0.0.0', port=8080, allowed_hosts=['mcp.example.com', 'localhost'])"]

Pass OUNCEMCP_CURSOR_KEYS and the Redis URL at run time from your secret store (for example docker run -e OUNCEMCP_CURSOR_KEYS=...), never in the image: anyone with the image could forge cursors and state tokens. Point the liveness probe at /healthz and the readiness probe at /readyz.