MCP server
Table Buddy speaks the Model Context Protocol over streamable HTTP, so Claude and other MCP clients can work with a restaurant through this API: read the menu, orders and stock, run reports, take orders. Every tool is one of the endpoints in this reference. There is no second surface, and nothing here can do what the API cannot.
https:/ / tablebuddy.radioworkflow.com/ api/ mcpConnect
Use a key made under API Keys, the same key the REST API takes, sent as Authorization: Bearer <key> (x-api-key also works; Authorization wins when both are sent). There is no OAuth and no separate MCP credential. A key belongs to one restaurant and acts as the person who made it, cut down to its scopes.
Claude Code
One command adds the server as table-buddy, reading the key from TABLEBUDDY_API_KEY. Use the line for your shell: in PowerShell the variable is $env:TABLEBUDDY_API_KEY.
claude mcp add --transport http table-buddy https://tablebuddy.radioworkflow.com/api/mcp \ --header "Authorization: Bearer $TABLEBUDDY_API_KEY"
claude mcp add --transport http table-buddy https://tablebuddy.radioworkflow.com/api/mcp ` --header "Authorization: Bearer $env:TABLEBUDDY_API_KEY"
Claude Code keeps the header it is given, key included, in its own settings on your machine. Revoke the key under API Keys if that file is ever shared.
A configuration file
Or describe the server in a file, such as a project’s .mcp.json. Claude Code reads ${TABLEBUDDY_API_KEY} from the environment each time it connects, so the file holds no key and can be committed. If the variable is not set, Claude Code warns and sends the text as it is, which the server refuses 401 invalid_api_key. For a client that does not read the environment, put the key in its local settings, never in a file you commit.
{
"mcpServers": {
"table-buddy": {
"type": "http",
"url": "https://tablebuddy.radioworkflow.com/api/mcp",
"headers": {
"Authorization": "Bearer ${TABLEBUDDY_API_KEY}"
}
}
}
}The Claude API
From your own code, the Claude API’s MCP connector calls Table Buddy from Anthropic’s servers with the key you give it as authorization_token. The server and the mcp_toolset that names it go together.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20,server-side-fallback-2026-07-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"fallbacks": "default",
"mcp_servers": [{ "type": "url", "name": "table-buddy", "url": "https://tablebuddy.radioworkflow.com/api/mcp", "authorization_token": "'"$TABLEBUDDY_API_KEY"'" }],
"tools": [{ "type": "mcp_toolset", "mcp_server_name": "table-buddy" }],
"messages": [{ "role": "user", "content": "What did we take on card yesterday?" }]
}'Claude’s desktop, web and mobile apps
They add a remote server as a custom connector that signs in with OAuth, which Table Buddy does not offer yet. Some organizations can instead give a connector a fixed request header; there an organization Owner enters one key, and every member of that Claude organization acts with it, as the person who made the key. For now, connect through Claude Code or the Claude API.
The key is the gate
tools/list shows only the tools this key may call now: its scopes, and what the person who made it may do in Table Buddy today. A call to any other tool is refused with insufficient_scope or permission_required, by the same checks a REST request meets. For an assistant that only answers questions, make a key with only the read scopes those questions need, and give a second key the write scopes it needs. Scopes are fixed when a key is made. See Authentication and scopes.
A new key starts with these read scopes ticked. They write nothing, but a read can still carry people’s details, so untick what an assistant does not need:
- menu:readRead the menu
- tables:readRead tables
- inventory:readRead stock and costs
- reports:readRead reports
reports:read reads every report as the console shows it, people included: staff names, the tips each person is owed, each cashier’s drawer and what it counted over or short, who gave each discount, and every ledger entry as it was typed, so a salary booked under a person’s name shows with its amount. The Labor report needs payroll:read as well.
Tools (20)
Each tool is named for its endpoint, whose page has its arguments, answer, refusals and samples: cancel-order is documented at /docs/cancel-order. A host shows it as mcp__table-buddy__<name>. Input and output schemas come from the same catalog as the OpenAPI document. Output schemas are exact, not widened; a field that needs a permission the key lacks is left out, never zeroed.
Each row shows the hints a client is sent: read-only changes nothing, destructive moves money, cannot be undone or is a change a person should approve, emails reaches people outside the restaurant, idempotent is an edit that lands on the same state when repeated, and writes is any other change. A description is at most 4,000 characters.
Restaurant
The restaurant a key belongs to, and the key itself.
- get-restaurantGet the restaurantGET
/api/ v1/ restaurant any keyread-only - get-current-keyGet the current keyGET
/api/ v1/ key any keyread-only
Menu
Menu categories and items with their add-ons, and taking an item off sale.
- list-menu-categoriesList menu categoriesGET
/api/ v1/ menu/ categories menu:readread-only - list-menu-itemsList menu itemsGET
/api/ v1/ menu/ items menu:readread-only - get-menu-itemGet a menu itemGET
/api/ v1/ menu/ items/ {item_id} menu:readread-only - set-menu-item-availabilityMark an item sold out or back on salePATCH
/api/ v1/ menu/ items/ {item_id}/ availability menu:writeidempotent
Tables
The floor plan's tables and their status.
- list-tablesList tablesGET
/api/ v1/ tables tables:readread-only - set-table-statusSet a table's statusPATCH
/api/ v1/ tables/ {table_id}/ status tables:writeidempotent
Orders
Orders from the POS, this API and outside systems: reading them, opening them, adding rounds, sending them to the kitchen and cancelling.
- list-ordersList ordersGET
/api/ v1/ orders orders:readread-only - get-orderGet an orderGET
/api/ v1/ orders/ {order_id} orders:readread-only - create-orderCreate an orderPOST
/api/ v1/ orders orders:writewrites - add-order-itemsAdd a round to an orderPOST
/api/ v1/ orders/ {order_id}/ items orders:writewrites - send-orderSend an order to the kitchenPOST
/api/ v1/ orders/ {order_id}/ send orders:writewrites - cancel-orderCancel an unpaid orderPOST
/api/ v1/ orders/ {order_id}/ cancel orders:canceldestructive
Stock
Raw materials, their stock cards and stock adjustments.
- list-materialsList materialsGET
/api/ v1/ inventory/ materials inventory:readread-only - get-materialGet a materialGET
/api/ v1/ inventory/ materials/ {material_id} inventory:readread-only - list-stock-movementsGet a stock cardGET
/api/ v1/ inventory/ materials/ {material_id}/ movements inventory:readread-only - adjust-stockAdjust stockPOST
/api/ v1/ inventory/ materials/ {material_id}/ adjustments inventory:writewrites
Reports
The reports, raw or as the page prints them.
- list-reportsList reportsGET
/api/ v1/ reports reports:readread-only - run-reportRun a reportGET
/api/ v1/ reports/ {report_id} reports:readread-only
Retries and idempotency_key
- Every write sent as POST requires
idempotency_key, cancel-order and send-order included: a fresh UUID for each new operation. A PATCH takes one if you send it; a read takes none. - Send the same value only to retry that same call with the same arguments. The retry returns the first answer, marked
com.tablebuddy/replayed, and nothing runs twice. - The same value with other arguments is refused
idempotency_key_reused. While the first call is still running, a second answersidempotency_key_in_usewithretry_after. - A value is kept 24 hours for each API key, and REST and MCP share it: a request made with cURL and retried from Claude Code with the same body is the same operation.
- A refusal that is final (
not_found,refused) is kept too. A call refused for a bad argument frees the value, so fix the argument and send it again.
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "create-order",
"arguments": {
"type": "COUNTER",
"lines": [
{
"menu_item_id": "MENU_ITEM_ID",
"quantity": 1,
"addon_ids": []
}
],
"send": true,
"idempotency_key": "6f1c0e5a-93b2-4c1d-8e7f-2a4b5c6d7e8f"
}
}
}The server holds no session, so notifications/cancelled cancels nothing: a cancelled call may still complete. Send the same call with the same idempotency_key to learn how it ended. See Idempotency.
What MCP cannot do about consequential calls
destructiveHint: true, the strongest signal the protocol has. A host is free to ignore it, and the MCP specification tells clients not to trust annotations from a server they do not know.Table Buddy treats each of these as a change a person should approve first. Over MCP nothing asks: there is a key, not a signed-in person, and this server cannot make your client ask you. The real boundary is the scopes you made the key with: a key made without orders:cancel cannot cancel an unpaid order from any client. Use a host that asks before a destructive tool.
Records another system keeps
A record another system keeps, such as a Toast check, is refused (code refused) in the words the restaurant’s staff see. Change it in that system; the next sync brings it here. Retrying the call will not help. The refusals that can come from such a record:
The order is a check another system recorded, such as a Toast check.
This order comes from {provider} and is changed only by its sync.
Fix: Ring it up on that check in Toast; the next sync brings it here. An order made here would be a second bill.
The order is a check another system recorded, such as a Toast check.
This order comes from {provider} and is changed only by its sync.
Fix: Nothing to send: that check was made and served in Toast. Retrying will not help.
It is a check another system recorded, such as a Toast check.
This order comes from {provider} and is changed only by its sync.
Fix: Void it in Toast; the next sync brings that here. Retrying will not help.
Not in the API
Every endpoint in this reference is a tool. What the API leaves out on purpose, MCP leaves out too:
Errors, results and costs
A successful call’s structuredContent is the API’s answer, and its text is the API’s exact bytes. A failed call is a tool result with isError: true and no structuredContent. Its _meta["com.tablebuddy/error"] holds code, message, http_status, fix, docs and, when waiting helps, retry_after in seconds. Branch on code, never on the sentence. Every result carries _meta["com.tablebuddy/request-id"], the row in the restaurant’s request log: quote it when asking for help.
{
"isError": true,
"content": [
{
"type": "text",
"text": "An inactive or sold-out prepared item cannot be put on sale.\n\nPut the item back on the menu, or log the portions made, in Table Buddy first.\n\nReference: https://tablebuddy.radioworkflow.com/docs/set-menu-item-availability"
}
],
"_meta": {
"com.tablebuddy/request-id": "7c1e9a40-5d2b-4f6e-8a31-0b9c2d4e6f80",
"com.tablebuddy/rate-limit-remaining": 56,
"com.tablebuddy/error": {
"code": "refused",
"message": "An inactive or sold-out prepared item cannot be put on sale.",
"http_status": 409,
"fix": "Put the item back on the menu, or log the portions made, in Table Buddy first.",
"docs": "https://tablebuddy.radioworkflow.com/docs/set-menu-item-availability"
}
}
}Codes only MCP answers
result_too_largeWhat to do: Ask for less: a smaller limit, a shorter span, a filter, or view=display for a report. Nothing was changed.
origin_not_allowedOrigin header other than this site's: a web page, not an MCP client.What to do: Connect from an MCP client, or from a server; a browser page may not call this server.
Failures every tool may answer
A tool’s description lists its own failures; these apply to every tool, so they are listed here once. The rest of the codes are the API’s.
What to do: This key was made without the <scope> scope. Scopes are fixed when a key is made: make a new key with it under API Keys and point this connection at it. Retrying will not help.
What to do: Make a new key from an active account.
What to do: Ask an owner to restore the permission, or make a new key from an account that holds it.
What to do: Use a key with the named scope, from a creator who holds the named permission.
What to do: Fix the named arguments and call again. Nothing was done, and a write may keep its idempotency_key.
What to do: Wait retry_after seconds, then send the same call again (a write with the same idempotency_key).
What to do: Send the same call again (a write with the same idempotency_key: nothing kept it). If it keeps failing, quote this result's request-id when asking for help.
What a message costs
MCP and the REST API share the key’s 60 units a minute. A tool call costs exactly what its REST request costs, charged once, and every other message costs 1, so starting a connection costs 3. See Rate limits.
tools/call that reaches the APItools/call refused before it runsinitialize, tools/list, ping, a notification, and a message the server refuses (a batch, one over 1 MiB, one cut short, one that is not JSON-RPC).Origin, no key, or a bad key. An unknown key counts toward the limit on unknown keys instead.Limits
413 payload_too_large.result_too_large, never cut short: ask for less. A write is always answered whole.Writing a client by hand
The official SDKs handle all of this. If you speak the protocol yourself:
- POST only. The server is stateless and offers no stream, so
GETandDELETEanswer405. NoMcp-Session-Idis issued or expected. - Send no
Originheader. A web page’s is refused403 origin_not_allowed; call from a server, never from a browser. Acceptmust list bothapplication/jsonandtext/event-stream, or the request is refused406, though this server always answers JSON.Content-Type: application/json, or415.- One message per POST, at most 1 MiB. A JSON-RPC batch is refused
422 invalid_request: MCP removed batching in protocol revision 2025-06-18. - Send
MCP-Protocol-Versionon every message afterinitialize; without it a message is read as 2025-03-26. The server speaks 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07, and answers 2025-11-25 to a client that asks for any other.
curl -sS https://tablebuddy.radioworkflow.com/api/mcp \
-H "Authorization: Bearer $TABLEBUDDY_API_KEY" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2025-11-25" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Privacy
What an assistant reads, it sends to its own model provider under your arrangement with them. Table Buddy sends it nowhere else. The request log keeps each call’s method and tool, never what went in or came back. See the privacy notice.