Connect my agent
Beans Workbench offers two ways to get AI help. Beans Assistant is the chat built into the
Workbench: nothing to install, it sees the page you are on and asks before it changes a file.
Your own agent (Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, or any other MCP
client) can use the same tools through the Workbench's MCP server, dzt mcp; that is what this
page sets up. It also holds the list of other MCP servers (Blender, Sketchfab, your own) whose
tools Beans Assistant may use. For the second way you need the agent installed; it runs on its
own plan, no Beans account is needed.
In both cases the secrets of your settings (gateway token, API keys, webhook URLs, signing key)
are never sent to a model: Beans Assistant redacts every tool result before it leaves the
Workbench, and the tool that reports your setup to any agent (dayz_environment) gives folders only.
The screen
- Two ways to get AI help (top card): a reminder of the two ways, Open Beans Assistant when the built-in assistant is available, and How it works, which opens this page.
- Connect my agent (left card): one row per agent with its state on this computer: connected (the server is in its configuration and its command exists), found (installed, not connected), not installed, or command not found (connected to a Workbench that was moved or deleted). Each row has By hand and, until it is connected, Connect.
- Test server and Look again (under the rows): Test server checks that the Workbench's
server answers; Look again searches for the agents once more. The path on the right is the
dztprogram the agents will start. - Beans skills: with a Modder or Creator plan, a signed-in agent also gets the Beans skills
(verified playbooks, loaded one at a time with
skill_load, for your own use only: the terms forbid sharing them). Casual and the free month give the tools without the skills. Sign in with Steam is offered when you are not. - Log (appears after an action): what Connect did, or why it failed.
- Tools exposed (right card): after Test server, every tool the server offers with its description. Below, example prompts: a click writes one in Beans Assistant (you still send it), or copies it when the built-in assistant is not set up.
- MCP servers for Beans Assistant (bottom card): the external servers you added, each with its state (not started, connecting…, ready, N tools, error, disabled), Enabled, Test, Tools, Edit and remove. Above the list: Add server, Import JSON, Add Blender, Add Sketchfab, Connect all.
First steps
- Open Connect my agent in the rail (the Run group).
- Find your agent in the left card. If it says not installed, install it, then Look again.
- Click Connect on its row. For Claude Desktop, quit it completely first (tray icon too).
- Restart the agent so it loads the server. It appears there under the name
dayz. - Click Test server: the right card lists the tools your agent now has.
- In your agent, ask something that needs them, for example one of the example prompts.
Take the tour (in the app)
Common tasks
Use Beans Assistant, the built-in chat
- Press Ctrl+J, or click the spark in the rail or in a page header. The panel opens on the right; on Home the chat is in the page.
- Type your request.
@mentions a file, Ctrl+V pastes an image, the paperclip attaches files. Secrets of your settings (webhooks, keys, tokens) are removed from attached text, and the Workbench's own settings and session files are never attached. Replies show no image from the web: an image link is shown as its text. - Read the chip under the message box:
Context: …names what the page sends with your message. Click it to read the exact text; click its mark to stop sending it. - Choose the mode (see Concepts), then press Enter.
It shows unless you turned it off in Settings (sign in with Steam). Every signed-in account has a small free use each month with the default model, to try it; a plan (one per Steam account) adds a daily limit that resets every day at 00:00 UTC (Casual 12 €, about 14 GLM 5.3 Flash requests a day; Modder 29 €, about 20; Creator 79 €, about 60), and packs add credits that do not expire. The bar in the panel header shows what is used; click it for the details. Take its tour (in the app)
Start a recipe
Recipes are guided tasks: import a weapon, add a vehicle lock, set up a trader, publish to the Workshop. Open the catalogue from Recipes in the panel header (it works mid-conversation), Help > Recipes in the menu bar, See all on Home, or the chips a page shows when it is empty. Search by words or filter by category (Create, Improve, Test & fix, Server, Publish), then click a card: a new conversation starts, asks the recipe's questions, proposes a plan and works step by step, each step ended by a check. A card with a lock and a plan's name needs that plan; clicking it says so and opens the shop. Each page's help panel (F1) lists the recipes for that page.
A card's time is the assistant's: "a first version in ~20 min" for a recipe that creates something, "a session of ~30 min" for one that improves a mod you already have. When a recipe's steps are done, What next under the checklist offers the recipes that usually follow (test in game and fix, add a feature, balance, publish).
Build a mod over several days
Real mods take more than one sitting. Plan a mod over several days (on Home, or Make it a
project after a recipe) asks for the goal, who it is for and its size, then writes a roadmap:
a goal and milestones (a first version, a test in game, fixes, a feature, polish, a publish),
kept in the mod's .beans/ROADMAP.json. You approve it like any file change and can edit it.
Every conversation on that mod starts with the roadmap, so Beans picks up where you stopped.
Continue on Home starts a session on the next milestone: the assistant reads the code made in
earlier sessions, does the milestone, checks it, marks it done and adds what it found (a bug, a
rough edge) as new milestones. The Improve recipes (add a feature, fix what testers reported,
balance prices and loot) and Test in game and fix work the same way on any mod.
See your usage and purchases, get a plan or a pack
- Once signed in with Steam, a usage bar shows in the panel header (and above the composer on Home): your plan's limit, else this month's free use, with about how many requests are left, and your pack credits. Click it: a menu opens with the usage bars, each with when it resets and about how many requests are left.
- Account and usage: the usage bars, your plan, the replies per day over the last 30 days, your purchases with their receipts, and the prices per model.
- Plans and packs: the shop. Each plan says what it includes (all models, every recipe) and about how many requests a day; each pack about how many requests it pays. Tick the 14-day withdrawal box, then click a plan or a pack; the payment page opens in your browser and the account updates when it is paid. With a plan, click another one to change: it starts once paid, your old plan ends and Stripe credits its unused time.
The catalogue's recipes (guided actions) come with a Beans plan; without one, one recipe a month is free (the chip above the catalogue says whether it is used). The tools stay free. Audit my mod reviews a mod in a fresh conversation: security, player data, performance, compatibility, a game test, then a report with the fixes. A mod you create is yours: its first line says it was made with Beans Workbench, and you may remove it.
Models do not cost the same. The picker has two groups: Included, the default model (GLM 5.3 Flash), which the free month and the plans are counted in; and Premium, the Claude models (Haiku, Sonnet, Opus), which give stronger answers and use your plan faster. Each model shows its rate next to its name (×1 for the default model, ×6 for a model six times dearer), and after each reply a line says about how many requests are left in the limit that paid it, or, when packs paid, what it cost and why. The free monthly use is for the default model only: with another model picked, a refused request says so. When nothing is left, the conversation says when the limit comes back, with Plans and packs. A request starts only when a limit can pay for it: its prompt and a reply (the free month, then your plan's day, then the packs). When what is left is too little for the model you picked (a long conversation with Claude Max, say), the request is refused before it starts and names a cheaper model that fits, with a button that picks it and sends the request again. The reply is kept within what the limit can pay; what a reply still runs past it is counted in the next day (or month). 4. Manage plan (with a plan) opens Stripe's billing portal to cancel or update the card; Sign out forgets the session.
Settings has the same under Account & usage, with Sign in with Steam when you are signed out.
Approve, refuse or undo a change
- In Ask before changes mode, each change is shown first (a diff for files) with three answers: yes; yes and stop asking for this tool in this conversation; no, with what to do instead.
- After an answer that changed files, click N files changed under it to see the diffs.
- Revert file puts one file back; Undo this answer's changes puts back all of them.
- Rewind on one of your messages puts the files back as they were at that message, cuts the conversation there and returns its text to the message box. When a file cannot be put back (locked, read-only), the rewind stops: the conversation stays as it was.
- A file you changed since is shown with what changed and asks: overwrite or skip. Game files
are never changed. Files removed by an undo are kept in a
.beans-revertedfolder.
Connect an agent by hand
- Click By hand on the agent's row. Nothing is changed.
- For Claude Code, run the command shown in a terminal. For the others, add the lines shown to the file named above them. Copy copies them.
- Restart the agent, then Look again: the row should say connected.
Check that the server works
- Click Test server. The Workbench starts
dzt mcp, does the MCP handshake and asks for the list of tools. - A toast gives the number of tools and the right card lists them. A failure is shown in the log of the left card.
Test server checks the Workbench's side only. If it passes and your agent still shows no tools,
the agent was not restarted, or its configuration points to another dzt (command not found:
click Connect to point it to this Workbench).
Add Blender or another MCP server for Beans Assistant
- In the bottom card, click Add Blender (needs
uvand the mcp-for-blender add-on enabled in Blender), Add Sketchfab (needs Node.js and your own Sketchfab API key, which the form asks for), or Add server for any other. - For Add server, give a name, then either a local command with its arguments (one per line) or a remote URL. Environment values and headers are kept on this computer.
- Click Test on its row: the state becomes ready, N tools, or error with the reason. Tools lists what it offers.
- Leave Trusted off unless you want its tools to run without asking.
Import JSON takes the mcpServers block of a Claude Desktop or Claude Code configuration.
Examples
This page has no example to open. The example prompts under the tools list are requests to try with either assistant.
Concepts
- MCP (Model Context Protocol) is the standard way for an AI agent to call tools offered by another program. See https://modelcontextprotocol.io.
dztis the Workbench's command-line program;dzt mcpis the MCP server, speaking over standard input and output. The agent starts it itself each time it runs: the Workbench window does not need to be open.- Connect registers the server under the name
dayz. Claude Code is registered through its own command (claude mcp add --scope user). For Codex CLI a[mcp_servers.dayz]section is added to itsconfig.toml; for Gemini CLI, Cursor and Claude Desktop adayzentry is added tomcpServersin their JSON file. The previous file is kept next to it as<file>.beans-backup. A file that is not plain JSON is left alone and By hand opens instead. - Modes of Beans Assistant. Ask before changes: reads run on their own, every change is shown and waits for you. Auto: changes in your folders run without asking; publishing still asks, and so does every tool of an external server that is not trusted. Auto is not kept for the next start. Plan: the assistant only reads, then proposes a plan; nothing changes until you approve it.
- Context. Each page tells Beans Assistant what it shows (open file, selection, tab, unsaved edits, last problems) plus the folders that matter. It is short, has no secrets, and is sent again only when it changed. An external agent does not get it: it sees only tool results.
- Checkpoints. Before the assistant changes a file, the Workbench keeps a snapshot of it. That is what the diffs, Revert, Undo and Rewind use.
- Trusted server. Tools of an external MCP server are named
mcp__<server>__<tool>and are asked every time, even in Auto, unless the server is marked trusted.
Pitfalls
- Connecting an agent and not restarting it: agents read their servers at start.
- Clicking Connect while Claude Desktop runs: it rewrites its configuration from memory and drops the server. The page refuses and tells you to quit it first.
- Moving or deleting the Workbench after connecting: the row shows command not found; Connect repairs it.
- Reading Test server as a test of the agent: it only shows that
dzt mcpanswers. - Marking a server trusted to stop the questions: an MCP server runs with your permissions. Add only servers you trust, and keep Trusted for those you know well.
- Expecting the external servers of the bottom card in your own agent: they are for Beans Assistant. Add them to your agent in the agent's own configuration.
- Removing a server deletes its settings at once, including a key typed in its environment.
For agents
dzt mcpserves the tools;dzt toolslists them;dzt tool <name> '<json>'calls one from a terminal.dayz_environmentreports the detected folders (never keys or webhook URLs).- By hand, the registration is
claude mcp add --scope user dayz -- "<path to dzt>" mcp, or a server nameddayzwith command<path to dzt>and arguments["mcp"]. dzt loginsigns in to the Beans gateway; with a plan,dzt mcpthen adds the Beans rules to its instructions and offersskill_load.dzt checkpoints list,show <conversation>,revert <conversation>do the undo of Beans Assistant's file changes without the window.- The page reads each agent's configuration to find the
dayzserver and writes it only on Connect:~/.claude.json(through theclaudeprogram),~/.codex/config.toml,~/.gemini/settings.json,~/.cursor/mcp.json, andclaude_desktop_config.jsonin Claude Desktop's configuration folder. External servers are saved in the Workbench's settings. - Never read, print or ask for the gateway token, API keys, webhook URLs, or the environment and headers of the external servers.
- The page tells Beans Assistant: the path of
dzt(or "not found"), the agents connected, the agents found but not connected, the number of tools that answered the last test, whether Beans Assistant is available, the names of the enabled external servers, and the errors of its log. - Anchors a tour can point at:
assistant-builtin,assistant-agents,assistant-agent,assistant-connect,assistant-manual,assistant-test,assistant-skills,assistant-tools,assistant-prompts,assistant-servers,assistant-server-add,assistant-server-blender; in the Beans Assistant panel:beans-composer,beans-context,beans-mode,beans-history.
See also
- Settings: show or hide Beans Assistant, your folders.
- Home: the guided actions of Beans Assistant.
- Models: where models made with Blender through the assistant end up.
- The Workbench: the rail, the help panel, the tours.
docs/ASSISTANT.mdin the repository: what is sent, credits and plans, the gateway.