🇬🇧 EN

🔧 MCP Tool

Defines an external tool that an Agent node can call during its reasoning loop, using the Model Context Protocol (MCP). Connect one or more MCP Tool nodes to an Agent's tool_in port. The agent decides autonomously when and whether to invoke each tool.

Category: AI & Agents · Type identifier: mcp_tool · Graph mode only

Overview

The Model Context Protocol (MCP) is a standard that lets AI models call external tools — programs, APIs, or services — as part of their reasoning. When an agent has tools available, it can decide mid-response to call one, receive the result, and incorporate it into its final answer. This enables agents to look things up, perform calculations, query databases, or interact with any external system.

In Flusso, each MCP Tool node defines one tool. The node specifies the tool's name, a description the model uses to decide when to call it, and how Flusso should connect to the tool — either by launching a local subprocess (stdio transport) or by connecting to an HTTP JSON-RPC server (SSE transport).

You can connect multiple MCP Tool nodes to a single Agent. The agent receives the full list of available tools and selects the appropriate one based on the user's request.

Writing good descriptions is critical. The model uses the description to decide whether a given tool is relevant. Write descriptions that clearly state what the tool does, what inputs it expects, and when it should be used. Vague descriptions lead to the agent ignoring the tool or calling it at the wrong time.

Configuration

Field	Status	Description
Name	Required	The tool name the agent sees. Use a short, descriptive, lowercase name with underscores — for example `search_web`, `get_weather`, `query_database`. The model references this name when it decides to call the tool.
Description	Required	A natural-language explanation of what the tool does. The model reads this to decide when and whether to invoke the tool. Be specific: describe the tool's purpose, what arguments it accepts, and what it returns.
Transport	Required	`stdio` — Flusso launches a local subprocess on the server and communicates via stdin/stdout. `SSE` — Flusso connects to an HTTP endpoint that implements JSON-RPC over Server-Sent Events.
Command	Conditional (stdio)	The executable to run when launching the tool subprocess. For example `python`, `node`, or the full path to a binary. Only used when Transport is `stdio`.
Args	Conditional (stdio)	Space-separated arguments passed to the command. For example, if Command is `python` and Args is `tools/my_tool.py`, Flusso will run `python tools/my_tool.py`. Only used when Transport is `stdio`.
Environment	Optional (stdio)	Key-value environment variables to pass to the subprocess. Use this to provide API keys, configuration paths, or other settings the tool script needs. Entered as `KEY=value` pairs, one per line.
URL	Conditional (SSE)	The full HTTP endpoint URL for the MCP server, for example `https://my-tools-server.example.com/mcp`. Only used when Transport is `SSE`.
Headers	Optional (SSE)	Custom HTTP headers to send with each request to the MCP server. Commonly used to pass an API key for authentication, for example `Authorization: Bearer my-secret-key`. Entered as key-value pairs.

stdio vs SSE Transport

	stdio	SSE (HTTP)
How it works	Flusso spawns a subprocess on the server and communicates via standard input/output.	Flusso makes HTTP POST requests to a remote JSON-RPC server.
Best for	Local scripts, Python or Node.js tools you control, tools that need direct server access.	Remote tools, third-party MCP servers, cloud services, tools that need to scale independently.
Security	The subprocess runs with Flusso server permissions. Vet your scripts carefully.	Communication is over HTTP(S). Use HTTPS and authenticate with headers.
Latency	Low (local process).	Depends on network round-trip to the remote server.

Output Data

No direct output. The MCP Tool node itself does not produce output fields. When an agent calls a tool, the tool's return value is injected back into the agent's context automatically. The agent's final response (after any tool calls) is available as usual in agent.output.text and agent.output.tool_calls.

Example Usage

Connecting a web search tool to an agent

This example configures an MCP Tool that runs a Python script to perform a web search, and connects it to an agent that answers questions about current events.

Add an MCP Tool node from the AI & Agents sidebar. Set Name to search_web.
Write a clear description:
Search the web for up-to-date information about a topic. Use this tool when the user asks about recent events, current data, or anything that may have changed after the model's training cutoff. Input: a search query string. Returns: a list of results with titles, URLs, and snippets.
Set Transport to stdio. Set Command to python and Args to tools/web_search.py. Add the API key in Environment: SEARCH_API_KEY=your-key-here.
Draw an edge from the MCP Tool node to the tool_in (T) port on your Agent node.
Run the workflow. When the agent's prompt asks about current events, it will automatically call search_web, incorporate the results, and return a grounded answer.

Tips & Notes

Multiple tools per agent. You can connect as many MCP Tool nodes as you need to a single agent. There is no hard limit, but be mindful that a large number of tools increases the context consumed by the tool descriptions. Keep descriptions concise.
Security with stdio. When using stdio transport, the subprocess runs directly on the Flusso server with the same permissions as the application. Only run scripts you have written or fully reviewed. Do not pass user-supplied values directly into the command or args without sanitisation.
The agent controls tool invocation. You cannot force the agent to call a specific tool. The model decides based on the user prompt and the tool description. If an agent is not calling a tool you expect it to, review and improve the description.
Tool results are transparent in the run log. Every tool call and its result is recorded in the workflow's run detail view. You can inspect exactly what the agent sent to the tool and what came back.

Related Nodes

Agent — the node that calls tools at runtime.
Model Config — specifies the AI model for the agent in graph mode.
Memory — connects persistent memory to an agent in graph mode.