External AI Agents
Besides the built-in AI assistant, you can let an AI agent you already use – Claude Code, Claude Desktop, Cursor or any other client that supports the Model Context Protocol (MCP) – read, build and change scenarios on a Nussknacker Designer. The connection is made by nu-cli, the Nussknacker command line client, which runs an MCP server on your machine and talks to the Designer's API on your behalf.
This page is about agents that work on Nussknacker. To let an agent call your scenarios as tools, or to use external MCP tools inside a scenario, see MCP Server and the AI Agent component.
nu-cli in short
nu-cli is a single executable with no other dependencies. Install it with:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/TouK/nussknacker-cli-dist/main/install.sh)"
By default it is installed as ~/.local/bin/nu-cli. Its full documentation is the
nu-cli README; the commands below are the ones needed to connect an agent.
- Log in to a Designer once:
nu-cli login --url https://your-designer.example --browser.--browsersigns you in through the Designer's own login page;--token,--token-stdinand--basic-userare alternatives. The credential is stored indesigner.yaml(in.nussknacker-cli/of the working directory or in~/.config/nussknacker-cli/), readable only by you. - Profiles let one configuration hold several Designers, for example
localandstaging.-p <profile>picks one,nu-cli login ... -p <profile>creates it,nu-cli profile listlists them andnu-cli whoamishows which instance and user a command would use. The built-indemoprofile points at the public demo instance. - Scenario commands (
nu-cli scenario list,scenario graph,scenario validate,scenario diff,scenario save,nu-cli live, ...) are the same operations the agent gets, for a person at a terminal.
The agent acts as the user nu-cli is logged in as, with that user's permissions.
Connecting an agent
The agent's client starts nu-cli mcp itself and talks to it over standard input and output, so you register
the server in the client rather than run it. Run nu-cli mcp in a terminal and it prints what to register:
a claude mcp add ... command for Claude Code and an mcpServers JSON block for clients configured with JSON
(Claude Desktop, Cursor, ...), one server per profile, with the full path to the executable.
nu-cli mcp -p staging # prints the registration for the staging profile, read and draft only
nu-cli mcp -p local --allow-write # prints a server that may also save on the local Designer
One server serves one Designer, with its own permissions. Register a separate server for each profile, named for
example nussknacker-local and nussknacker-staging, so an agent can save on one instance and only read another.
Restart or reload the client after adding a server.
Safety flags
Nobody can confirm individual calls over MCP, so what the agent may do is decided by the flags the server starts with. A tool that is not allowed is not offered to the agent at all.
| Flag | What the agent may additionally do |
|---|---|
| (none) | read scenarios, components, validation results, live data, skills and topics; edit and discard the local draft |
--allow-write | create, save, archive and unarchive scenarios; create and update topics |
--allow-deploy | deploy and cancel scenarios; send a test message to the topic configured for nu-cli send |
--allow-delete | delete scenarios and topics – every call still asks you in the client to type a confirmation phrase |
--dry-run | offer every tool, but answer writes with the request they would send instead of sending it |
Start without any flag and add them only when needed, especially for instances other than your local one.
Edits stay local until saved. Without --allow-write the agent can still change a scenario, but only in a
draft kept by nu-cli on your machine. Review it with nu-cli scenario diff <name>, then save it with
nu-cli scenario save – or let an agent with --allow-write call save_scenario.
Every call the agent makes is logged, one line per call, to ~/.local/state/nussknacker/mcp.log
(or the file given with --log-file). Run tail -f on it to watch what the agent does.
Tools
The tools have the same names and behaviour as the AI assistant's, with one difference: nothing is "currently opened" in a terminal, so every scenario tool takes the scenario name.
| Access | Tools |
|---|---|
| read | list_scenarios, get_scenario, get_scenario_statuses, get_live_data, get_validation_results, get_components, get_component_definition, list_configured_services, list_skills, get_skill, list_topics, get_topic, preview_topic_messages |
| draft (default) | change_scenario_values, change_scenario_labels, add_node, add_node_between, replace_node, delete_node, add_edge, delete_edge, apply_scenario_graph, import_scenario_graph, run_auto_layout, discard_draft |
--allow-write | create_scenario, save_scenario, archive_scenarios, unarchive_scenarios, create_topic, update_topic |
--allow-deploy | deploy_scenario, cancel_scenarios, send_message |
--allow-delete | delete_scenarios, delete_topic |
Topic tools need the Topics extension on the Designer. When the Designer refuses a call,
the tool answers with { "status": "rejected", "reason": ... }, which the agent can read and act on.
Skills
list_skills and get_skill return the playbooks the Designer publishes for multi-step work – building a scenario,
choosing components, writing SpEL, testing. They are read from the Designer instance, not from nu-cli, so an agent
always gets the skills that match the instance it works on, the same ones the built-in assistant uses. Ask your agent
to read the relevant skills (for example scenario-authoring) before it creates or modifies a scenario.
WebMCP (experimental)
An agent that drives a browser can also use the Designer's own tools directly in the page, through
WebMCP. It is off by default; turn on the experimental.exposeWebmcp
user setting (on the /__settings page) to expose the assistant's tools to such an agent. The tools then run in your
browser session, on the scenario opened in the editor. A panel in the scenario editor reminds you that exposure is on;
use turn off there to disable it.