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.
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.
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.
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.
Claude Code
Codex CLI
Gemini CLI
Cursor
VS Code
Zed
Claude on the web and Claude Desktop
ChatGPT
Tried with Claude Code 2.1.301.
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:
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.
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_jobandtest_printprint on real paper at a customer’s printer, andcreate_printercan 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_documentdraws the receipt as text. It prints nothing, bills nothing and keeps no copy of the receipt.create_jobwithdry_run: truedoes the same for a printer and checks what a real job would check, without making a job. It takes anidempotency_keylike a real create. - Retries. Send an
idempotency_keywith every create, and the same one again if a call fails or times out, so that the thing is made once.test_printtakes one too. Without one, a second call is a second page. - Printer addresses are passwords.
create_printerandrotate_printer_secretreturn the printer’s address in the answer, and so in the conversation. Give a keyprinters:writeonly 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
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.