Skip to main content
Version: Current

MCP servers - scenarios as MCP tools

The MCP item in the side menu (the page titled Model Context Protocol servers, at /mcp) is where you publish Request-Response scenarios as tools of an MCP server that Nussknacker hosts. AI agents and LLM clients that speak MCP - Claude, Cursor, your own agents, or the AI Agent component of another Nussknacker instance - connect to that server and call your scenarios as tools.

note

This is Nussknacker acting as an MCP server. The opposite direction - an AI Agent in your scenario calling the tools of an external MCP server - is configured in Integrations, as an MCP Server integration. The two are independent: an instance can use either, both or neither.

Creating an MCP server​

Click Create new MCP and fill in:

FieldDescription
MCP nameName of the server. It becomes the last segment of its endpoint URL.
Request-response scenariosThe scenarios published as tools. A scenario marked not deployed is not offered to clients until it is deployed; missing means it is gone.

Under About you may say what the server is, all of it optional. A client gets it in the answer to initialize; what is left empty is not sent.

FieldSent asDescription
TitleserverInfo.titleThe name a client shows for the server. Without it, the client shows the MCP name. Up to 100 characters.
DescriptionserverInfo.descriptionWhat the server is for, for the person choosing it in a client. Up to 2000 characters.
InstructionsinstructionsHow to use the tools, for the model: which one to call first, what to avoid. A client may add it to its system prompt. Up to 4000 characters.
WebsiteserverInfo.websiteUrlA page about the server, e.g. its documentation; an https:// or http:// address.

On a saved server a field that is set shows a pencil, and the ones that are not set are added with the buttons below them; each is saved on its own, and changing one takes MCP.Edit. A client reads them when it connects, so one that is already connected shows a change after it reconnects.

A scenario becomes a tool only in the hands of somebody who may deploy it (Scenario.Deploy in its category); the others are offered but cannot be picked. A tool the server's clients can already call stays whoever saves the server, and anybody who may edit the server can remove one. A saved tool they can't call yet takes Scenario.Deploy like a new one: until somebody who may deploy it saves the server, or the tool is removed, others can't save the server.

How to connect shows what to give to the client:

  • Endpoint URL - https://<your Nussknacker host>/api/custom/mcp/<MCP name>; the client sends MCP JSON-RPC requests (initialize, tools/list, tools/call) to it with HTTP POST.
  • HTTP headers and Client configuration - the token the client sends with every request, and a ready configuration snippet for common MCP clients.

Expand the tools preview to see the tools exactly as a client will list them.

Who may call the server​

A client calls the server with a Nussknacker API token whose owner may use that server (the MCP.Use action on it); nothing else is accepted. Until the server has a token, nobody can call it - the access section says so.

Generate token sets everything up in one step: the first time, the server's own service account, which may use exactly this server and call the scenarios behind its tools; then a token - shown once, with a name and a lifetime you choose under Options. Clicking it again issues another token for the same account, and the section lists the server's tokens with their status and when each was last used, so that one can be revoked without touching the others. Generating or revoking a token decides who may call the server, as opening it does, so it needs the right to change the server (MCP.Edit) and to manage access (RBAC.Manage). The account appears under Administration → Service accounts with the server's name (see Access control). The Service account: … link in the server's access section opens that account's profile.

The account's access follows the server. Saving the server with other tools changes the scenarios its clients may call at once; if that change could not be made, the save is refused when it would take a scenario away, and goes through with a warning when it would only add one - save again to retry. Deleting the server deactivates the account and revokes its tokens; if that fails midway, delete the server again to finish.

Only the server's own account follows its tools. Another account given MCP.Use on the server as direct access in Access control gets no scenarios with it: a tool whose scenario requires a token answers it only with Scenario.Invoke on that scenario, given separately, and a tool added later is not included. Generate a token here instead, unless the client needs exactly that.

The client sends the token in the Authorization: Bearer header, or in X-Nussknacker-Api-Token. A client that cannot set Authorization may use a header of the server's own choice: set Token header under Options (e.g. X-Api-Key); it is saved with the server, so changing it takes MCP.Edit. Revoking the token, or deleting the server, cuts the client off within 30 seconds.

A server may instead be switched to Open - no token required: anybody who reaches the endpoint can then call its tools, which run as the Designer itself and are attributed to nobody. It fits a network that authenticates in front of Nussknacker, or a demo. Switching takes MCP.Edit, as it saves the server. The installation may forbid open servers.

When a tool's scenario itself requires a token (its Access property, see Who may call the scenario), the tool call reaches it with the caller's token, so the scenario checks that the caller may call it. A token generated for the server may call the scenarios behind its tools.

How a scenario becomes a tool​

Only deployed Request-Response scenarios can be tools. A call to the tool calls the scenario through its HTTP endpoint and returns the scenario's response.

ScenarioMCP tool
NameTool name derived from the scenario name (see normalization below)
Description (scenario properties)Tool description; without one, the tool is described as Request-response scenario: <name>
Input schemaTool input schema
SlugTool title

Tool names keep letters, digits, _ and -; other characters become _. Consecutive underscores collapse into one, and leading and trailing underscores are removed. If nothing remains, the name is scenario_tool. For example, __Order lookup!__ becomes Order_lookup, and !!! becomes scenario_tool. Names are case-sensitive; letters are not lowercased.

The tool description is what the model reads when it decides whether to call the tool, and the input schema is what it has to fill in. Describe the scenario business-first: what question it answers and what it needs, not how it is built.

Configuration​

The Designer calls the scenarios through the Request-Response runtime configured under mcp.requestResponse in the Designer configuration: baseUrl (default http://localhost:8181/), optional basic auth, and timeout (default 30 seconds) for a single tool call. The servers speak MCP revision 2025-11-25 and answer a client that asks for 2025-06-18 or 2025-03-26 in that revision; mcp.protocolVersion sets the newest revision they offer. Whether a server may be opened to calls without a token is mcp.allowOpenAccess; see Exposing scenarios as MCP tools.

Tools that ask the user a question​

A scenario with an Interaction node pauses and waits for more input. Called as a tool by a client of revision 2026-07-28 that declares the elicitation capability, it asks the client's user instead: tools/call is answered with resultType: "input_required" and one form-mode elicitation/create request - the node's Question with one field, a choice of the node's items for a menu and free text otherwise. The client sends the same call again with the answer and the requestState it was given, and gets the tool's result, or the next question when the scenario pauses again.

  • requestState is encrypted by the Designer and is accepted only from the same caller, on the same server and tool, with the same arguments, for mcp.requestState.ttl (default 5 minutes). Anything else is refused with -32602 and the tool has to be called again. On a server open to calls without a token every caller counts as the same one, so there a state is bound to the server, the tool and the arguments only.
  • The key is drawn when the Designer starts. Set mcp.requestState.secret (at least 32 characters) when several Designers serve one address, or to keep questions answerable across a restart of the Designer. The paused scenario itself lives in the memory of the Request-Response runtime, so a restart of the runtime still loses it.
  • An answer that is not one of a menu's items does not resume the scenario: the question is put again. So is a retry that brings no answer - to a client that still declares the capability; one that does not gets an error result.
  • Only form mode is used, with one text or single-choice field per question. A client without the capability, or of an earlier revision, gets the node's pause response as the tool's result, as before.

Protocol revisions​

The servers speak MCP revisions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26 on the same endpoint, and the client chooses by how it opens:

  • A client of 2026-07-28 sends no initialize. Each request names the revision and the client's capabilities in _meta and repeats them in the MCP-Protocol-Version, Mcp-Method and, for tools/call, Mcp-Name headers. The server answers server/discover, tools/list and tools/call, and keeps nothing between requests. A request whose headers are missing or differ from its body gets 400 with the JSON-RPC error -32020, a revision the server does not speak 400 with -32022 and the list of the ones it does, and an unknown method 404. A proxy in front of the Designer has to pass the Mcp-* headers through. The same checks apply when only the header names 2026-07-28 and the body an earlier revision, and a request that sends one of these headers twice is refused whatever revision it names.
  • A client that opens with initialize is served as before, in the revision it asks for or, when the server does not speak that one, in 2025-11-25.

A tool's input schema is published without x-mcp-header annotations, even when the scenario's schema has them: the servers do not compare Mcp-Param-* headers with the arguments of a call, so they do not ask clients to send them. Do not route or authorize on Mcp-Param-* headers in front of the Designer.

mcp.protocolVersion sets the newest revision the servers offer (default 2026-07-28). Set below 2026-07-28, it turns the stateless revision off: every request is then answered the way the earlier revisions expect.