Skip to content
API referenceMCP server

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.

Endpointhttps://tablebuddy.radioworkflow.com/api/mcp

Connect

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.

bash or zsh
claude mcp add --transport http table-buddy https://tablebuddy.radioworkflow.com/api/mcp \
  --header "Authorization: Bearer $TABLEBUDDY_API_KEY"
PowerShell
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.

JSON
{
  "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
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.

Keep the key in an environment variable
A key is shown once and stored only as a hash. A leaked one is revoked and replaced, never recovered.

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.

Menu

Menu categories and items with their add-ons, and taking an item off sale.

Tables

The floor plan's tables and their status.

  • list-tablesList tables
    GET/api/v1/tables
    tables:readread-only
  • set-table-statusSet a table's status
    PATCH/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 orders
    GET/api/v1/orders
    orders:readread-only
  • get-orderGet an order
    GET/api/v1/orders/{order_id}
    orders:readread-only
  • create-orderCreate an order
    POST/api/v1/orders
    orders:writewrites
  • add-order-itemsAdd a round to an order
    POST/api/v1/orders/{order_id}/items
    orders:writewrites
  • send-orderSend an order to the kitchen
    POST/api/v1/orders/{order_id}/send
    orders:writewrites
  • cancel-orderCancel an unpaid order
    POST/api/v1/orders/{order_id}/cancel
    orders:canceldestructive

Stock

Raw materials, their stock cards and stock adjustments.

  • list-materialsList materials
    GET/api/v1/inventory/materials
    inventory:readread-only
  • get-materialGet a material
    GET/api/v1/inventory/materials/{material_id}
    inventory:readread-only
  • list-stock-movementsGet a stock card
    GET/api/v1/inventory/materials/{material_id}/movements
    inventory:readread-only
  • adjust-stockAdjust stock
    POST/api/v1/inventory/materials/{material_id}/adjustments
    inventory:writewrites

Reports

The reports, raw or as the page prints them.

  • list-reportsList reports
    GET/api/v1/reports
    reports:readread-only
  • run-reportRun a report
    GET/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 answers idempotency_key_in_use with retry_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.
tools/call · create-order
{
  "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

An annotation is a hint, not a gate.
cancel-order carries 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:

Marketing campaigns, test sends, audiences, consent and the never-email list
Mail to guests goes out under the restaurant's name, and CAN-SPAM makes the restaurant liable for every message. It needs the platform switch, a verified domain and Email guests, which no default role holds.
Deleting a restaurant, a sample, a guest, a supplier, an employee or a menu item
Deleting a record that holds history belongs to a person at a screen that says what goes with it. Nothing in the API deletes history.
Members, invitations, staff roles, access and API keys
They are security-sensitive, and grants are ranked. A key never makes a key.
Settings: taxes, payment methods, the business day, table ordering, sending domains
Each changes every future bill or figure.
Integrations: connecting, pausing, resuming, running, disconnecting, credentials, the Toast deposit helper
They change a live connection and handle credentials. A credential never travels through an API body.
Pay rates, salaries, pay rules, timesheet approval and the payroll file
They are Pay rates and payroll's alone, and approval fixes a pay period. Reads of pay need the payroll:read scope; writes stay in the console.
Formal notices (warnings and write-ups)
A notice is a personnel record, under the rank rule.
Ledger entries, transfers, categories, account edits, and undoing a settlement or a payout
The drawer rule, backdating and accounts another system keeps make each a console act for now.
Opening, counting and closing a cash drawer; cash in and out
They are physical acts at the register.
Uploading, editing, rejecting or splitting a supplier invoice; supplier credits
Upload has its own door and review is a screen.
Creating and editing menu items, recipes and preps, add-on groups and categories
Their engines take form-shaped input, and Toast owns the names and prices of linked items.
Creating and editing tables and reservations
Little value to another program; a table's status is in the API.
The accounting export and QuickBooks
The export is a download that marks days posted, and the QuickBooks sync is its own.
Anything an integration writes (imported checks, refunds, write-offs, outside money and staff)
Only an integration's own sync writes through them, under its status.
Changing a record another system keeps: a Toast check, a kept account or payment method, a linked item's name, price or place on the menu, a Toast punch or week
The record is the other system's truth. The endpoints that touch such records refuse in that system's own words.
Pay, labor cost and labor % to a key without payroll:read
They are Pay rates and payroll's alone, totals included: the fields are left out, never zeroed.
Webhooks or an event feed
Later.

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.

A failed call
{
  "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

tool resultresult_too_large
A read answered more than 256 KiB, the most one tool result may carry.

What to do: Ask for less: a smaller limit, a shorter span, a filter, or view=display for a report. Nothing was changed.

403origin_not_allowed
The POST carried an Origin 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.

The key does not carry the endpoint's scope.

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.

The key's creator has left the restaurant, was suspended, or was removed and invited back.

What to do: Make a new key from an active account.

The key's creator no longer holds any permission that could put this scope on a key.

What to do: Ask an owner to restore the permission, or make a new key from an account that holds it.

The key's permissions for this endpoint (its creator's, cut down to the endpoint's scope) do not include what this endpoint, or this argument, needs. The message names it.

What to do: Use a key with the named scope, from a creator who holds the named permission.

The arguments do not match the tool's input schema: a missing or unknown argument, or a value out of range. The message names the first four problems.

What to do: Fix the named arguments and call again. Nothing was done, and a write may keep its idempotency_key.

Over the key's 60 units a minute, or over 30 unknown keys a minute from one network (an address; an IPv6 caller's /64).

What to do: Wait retry_after seconds, then send the same call again (a write with the same idempotency_key).

Something failed on our side. Nothing kept the call's 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 API
1, or 5 for a heavy read (run-report).
tools/call refused before it runs
1: an unknown tool, a missing id in the path, or a key whose maker has lost access.
Every other message
1: initialize, 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).
Before the key is known
0: a foreign Origin, no key, or a bad key. An unknown key counts toward the limit on unknown keys instead.

Limits

1 MiB
One message, the API’s own body limit. A larger one is refused 413 payload_too_large.
256 KiB
One read’s answer. A larger one is refused result_too_large, never cut short: ask for less. A write is always answered whole.
4,000 characters
One tool’s description; the reference page has the rest.

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 GET and DELETE answer 405. No Mcp-Session-Id is issued or expected.
  • Send no Origin header. A web page’s is refused 403 origin_not_allowed; call from a server, never from a browser.
  • Accept must list both application/json and text/event-stream, or the request is refused 406, though this server always answers JSON. Content-Type: application/json, or 415.
  • 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-Version on every message after initialize; 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.
Listing the tools with cURL
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.