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.