13. Deploying¶
So far Shelf has run locally. This chapter runs it over HTTP for many users, on more than one replica.
HTTP¶
server.run("http", host="0.0.0.0", port=8080,
allowed_hosts=["shelf.example.com"], allowed_origins=["https://app.example.com"])
Binding a public address without allowed_hosts is an error: Host and Origin checks stop DNS rebinding attacks from a browser on the user's machine. Behind a reverse proxy that already checks them, pass host_origin_protection=False. For an ASGI server such as uvicorn, use server.http_app().
Add authentication as in chapter 7 (auth= and audience=); over HTTP, a server without it is open to anyone who can reach it.
More than one replica¶
Everything that must survive a restart or be seen by another replica lives in the store: idempotency records (chapter 6), approval receipts, handles and jobs (chapter 8). The default MemoryStore is for one process. Share Redis:
import redis.asyncio as redis
from ouncemcp import OunceServer, RedisStore
server = OunceServer("shelf", store=RedisStore(redis.Redis.from_url(REDIS_URL)), handles=True)
and set the same signing keys everywhere, newest first, so a cursor issued by one replica works on another:
To rotate, add the new key at the front, deploy, and remove the old one once its cursors have expired.
Health and metrics¶
| Route | Answers |
|---|---|
GET /healthz |
200 while the process serves requests |
GET /readyz |
200 when the store answers and every readiness=[...] check passes, else 503 |
GET /metrics |
With metrics=True: calls, errors by category, truncations, result tokens and latency per tool, for Prometheus |
Probes send a Host header too, so include the name they use in allowed_hosts.
Configuration in a file¶
Keep budgets, limits, discovery and security settings out of code:
Keyword arguments override the file.
A checklist¶
-
auth=andaudience=set;allowed_hostslists the public name and the probe names. - A shared store and the same
OUNCEMCP_CURSOR_KEYSon every replica. -
ouncemcp checkand the task suite pass in CI. - Traces or metrics go somewhere you look.
- Every write has
idempotency=True; every destructive tool has a policy and an approval.
The deployment guide has the details.