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:

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

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: a service account for the server, a role that may use exactly this server and call the scenarios behind its tools, and 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 and the role appear in Access control like any other.

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 removing the role, 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.

Scenario	MCP tool
Name	Tool 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 schema	Tool input schema
Slug	Tool 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. Whether a server may be opened to calls without a token is mcp.allowOpenAccess; see Exposing scenarios as MCP tools.