> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Connect an AI assistant (MCP)

> How to connect an AI coding assistant to the Tillcast MCP server with an API key: the address, the setup for Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, Zed and Claude custom connectors, which key to give, what the tools do, safety and troubleshooting. OAuth sign-in is planned, not available.

> **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](/api-reference), 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.

|                    |                                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Address            | `https://api.tillcast.com/mcp`                                                                                              |
| Sign-in            | Your API key as a bearer token: the header `Authorization: Bearer <your key>`                                               |
| Transport          | MCP over HTTP, JSON only: each `POST` carries one message and gets one JSON answer. There is no event stream and no session |
| Protocol revisions | 2026-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](/api/authentication)). 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 to                      | Give it                                           | It sees                                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Look around and draw receipts. Nothing prints  | The **Read only** preset                          | 10 tools                                                                                                                                              |
| Print receipts and test pages for one customer | The **Printing** preset, limited to that customer | 9 tools, among them `create_job` and `test_print`                                                                                                     |
| Set customers, locations and printers up, once | The **Installer** preset, for that session only   | 23 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.

#### Claude Code

**Tried** with Claude Code 2.1.301.

```bash wordWrap
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:

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

Source: [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), Anthropic, read on 2026-10-21.

#### Codex CLI

**Not tried** with a session. Codex CLI 0.163.0 accepted this configuration, and `codex mcp get tillcast` showed a streamable HTTP server with a bearer token from `TILLCAST_API_KEY`. Nobody at Tillcast has run a session with it.

Add this to `~/.codex/config.toml`:

```toml wordWrap
[mcp_servers.tillcast]
url = "https://api.tillcast.com/mcp"
bearer_token_env_var = "TILLCAST_API_KEY"
```

The same from the command line: `codex mcp add tillcast --url https://api.tillcast.com/mcp --bearer-token-env-var TILLCAST_API_KEY`.

Source: [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp), OpenAI, read on 2026-10-21.

#### Gemini CLI

**Tried** with Gemini CLI 0.65.0.

```bash wordWrap
export TILLCAST_API_KEY='<your key>'
gemini mcp add --scope user --transport http --header 'Authorization: Bearer ${TILLCAST_API_KEY}' tillcast https://api.tillcast.com/mcp
```

Keep the single quotes, so that the settings file keeps `${TILLCAST_API_KEY}` and not the key. Gemini CLI reads the variable when it connects. Check it with `gemini mcp list`: the line for `tillcast` ends in `Connected`. Gemini CLI's Trusted Folders setting, which is off unless you switch it on, keeps MCP servers from connecting in a folder that you have not marked as trusted.

Sources: [MCP servers with Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) and [Trusted Folders](https://geminicli.com/docs/cli/trusted-folders/), Google, read on 2026-10-25.

#### Cursor

**Not tried.**

Put this in `.cursor/mcp.json` in the project, or in `~/.cursor/mcp.json` for all projects:

```json wordWrap
{
  "mcpServers": {
    "tillcast": {
      "url": "https://api.tillcast.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TILLCAST_API_KEY}" }
    }
  }
}
```

Source: [Model Context Protocol (MCP)](https://cursor.com/docs/mcp), Cursor, read on 2026-10-25.

#### VS Code

**Not tried.**

Put this in `.vscode/mcp.json` in the project, or add it to your user profile. VS Code asks for the key the first time the server starts and keeps it, so it is not in the file:

```json wordWrap
{
  "inputs": [
    { "type": "promptString", "id": "tillcast-key", "description": "Tillcast API key", "password": true }
  ],
  "servers": {
    "tillcast": {
      "type": "http",
      "url": "https://api.tillcast.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tillcast-key}" }
    }
  }
}
```

Source: [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration), Microsoft, read on 2026-10-21.

#### Zed

**Not tried.**

Add this under `context_servers` in `settings.json`:

```json wordWrap
{
  "context_servers": {
    "tillcast": {
      "url": "https://api.tillcast.com/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}
```

Zed's page shows the token written into the file, so the key sits in plain text in your settings. Keep that file out of version control.

Source: [Model Context Protocol](https://zed.dev/docs/ai/mcp), Zed, read on 2026-10-21.

#### Claude on the web and Claude Desktop

**Not tried.** Anthropic's help page for custom connectors describes a **Request headers** field for fixed credentials such as API keys. Tillcast has not used it.

On a Pro or Max plan, go to **Customize**, then **Connectors**, click **+ Add** and **Add custom connector**. On a Team or Enterprise plan an owner goes to **Organization settings**, then **Connectors**, and chooses **Add**, **Custom**, **Web**. Enter the address `https://api.tillcast.com/mcp`. Set **Authentication** to **No sign in**, and under **Request headers** add the header `Authorization` with the value `Bearer <your key>`. On a Team or Enterprise plan, everyone who uses the connector reaches Tillcast with that one key, so make it a key with few scopes.

If this does not connect, see [Troubleshooting](#troubleshooting). One thing is not known: whether Anthropic's servers send an `Origin` header, which the Tillcast server refuses.

Source: [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), Anthropic, read on 2026-10-21.

#### ChatGPT

**Not yet.** ChatGPT's form for a custom MCP server offers OAuth or no authentication, and no API key or header. OAuth sign-in for the Tillcast MCP server is planned and not available, so ChatGPT cannot connect to it today. There is no date.

Source: [Add custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server), OpenAI, 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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp), OpenAI, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/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.

| Group                   | Tools                                                                                                                                                                  | Scope                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Organization            | `get_organization`                                                                                                                                                     | any key                                              |
| Customers and locations | `list_customers`, `get_customer`, `create_customer`, `update_customer`, `delete_customer`, `suspend_customer`, `reactivate_customer`, and the same seven for locations | `customers:read`, `customers:write`                  |
| Printers                | `list_printers`, `get_printer`, `create_printer`, `update_printer`, `delete_printer`, `move_printer`, `rotate_printer_secret`                                          | `printers:read`, `printers:write`                    |
| Jobs                    | `create_job`, `get_job`, `list_jobs`, `cancel_job`, `test_print`                                                                                                       | `jobs:read`, `jobs:write`                            |
| Preview                 | `preview_document`                                                                                                                                                     | any 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](/concepts/documents), or `receiptline` text, exactly one of the two. Every create needs an `idempotency_key`, the same as the `Idempotency-Key` header of [Idempotency](/api/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 see                                                                                                 | Why                                                                                                          | What to do                                                                                  |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `401`, "Server rejected the configured Authorization header", `authentication_required` or `invalid_api_key` | The key is missing, wrong, revoked or expired                                                                | Check 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 runs                                                                | Export 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 available | Add the `Authorization` header as shown above                                               |
| The client says it needs OAuth, or has no field for a key                                                    | The client offers only OAuth sign-in, which is not available yet                                             | Use a client from the list above                                                            |
| A tool answers `insufficient_scope`. This is a tool result with an error, not an HTTP `403`                  | The key lacks the scope that tool needs                                                                      | Make 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 it        | Use a client that runs outside a browser page                                               |
| Fewer than 28 tools                                                                                          | A key is shown only the tools its scopes allow                                                               | Expected. See [Which key to give](#which-key-to-give)                                       |
| `rate_limited`                                                                                               | A limit on calls or on previews was reached                                                                  | Wait for the number of seconds in the message, then go on                                   |
| `result_too_large` on a list                                                                                 | The page would not fit in one answer                                                                         | Ask 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](/roadmap).

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