---
topic: ai-setup
title: Setting up the shop's AI connection
summary: get_ai_status is always step 1 — it names the state and the exact next tool. The API key can never travel through this connection.
appliesTo: []
derivedFrom:
  - Plugin\tnt_mcp\src\Mcp\Tools\GetAiStatus::nextStep
  - Plugin\tnt_mcp\src\Mcp\Tools\BeginAiKeyEntry::run
  - Plugin\tnt_mcp\src\Ai\AiStatus::evaluate
  - Plugin\tnt_mcp\src\Settings\AiWriteSetting::enabled
---

## Domain model

The shop can talk to an LLM of the merchant's choosing: OpenAI, Anthropic, or any OpenAI-compatible
service. That connection has four parts — provider, default model, API key, and (compatible only)
an API address — plus two spending brakes, a daily cost ceiling and an hourly call ceiling. The key
is encrypted with a secret derived from this shop installation and is never handed back out; only
its last four characters are ever readable, here or in the admin.

Everything the merchant configures lives on one screen: **Plugins → JTL Shop - AI Connector → KI**.
Anything you change through a tool shows up there, and anything they type there is what your tools
read back.

## The one rule

**You cannot set the API key.** Not with `set_ai_configuration`, not by asking the merchant to paste
it into the chat. Live secrets do not survive this connection, and a key pasted into a conversation
has been disclosed to every system that conversation passes through. Never ask for one. The only
correct move is `begin_ai_key_entry`, which returns a one-time link the merchant opens themselves;
it expires in 15 minutes, works exactly once, and drops them on the KI tab with the key field
focused and everything else already filled in.

Everything else — provider, model, API address, both ceilings — you can set directly.

## Always start with get_ai_status

`get_ai_status` is the entry point, not a debugging tool. It answers with a `state`, the current
`configuration` (never the key), the `budget`, whether you are permitted to write at all, what is
`missing`, and — the part to act on — `nextStep`, which names the tool to call and the sentence to
relay. Do not infer the next move yourself; the tool has already decided it, and the admin banner
the merchant is looking at is fed from the same verdict, so following `nextStep` keeps you and the
screen in agreement.

Pass `checkConnection: true` when you need certainty rather than the last recorded result — it calls
the provider and records what happened. It costs a request, so use it to verify a change, not to
poll.

## The six states

| state | what it means | nextStep |
|---|---|---|
| `unconfigured` | Provider or model missing — you can fix this yourself | `set_ai_configuration` |
| `key_missing` | Everything but the key is set, or the stored key can no longer be decrypted | `begin_ai_key_entry` |
| `untested` | A key is stored but the provider has never confirmed it | `test_ai_connection` |
| `active` | Configured and working | nothing to do |
| `degraded` | Works, but a limit the merchant set is reached, or costs are unpriced | usually nothing — ask whether to raise the limit |
| `down` | The provider is refusing or failing | `begin_ai_key_entry` if the key is rejected, otherwise `test_ai_connection` |

`degraded` is not a fault. A reached ceiling is the merchant's own decision working as intended; say
so, and ask whether they want to raise it rather than reporting a breakage.

## The happy path, end to end

1. `get_ai_status` — read `state` and `nextStep`.
2. `state: unconfigured` → ask the merchant which provider they use, then `set_ai_configuration`
   with the provider and, if they know one, a default model. `list_available_models` can offer them
   a choice once a key exists.
3. `state: key_missing` → `begin_ai_key_entry`, hand over the returned link, and say plainly that
   they have to type the key in themselves because it cannot travel through this connection.
4. After they confirm they have entered it: `get_ai_status` with `checkConnection: true`.
5. `state: active` → tell them which model is live. `estimate_prompt_cost` answers "what will this
   cost?" before they commit to an automation.

## When writing is switched off

The merchant can disable AI writes entirely (**Einstellungen → "KI darf die KI-Zugangsdaten des
Shops setzen"**, on by default). When it is off, `get_ai_status` still reads and still tells you the
state, but `nextStep` carries no tool — only an admin link and the instruction to ask the merchant
to switch it on or to configure everything by hand. Do not retry the write tools against it; they
refuse, by design.

## What this is not

This guide is about the shop's connection to an LLM. It is not about the MCP connection you are
using right now — that is OAuth, and it is already working if you are reading this.
