Start my cellar

Kept guides · Using Kept

For developers

Kept's API is its MCP server: one address for each cellar, which an assistant or your own code calls with JSON-RPC. The tables on this page list every tool the server offers.

The endpoint

POST https://kept.wine/mcp/YOUR-SECRET
ProtocolModel Context Protocol (MCP) over streamable HTTP. Messages are JSON-RPC 2.0.
Sign-inNone. The secret at the end of the address is the key, and it opens one cellar. Make it on the Use Kept in ChatGPT or Claude page in Kept, and keep it as you would a password.
HeadersContent-Type: application/json, and Accept: application/json, text/event-stream. The server refuses a request that does not accept both, with 406.
AnswersOne server-sent event named message, whose data line is the JSON-RPC response.
SessionsNone. Each call stands alone, so you can call a tool without the initialize handshake. Each call reads the cellar as it stands at that moment.
Server namekept

Connect a client

To connect Claude or ChatGPT through their own menus, follow Use Kept in ChatGPT or Claude. For a client that takes an address, give it the link and choose no sign-in.

In Claude Code, add the cellar from a terminal:

claude mcp add --transport http kept https://kept.wine/mcp/YOUR-SECRET

Or put it in a project's .mcp.json:

{
  "mcpServers": {
    "kept": { "type": "http", "url": "https://kept.wine/mcp/YOUR-SECRET" }
  }
}

The link is a secret. Do not commit a file that holds it to a shared repository.

Call it from your own code

Any HTTP client can call a tool. To list the tools a link has:

curl https://kept.wine/mcp/YOUR-SECRET \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

To call one, send tools/call with the tool's name and what it takes. This asks for two reds to open next:

curl https://kept.wine/mcp/YOUR-SECRET \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {"name": "drink_next",
                  "arguments": {"type": "red", "limit": 2}}}'

What comes back

The response is one event. Its data line holds the JSON-RPC result. The tool's answer is in result.content[0].text, as JSON in a string:

event: message
data: {"result": {"content": [{"type": "text", "text": "{\"year\": 2026, …}"}]}, "id": 2, "jsonrpc": "2.0"}

Parsed, the text of that answer looks like this:

drink_next

{
  "year": 2026,
  "winesToOpen": 93,
  "notShown": 91,
  "winesLeftOutBecauseTheyShouldBeKept": 18,
  "wines": [
    {
      "id": 3,
      "wine": "Castello Varenza Riserva 2016",
      "type": "Red",
      "grape": "Sangiovese",
      "region": "Tuscany",
      "country": "Italy",
      "abvPercent": 14,
      "bottles": 12,
      "lastAddedOn": "2026-05-06",
      "bottlesAddedThatDay": 12,
      "costPerBottleUsd": 62,
      "drinkFrom": 2022,
      "drinkBy": 2027,
      "stage": "drink_soon",
      "advice": "Drink by 2027",
      "where": [
        "North wall · E4",
        "North wall · A5",
        "North wall · B5"
      ]
    },
    {
      "id": 92,
      "wine": "Stonewake Zinfandel 2018",
      "type": "Red",
      "grape": "Zinfandel",
      "region": "Sonoma County",
      "country": "United States",
      "abvPercent": 15,
      "bottles": 4,
      "lastAddedOn": "2026-05-06",
      "bottlesAddedThatDay": 4,
      "costPerBottleUsd": 38,
      "drinkFrom": 2020,
      "drinkBy": 2027,
      "stage": "drink_soon",
      "advice": "Drink by 2027",
      "where": [
        "North wall · Q7",
        "North wall · R7",
        "North wall · S7"
      ]
    }
  ]
}

The server leaves out a field that has nothing to say. Costs are estimates, in US dollars. Here each list of spots is cut to its first three.

Tools that read

Every link has these 9 tools. None of them changes anything.

cellar_overview

Cellar overview Reads

The whole cellar summed up: how many bottles and wines there are, and how many spirits and beers when there are any, what they would cost to buy again, how they divide by type and by drinking stage, and each rack with its temperature and how full it is.

It takes nothing.

find_wines

Find wines Reads

The wines in the cellar, and any spirits and beers: all of them, or the ones that match. Each comes with how many bottles there are, what a bottle costs, its drinking window and stage, and where the bottles are. Its ids are the ones wine_details takes.

TakesKindWhat it is
search string Words to look for in the producer, the wine's name, the grape or style, the region or the country. A year finds that vintage. Leave out to list everything.
type string Only this type: red, white, rosé, sparkling, dessert, fortified or orange for a wine, or spirit, or beer, or mixer for tonic, soda, bitters, water and soft drinks.
stage string Only wines at this stage of their drinking window: keep, ready, drink_soon or past_best.
rack string Only wines with a bottle in the rack of this name.
sortBy string The order to list them in: name, value, bottles, newest, oldest, drink_by or added. Added puts what went in most recently first, by the day and then by the order they were entered. Newest and oldest are vintages. The default is name.
limit integer, default 50 The most wines to return, up to 200. The default is 50.

drink_next

What to drink next Reads

The wines to open next, the most pressing first: those past their best, then those to drink this year or next, then those that are ready. A beer counts by the day it is best by. Wines still to be kept are left out, and so are spirits, unless the type asked for is spirit. A wine with headsUp is the last bottle of a year that belongs to a vertical of the same wine.

TakesKindWhat it is
type string Only this type: red, white, rosé, sparkling, dessert, fortified or orange for a wine, or spirit, or beer, or mixer for tonic, soda, bitters, water and soft drinks.
limit integer, default 40 The most wines to return, up to 200. The default is 40.

wine_details

One wine in detail Reads

Everything recorded about one wine, spirit or beer: its details, the owner's notes, where each bottle in the cellar is, and the bottles of it that have been drunk, with what was said about them. Each bottle of a beer has the dates known for it, and each opened bottle of a spirit has how much is left.

TakesKindWhat it is
id
needed
integer The wine's id, as given by find_wines or drink_next.

rack_contents

What is in a rack Reads

What is in one rack, spot by spot, with the rack's temperature and how many spots are free. With no name, the list of racks.

TakesKindWhat it is
rack string The rack's name, or part of it, such as "Fridge 2". Leave out to list the racks.

drinking_history

What has been drunk Reads

The bottles that have been drunk, the latest first, each with the day, the owner's rating out of five when they gave one, and what they said about it. Counts over time are bottles_over_time's.

TakesKindWhat it is
limit integer, default 50 The most bottles to return, up to 200. The default is 50.

cellar_report

The cellar added up Reads

What is in the cellar now, added up one way: by type, producer, grape, style, country, region, rack, vintage, the year to drink by, or drinking stage. Grape groups the wines, and style the spirits and beers. Each group comes with its bottles and what they would cost to buy again.

TakesKindWhat it is
groupBy string What to group by: type, producer, grape, style, country, region, rack, vintage, drink_by or stage. The default is type.

bottles_over_time

Bottles drunk or added over time Reads

The bottles drunk, or the bottles added, in each month, quarter or year, with what they would cost to buy again, divided if asked by type, producer, grape or style, country or region. A bottle of spirits counts as drunk on the day it was finished.

TakesKindWhat it is
what string Which bottles to count: drunk or added. The default is drunk.
period string The length of each period: month, quarter or year. The default is month.
groupBy string Divide each period's count by this: type, producer, grape, country or region. Leave out for the count alone.
from string The first day to count, as YYYY-MM-DD. Leave out to start from the earliest bottle.
to string The last day to count, as YYYY-MM-DD. Leave out to count up to today.

where_to_put

Where new bottles should go Reads

Where Kept would put bottles that are about to be added, with its reasons: a spot at a temperature that suits the wine, beside bottles of the same wine when there are any. Beer goes in the cold, and a spirit on a rack, out of the fridges. It suggests, and changes nothing. The rack and spot chosen are what add_bottles takes.

TakesKindWhat it is
type string The type: red, white, rosé, sparkling, dessert, fortified or orange for a wine, or spirit, or beer, or mixer for tonic, soda, bitters, water and soft drinks.
drinkFrom integer The first year the wine should be at its best, if known.
drinkBy integer The last year the wine should be at its best, if known.
costPerBottleUsd number About what a standard 750 ml bottle costs, in US dollars, if known: half a magnum's price.
bottles integer, default 1 How many bottles, from 1 to 12. The default is 1.
sizeMl integer The size of each bottle in milliliters. The default is 750, or 355 for a beer.
wineId integer The id of the wine, if it is already in the cellar, so that the new bottles go beside it.

Tools that change

A link has these 3 tools only when its cellar has allowed changes, on the Use Kept in ChatGPT or Claude page. A link that only reads is not shown them, and the server refuses it if it calls one anyway.

No tool deletes or moves a bottle, changes a wine's details, sets the date on a beer or the level of a spirit, or adds, changes or removes a rack.

record_bottle_drunk

Record a bottle as drunk Changes the cellar An assistant cannot undo it

Records one bottle as drunk: it leaves the cellar, its spot is freed, and it joins the drinking history. One call is one bottle. For a spirit, drunk means the bottle is finished. Only the owner can put a bottle back, on the wine's page in Kept. A note on how it was is note_on_drunk_bottle's.

TakesKindWhat it is
wineId
needed
integer The wine's id, as given by find_wines, drink_next or wine_details.
where string Where the bottle was taken from, as wine_details gives it, such as "Fridge 1 · Shelf 7". Needed only when the wine has bottles in more than one place. Ask the owner; do not guess.
note string What the owner said about the wine, if they have already said.
drunkOn string The day it was drunk, as YYYY-MM-DD, if that was not today.

note_on_drunk_bottle

Note how a bottle was Changes the cellar

Saves what the owner said about a bottle that has been drunk. It replaces any note the bottle had.

TakesKindWhat it is
bottleId
needed
integer The bottle's id, as given by record_bottle_drunk, drinking_history or wine_details.
note
needed
string What the owner said about it, up to 1,000 characters.

add_bottles

Add bottles of a wine Changes the cellar

Adds bottles of one wine, spirit or beer to the cellar, up to a case at a time, all going to one place. A wine already in the cellar, found with find_wines, is joined when the new bottles are spelled the same way. Only the owner can take bottles out again, in Kept.

TakesKindWhat it is
producer
needed
string Who made the wine, as on the label.
name string The wine's own name, if it has one beyond the producer's, such as "Monte Bello".
vintage integer The vintage year. Leave out for a wine with no vintage, and for a spirit or a beer unless it has a year on it.
type string The type: red, white, rosé, sparkling, dessert, fortified or orange for a wine, or spirit, or beer, or mixer for tonic, soda, bitters, water and soft drinks.
grape string The grape or blend of a wine, such as "Pinot Noir" or "Champagne Blend". For a spirit or a beer, its style, such as "Bourbon" or "IPA".
region string The region or appellation.
country string The country.
abvPercent number The alcohol by volume, as a number of percent such as 13.5. Use the figure on the label when the owner reads it to you. Otherwise give the strength you know that bottling to have, or the usual strength of its kind, and tell the owner it is an estimate.
abvIsFromTheLabel boolean, default false True only when the owner read abvPercent to you from the label. Left out or false, Kept records it as an estimate and shows it as "about".
costPerBottleUsd number About what a standard 750 ml bottle of it costs to buy today, in US dollars. For a beer, what one can or bottle of it costs. Give your own estimate if the owner does not know, and tell them it is an estimate.
drinkFrom integer The first year the wine should be at its best. Give your own estimate if the owner does not know. Leave out for a spirit, and for a beer unless it is one made to be kept.
drinkBy integer The last year the wine should be at its best. Give your own estimate if the owner does not know. Leave out for a spirit, and for a beer unless it is one made to be kept.
bottles integer, default 1 How many bottles, from 1 to 12. The default is 1.
sizeMl integer The size of each bottle in milliliters: 187, 355, 375, 473, 500, 700, 750, 1000, 1500, 1750, 3000 or 6000. The default is 750, or 355 for a beer.
rack string The name of the rack they are going into, such as "Fridge 2". Ask the owner, or offer what where_to_put suggests. Leave out only if they are not going into a rack yet.
place string The place in that rack, written the way the rack names its places: "Shelf 4", "C4", "A top", or "Bottom" for the space under a fridge's shelves.
notes string Anything the owner wants noted about the wine.

Errors

What happenedWhat you get
The secret opens no cellarHTTP 404.
A GET or DELETEHTTP 405. The server has no stream to listen to and no session to end.
The request does not accept both kinds of answerHTTP 406.
Too many callsHTTP 429.
A tool was given something it cannot useHTTP 200, and a result with "isError": true whose text says what was wrong, such as “No wine in this cellar has the id 999. Use find_wines to get the ids.”
A tool that changes, called on a link that only readsHTTP 200, and a JSON-RPC error with the code -32600.

Limits

The limits are far above what a person does by hand. They are there for the day a link gets out, or an assistant will not stop.

LimitHow many
Calls on one link1,000 in five minutes
Bottles recorded as drunk100 a day in one cellar
Bottles added300 a day in one cellar, and 12 in one call
Notes on drunk bottles300 a day in one cellar
Wines in one answer200