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
| Protocol | Model Context Protocol (MCP) over streamable HTTP. Messages are JSON-RPC 2.0. |
| Sign-in | None. 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. |
| Headers | Content-Type: application/json, and Accept: application/json, text/event-stream. The server refuses a request that does not accept both, with 406. |
| Answers | One server-sent event named message, whose data line is the JSON-RPC response. |
| Sessions | None. 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 name | kept |
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 ReadsThe 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 ReadsThe 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.
| Takes | Kind | What 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 ReadsThe 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.
| Takes | Kind | What 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 ReadsEverything 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.
| Takes | Kind | What it is |
|---|---|---|
id needed |
integer | The wine's id, as given by find_wines or drink_next. |
rack_contents
What is in a rack ReadsWhat 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.
| Takes | Kind | What 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 ReadsThe 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.
| Takes | Kind | What it is |
|---|---|---|
limit |
integer, default 50 | The most bottles to return, up to 200. The default is 50. |
cellar_report
The cellar added up ReadsWhat 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.
| Takes | Kind | What 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 ReadsThe 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.
| Takes | Kind | What 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 ReadsWhere 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.
| Takes | Kind | What 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 itRecords 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.
| Takes | Kind | What 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 cellarSaves what the owner said about a bottle that has been drunk. It replaces any note the bottle had.
| Takes | Kind | What 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 cellarAdds 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.
| Takes | Kind | What 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 happened | What you get |
|---|---|
| The secret opens no cellar | HTTP 404. |
A GET or DELETE | HTTP 405. The server has no stream to listen to and no session to end. |
| The request does not accept both kinds of answer | HTTP 406. |
| Too many calls | HTTP 429. |
| A tool was given something it cannot use | HTTP 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 reads | HTTP 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.
| Limit | How many |
|---|---|
| Calls on one link | 1,000 in five minutes |
| Bottles recorded as drunk | 100 a day in one cellar |
| Bottles added | 300 a day in one cellar, and 12 in one call |
| Notes on drunk bottles | 300 a day in one cellar |
| Wines in one answer | 200 |