Connect Claude or ChatGPT to Your Wine Cellar: Cellarion's AI Connector (Beta)

Your cellar can talk now

Since the beginning, Cellarion has been the place you record your cellar. As of this week it's also a place your AI can work with. Connect Claude or ChatGPT to your account and you can simply ask: "What should I open tonight with grilled lamb?" — and the answer comes from your bottles, your drink windows, your ratings. Not generic wine advice; your actual cellar.

A few things people have already used it for:

• "We drank the 2016 Barolo last night — log it, four stars, note that it needed an hour in the decanter."
• "Which of my whites are past their peak? Anything I should drink this month?"
• "Reorganise rack two by drink window, ready-to-drink at the top."
• "I'm at the wine shop. Where are the gaps in my cellar?"
• "Add the case of Rioja I just bought — twelve bottles, €14 each."

The AI does the tedious part — finding the bottle, matching it against the shared wine registry, updating the rack — and you stay in charge of the decisions.

Connecting takes about two minutes

In Cellarion, go to Settings → Connect your AI. You'll find ready-made instructions for each client, but the short version:

• claude.ai — add a custom connector pointing at https://cellarion.app/api/mcp. Claude sends you to a Cellarion consent screen; you approve, and that's it.
• ChatGPT — add Cellarion as a connector in developer mode, same address, same consent screen.
• Claude Desktop, Cursor and friends — run npx cellarion-mcp with a personal API token from Settings. One line of config; the setup page writes it for you.

Built to be trusted before it's built to be clever

Letting software — any software — edit your cellar should make you pause. So the guardrails came first:

• Everything is reversible. Every change an AI makes lands in a ledger, and "undo that" works — as does a one-click Revert next to each entry in Settings → What your AI has changed.
• You choose how much to allow. Connect read-only if you'd rather the AI could look but not touch. Full access can consume and edit, but destructive things stay behind confirmations.
• Revoking is instant. Delete the connection in Settings and the AI is out, mid-sentence if need be.
• It's honestly labelled. This is a beta. It works — it's been through three full audits — but it's new, and the label says so everywhere it matters.

And like everything in Cellarion: it's free. No AI tier, no paywall. If Cellarion earns a place in your cellar, supporting the running costs is welcome — but every feature is for everyone.

For the technically curious: how it actually works

You can stop here and go pour a glass. What follows is the part where we nerd out.

The connector speaks MCP (Model Context Protocol) — the open standard Claude, ChatGPT and a growing list of clients use to talk to tools. Cellarion's implementation is not a sidecar service: the MCP server runs in-process in the same Express backend as the REST API, mounted at /api/mcp as a Streamable HTTP endpoint, with an SSE stream per session for push updates. Around 58 tools, filtered per connection: a read-only token literally never sees the write tools — they're unregistered for that session, not hidden.

There's also an anonymous endpoint, /api/mcp/public, exposing the shared wine registry, drink-window logic and guides to any AI without an account — the registry as a public good. And for stdio clients, npx cellarion-mcp is a thin bridge published on npm that forwards to either cellarion.app or your own server.

Identity: a real OAuth server, not an API-key form

Remote connectors authenticate against an OAuth 2.1 authorization server built into Cellarion: PKCE, dynamic client registration, discovery via RFC 9728 (WWW-Authenticate pointing at the protected-resource metadata — the header that lets claude.ai find the sign-in flow on its own), rotating refresh tokens with reuse detection. Prefer hand-minted credentials? Personal tokens carry explicit scopes — read, consume, write — and the write scope exists for the AI: it grants the MCP endpoint and nothing else on the REST surface.

Writes are where the engineering went

Reads are easy — paginated, lean, no surprises. Writes are where an agent can hurt you, so they run through layers:

• Registry-safe adds. An AI can't invent duplicate wines: adding goes resolve-first through the same fuzzy-matching chokepoint as the app (with sibling matching an AI can't skip), and every wine an AI does create is stamped and auditable as a class.
• Claim-first idempotency. Retried tool calls are the classic agent failure mode. Each write can carry an idempotency_key; the server atomically claims it in a ledger row under a unique partial index keyed per user and per tool, so a retry returns the original result instead of running twice — and a concurrent twin gets a distinct busy code, so a client can't accidentally defeat the guard by rotating keys.
• Invariants in the database, not just the code. "One bottle, one slot" is enforced by a unique multikey index across racks — even two perfectly interleaved requests can't place the same bottle twice. Optimistic concurrency turns racing writers into clean conflicts.
• A typed error taxonomy (invalid_input, conflict, busy, rate_limited, unavailable, …) so an agent knows the difference between "don't retry", "retry with the same key" and "the vector index is rebuilding, come back later".
• One reversal engine. Undo-via-AI and the Revert button in Settings run the exact same code path over the same ledger, prev-snapshots included — so they can never disagree about what "undo" means.

Fairness, cost and the shared-IP problem

A detail we're fond of: hosted AI connectors call from a small pool of egress IPs, so classic per-IP rate limiting would put every claude.ai user in one bucket — one chatty agent could starve everyone. The MCP endpoint is therefore limited per authenticated user (across all their tokens and IPs), with a separate high per-IP guard that only exists to stop unauthenticated flooding. Inside the protocol there are further budgets: a per-request tool-call cap, a per-user mutation budget shared with the web's write limits, and a daily AI budget for the one tool that actually spends money (semantic search embeds a query once; similarity search reuses stored vectors and costs nothing).

Run it yourself, if you like

Cellarion is AGPL and the whole MCP surface self-hosts: the OAuth issuer and every public link derive from your FRONTEND_URL, discovery endpoints are proxied in the shipped nginx config, and the same npx bridge points anywhere. The hosted app at cellarion.app is the easy path — but it's your cellar, and the exit has always been open.

It's a beta, and we mean the label: expect rough edges, tell us about them, and everything the AI changes can be unwound while you do. Connect your AI in Settings → Connect your AI, and let us know what you asked it first.