Connecting an MCP server

MCP (Model Context Protocol) is a way of handing a model a set of tools over the network. In Flow it shows up in two opposite directions, and they are constantly mixed up because they are called the same thing.

Step one: a connection, not a node

The server address and the token are stored in a workspace integration; the node remembers only its id. The reason is the same for every integration and is spelled out in the overview: a secret must not sit in a graph that gets exported and shown around.

“As tool” mode: the whole server goes to the agent

The default. The node shows a single tool_out port, which you drag into the extensions port of ai_agent with a link_extension wire — exactly like any other agent tool.

An important detail: in this mode the model receives all the tools the server declares, not one selected tool. There is no “which ones to enable” list in the form. The Tool name field is optional here and only names a default tool for single-tool calls. To narrow the set, either run a server that exposes only what you need, or use executable mode and call one tool as an explicit step.

The server hands over its tool list while the run is being prepared, once. A tool that appears on the server mid-turn will not appear in that turn.

“Executable” mode: one tool as a graph step

Here the node becomes an ordinary step: it grows a run input and a success output, and the decision is yours rather than the model’s. Exactly one connection field becomes required — Tool name: without it the connection will not save in this mode. Tool arguments (JSON) (a JSON object of arguments) stays optional: left empty, it means a call with an empty argument set.

What the node passes on:

The error branch is on by default in this mode — for the same reason as on http_request: a remote server that may not answer is an expected outcome, not a broken workflow. The author of the run does see the MCP server’s own error text: the server is theirs, and its words are the diagnosis. It is not shown to the person in the chat.

When the server is unreachable

The two modes behave differently, and the difference matters.

The second case is the nastiest kind of failure: nothing broke, everything “works”, the bot just stopped being able to do the thing you built it for. The platform deliberately does not kill a turn over an unavailable extension — otherwise one wedged third-party server would break every conversation. But you need to know about it, so:

• if an MCP tool is critical to the scenario, use executable mode with an explicit error branch; silent degradation then becomes impossible;
• check what actually arrived: in Executions the agent node shows which tools it called;
• the server must be publicly reachable. Outbound requests are refused when the address falls into a private range — an MCP server on localhost or on a local network is unreachable. This is the same guard described in HTTP and the web.

What next