MCP tools

Agent commands. Your AI agent uses this node in workflows. You manage the MCP servers that provide these tools with pflow mcp commands.

MCP (Model Context Protocol) lets you extend pflow with external tools. When you add an MCP server, its tools become pflow nodes — same validation, same error handling, same template access as built-in nodes.

How it works

Add an MCP server with pflow mcp add — it discovers the server’s tools right away
Re-sync with pflow mcp sync after editing the config file or fixing a server that failed
Tools become nodes named mcp-{server}-{tool}
Agent uses them like any other node

# Add a GitHub MCP server
pflow mcp add github.mcp.json

# Tools are now available
pflow mcp list github
# mcp-github-create_issue
# mcp-github-list_repos
# mcp-github-search_code

Node naming

MCP tools become nodes with the pattern mcp-{server}-{tool}:

Server	Tool	Node name
github	create_issue	`mcp-github-create_issue`
slack	send_message	`mcp-slack-send_message`
filesystem	read_file	`mcp-filesystem-read_file`

Parameters

MCP node parameters come from the tool’s input schema. Each MCP server defines its own tools with their own parameters. pflow also adds two parameters to every MCP node. They control the call and are never sent to the server:

Parameter	Effect
`timeout`	Seconds before the tool call is abandoned (default: 30)
`result_format: json_block`	For tools that wrap JSON in prose, parse the single fenced JSON block in the text result and use it as `result`

To see a tool’s parameters:

pflow mcp describe mcp-github-create_issue

Output

All MCP nodes write to:

Key	Type	Description
`result`	any	Tool execution result
`error`	str	Error message (only on failure)

For dict results, read nested fields through result: If a tool returns {"issue_url": "...", "issue_number": 123}, use:

${github-issue.result.issue_url}
${github-issue.result.issue_number}

MCP nodes do not extract top-level result fields into ${node.field} and do not write a {server}_{tool}_result alias. Each workflow node already has its own namespace, so ${node.result} is the canonical success output.

Example workflow

### create_issue

Create a GitHub issue from the error summary.

- type: mcp-github-create_issue
- repository: myorg/myrepo
- title: "Bug: ${error_summary}"
- body: ${error_details}

### notify

Send a Slack notification with the issue link.

- type: mcp-slack-send_message
- channel: "#alerts"
- text: "Created issue: ${create_issue.result.issue_url}"

Code passed to a tool

Some tools take JavaScript to run: function of evaluate_script (chrome-devtools) and browser_evaluate (Playwright), initScript of navigate_page, and code of browser_run_code_unsafe. pflow sends that code exactly as written, so a ${...} inside it is JavaScript’s own template literal, not a template variable. A workflow value goes in as ${x|json}, which inserts it as a JavaScript value: a string arrives quoted and escaped ("Don't Stop"), a boolean as true, an object as an object literal.

### check-title

Compare the page title with the expected one.

- type: mcp-chrome-devtools-evaluate_script
- pageId: ${page_id}
- function: |
    () => {
      const expected = ${title|json};
      return { same: document.title === expected, label: `title: ${expected}` };
    }

Write the insert where a value goes, without quotes around it. Text that holds JSON, such as a shell stdout, arrives as a string: parse it with JSON.parse(${fetch.stdout|json}). $${...} is sent unchanged here too. |json is accepted only in these parameters, and validation points out a ${...} in the code that names a workflow value, with the |json form to use.

Setup

To use MCP tools, first add MCP servers to pflow. See Adding MCP servers for configuration format, authentication, and examples. pflow supports both local (stdio) and remote (HTTP) MCP servers. Both work identically in workflows - same naming, parameters, and output structure.

Server lifetime

Each run, and each pflow probe, connects to its MCP servers and disconnects at the end. A stdio server starts and stops with the run, so every run begins clean. That is the right default for a saved workflow, but anything the server holds in memory (an open browser page, a notebook kernel) is gone before the next call. State the server writes to disk, such as a browser profile, survives either way. When your agent needs to explore step by step across separate calls, keep one server process alive outside pflow. Run the stdio server behind mcp-proxy, which starts a single child and shares it with every connection, and register the proxy as an HTTP server:

# keep this running in its own process (another terminal, or backgrounded):
uvx --with 'mcp<2' mcp-proxy --port 8932 -- <server command>   # mcp<2: mcp-proxy 0.12 breaks on mcp 2.x
pflow mcp add '{"explore": {"type": "http", "url": "http://127.0.0.1:8932/mcp"}}'
# when done:
pflow mcp remove -f explore    # then stop the proxy process

A server’s own HTTP mode is not a substitute: it may drop its state when the last client disconnects, which happens at the end of every run. With @playwright/mcp, --port starts the next run at about:blank, while behind the proxy the open page, localStorage and session cookie carried across separate runs. Everything that uses the long-lived registration shares one server and its state, so confirm a finished workflow against the normal run-scoped registration.

Error handling

MCP nodes return error action on:

Connection failure: Server not reachable
Tool error: Tool reported an error (via isError flag)
Timeout: The call took longer than timeout seconds (default 30)

The node does not retry automatically - MCP calls start a server subprocess, and retries would cause resource conflicts.

When tools are synced

pflow mcp add discovers tools from the servers it adds. Running a workflow never contacts servers to discover tools — it uses the tools already in the registry. Run pflow mcp sync <server> (or --all) when:

pflow mcp add reported a server it could not reach (fix the token or start the server, then sync)
You edited ~/.pflow/mcp-servers.json by hand
A server added or changed its tools

CLI commands

Nodes

Configuration

Experimental

How it works

Node naming

Parameters

Output

Example workflow

Code passed to a tool

Setup

Server lifetime

Error handling

When tools are synced

​How it works

​Node naming

​Parameters

​Output

​Example workflow

​Code passed to a tool

​Setup

​Server lifetime

​Error handling

​When tools are synced

How it works

Node naming

Parameters

Output

Example workflow

Code passed to a tool

Setup

Server lifetime

Error handling

When tools are synced