Skip to navigation

Connect an AI assistant (MCP)

Use Tillcast from an AI assistant that speaks MCP, with an API key: the address, the setup for each client, which key to give it and what to watch.

View as Markdown
A key prints on real paper

The MCP server acts with your API key on your live account. A tool that prints, prints on a real printer, and every key is live. Give an assistant a key made for it with only the scopes it needs, keep the key in an environment variable, and let a person approve every call that prints.

Tillcast runs an MCP server, the Model Context Protocol, at https://api.tillcast.com/mcp. An assistant that connects to it gets tools for your customers, locations, printers and jobs, and one tool that shows a receipt without printing it. The tools call the same API as the REST API, with the same key. Tillcast runs no model: your assistant does.

This is not the docs search server at https://docs.tillcast.com/_mcp/server. That one is Fern’s. It answers from these docs only and cannot call the Tillcast API.

Addresshttps://api.tillcast.com/mcp
Sign-inYour API key as a bearer token: the header Authorization: Bearer <your key>
TransportMCP over HTTP, JSON only: each POST carries one message and gets one JSON answer. There is no event stream and no session
Protocol revisions2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26

Which key to give

Make the key in the dashboard, under API keys (see Authentication and API keys). The server shows a key only the tools its scopes allow, so the key is also the list of what the assistant can do.

You want the assistant toGive itIt sees
Look around and draw receipts. Nothing printsThe Read only preset10 tools
Print receipts and test pages for one customerThe Printing preset, limited to that customer9 tools, among them create_job and test_print
Set customers, locations and printers up, onceThe Installer preset, for that session only23 tools to read, create, change and delete them. None queues a job, but create_printer can print a welcome receipt when the printer first connects

Start with Read only. It can already list your customers and printers and draw a receipt with preview_document. A key can never create or change keys, and it cannot grant more than it has. A key does not gain scopes later: to give an assistant more, make a new key and revoke the old one.

Keep the key in an environment variable, here TILLCAST_API_KEY, and never in a prompt, a chat, a file you commit or a log. The commands and files below ask the client to read the variable, so the key itself is not written into the client’s configuration.

Connect a client

Each tab says whether Tillcast tried it. Tried means that Tillcast ran the real client, with the version named, against a local build of the Tillcast server, made from its repository, and connected with a key. Not tried means the setup follows the vendor’s documentation, which the tab names, and nobody at Tillcast has run it.

Tried with Claude Code 2.1.301.

export TILLCAST_API_KEY='<your key>'
claude mcp add --transport http tillcast https://api.tillcast.com/mcp --header 'Authorization: Bearer ${TILLCAST_API_KEY}'

Keep the single quotes. Claude Code reads ${TILLCAST_API_KEY} when it connects, from the environment it runs in, so the key is not written into ~/.claude.json. Check it with claude mcp list: the line for tillcast ends in Connected.

To share the setup with a team, put this in .mcp.json at the root of the project. It holds no key, so it is safe to commit:

{
"mcpServers": {
"tillcast": {
"type": "http",
"url": "https://api.tillcast.com/mcp",
"headers": { "Authorization": "Bearer ${TILLCAST_API_KEY}" }
}
}
}

Source: Connect Claude Code to tools via MCP, Anthropic, read on 2026-10-21.

An MCP client that is not in the list should work if it speaks MCP over Streamable HTTP, can send an Authorization header and sends no Origin header (a page in a browser always sends one, and the server answers it with 403). A client that can only start a local program cannot connect. A client that offers only OAuth sign-in cannot connect yet either: OAuth sign-in for this server is planned and not available.

Two vendor APIs can also give a model a remote MCP server: the mcp tool of the OpenAI Responses API, with its authorization parameter, and the MCP connector of the Anthropic Messages API, in beta, with the authorization_token field of an entry in mcp_servers. The calls come from the vendors’ servers, so whether they send an Origin header is not known, and a Tillcast key in those fields was not tried. Tillcast has not tried either API, so both are not tested. Sources: MCP servers, OpenAI, and MCP connector, Anthropic, read on 2026-10-25.

Try it

Ask the assistant: “Use the Tillcast tools to show my organization.” The tool get_organization answers with your organization and the key’s own scopes, so you can see what the assistant may do. Then ask it to list your customers and printers.

To see a receipt without printing it, ask for a preview: “Preview a receipt for table 7 with two items on an 80 mm printer.” The assistant calls preview_document and shows you the paper as text.

What the tools do

The server has 28 tools. A key is shown only the tools its scopes allow, and a tool that is not shown still refuses with insufficient_scope if it is called.

GroupToolsScope
Organizationget_organizationany key
Customers and locationslist_customers, get_customer, create_customer, update_customer, delete_customer, suspend_customer, reactivate_customer, and the same seven for locationscustomers:read, customers:write
Printerslist_printers, get_printer, create_printer, update_printer, delete_printer, move_printer, rotate_printer_secretprinters:read, printers:write
Jobscreate_job, get_job, list_jobs, cancel_job, test_printjobs:read, jobs:write
Previewpreview_documentany key, and printers:read when it names a printer

Keys, members and settings have no tool. The server also offers a guide the assistant reads first (tillcast://guide/start), the block types of a receipt (tillcast://guide/blocks), and three prompts: print_receipt, set_up_customer and check_printer.

A job is the same job as in the REST API: a document of blocks, or receiptline text, exactly one of the two. Every create needs an idempotency_key, the same as the Idempotency-Key header of Idempotency.

Keep it safe

  • A person approves what prints. create_job and test_print print on real paper at a customer’s printer, and create_printer can print a welcome receipt when the printer first connects (welcome_print, on by default; an Epson prints none). Keep your client’s approval for tool calls switched on, and do not choose “always allow” for these tools. The server tells the assistant to preview first and to print only what you agreed to, but your client is the control that holds.
  • Preview first. preview_document draws the receipt as text. It prints nothing, bills nothing and keeps no copy of the receipt. create_job with dry_run: true does the same for a printer and checks what a real job would check, without making a job. It takes an idempotency_key like a real create.
  • Retries. Send an idempotency_key with every create, and the same one again if a call fails or times out, so that the thing is made once. test_print takes one too. Without one, a second call is a second page.
  • Printer addresses are passwords. create_printer and rotate_printer_secret return the printer’s address in the answer, and so in the conversation. Give a key printers:write only for a session that sets printers up.
  • Names are data. The text in a customer’s or a job’s fields was written by other people. The server shows invisible characters in it as ?, keeping only the few that an emoji or a script needs, but it cannot make visible text safe, so an assistant can be told what to do by a name. Approvals are the answer.
  • Everything is live. Every key works on the live account and prints on a real printer. Use the Read only preset until you know what you want, and revoke the key when you are done.

Troubleshooting

What you seeWhyWhat to do
401, “Server rejected the configured Authorization header”, authentication_required or invalid_api_keyThe key is missing, wrong, revoked or expiredCheck the variable in the environment that started the client, and the key in the dashboard
”Missing environment variables” (Claude Code), or the server shows as disconnected (Gemini CLI)The variable is not set where the client runsExport it in the shell that starts the client, then start the client again
The client opens an OAuth page, or fails with a message such as “Dynamic Client Registration rejected”The client sent no key, so it fell back to OAuth. OAuth sign-in for this server is planned and not availableAdd the Authorization header as shown above
The client says it needs OAuth, or has no field for a keyThe client offers only OAuth sign-in, which is not available yetUse a client from the list above
A tool answers insufficient_scope. This is a tool result with an error, not an HTTP 403The key lacks the scope that tool needsMake a new key with the scope. A key never gains scopes
403 with “This origin may not call the MCP endpoint”The request carried an Origin header, which a page in a browser always sends. The server refuses itUse a client that runs outside a browser page
Fewer than 28 toolsA key is shown only the tools its scopes allowExpected. See Which key to give
rate_limitedA limit on calls or on previews was reachedWait for the number of seconds in the message, then go on
result_too_large on a listThe page would not fit in one answerAsk again with a smaller limit, as the message says

Not yet

OAuth sign-in for the MCP server is planned, and it is not available. It would let an assistant that offers only OAuth sign-in, such as ChatGPT, connect without a key. There is no date. Until it exists, use a client that sends the key as a header. See the roadmap.

There are no template tools: a template language and stored templates are in development and not available. See Build with an agent for how a coding agent should read these docs, and what an agent must not do on its own.