pflow mcp

The pflow mcp command group manages Model Context Protocol (MCP) server connections. MCP servers expose external tools that can be used in pflow workflows.

Setup commands. You run add, remove, and sync to configure MCP servers. Your agent uses tools and info to discover available tools when building workflows.

Commands

Command	Description
`add`	Add MCP servers from config
`servers`	List configured servers
`remove`	Remove a server
`sync`	Discover and register tools
`tools`	List registered MCP tools
`info`	Show tool details
`serve`	Run pflow as an MCP server

pflow mcp add

Add MCP servers from config files or JSON, then discover their tools. A server that can’t be reached is still added; pflow prints its error and the pflow mcp sync <name> command to retry.

pflow mcp add <CONFIG_SOURCE>...

Arguments:

CONFIG_SOURCE - One or more config file paths or raw JSON strings

Examples:

# Add from config file
pflow mcp add ./github.mcp.json

# Add from raw JSON (simple format)
pflow mcp add '{"github": {"command": "npx", "args": ["-y", "@github/mcp-server"]}}'

# Add HTTP server
pflow mcp add '{"slack": {"type": "http", "url": "https://mcp.example.com/slack"}}'

# Add multiple servers
pflow mcp add github.mcp.json slack.mcp.json

Config formats: Simple format (recommended):

{
  "github": {
    "command": "npx",
    "args": ["-y", "@github/mcp-server"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Full MCP format (compatible with Claude Desktop):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"]
    }
  }
}

HTTP server format:

{
  "slack": {
    "type": "http",
    "url": "https://mcp.example.com/slack",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Environment variables in env and headers support ${VAR} and ${VAR:-default} syntax. They expand at runtime.

pflow mcp list

List all configured MCP servers.

pflow mcp servers [--json]

Options:

--json - Output as JSON

Output:

Configured MCP servers:

  github:
    Transport: stdio
    Command: npx -y @github/mcp-server
    Environment: GITHUB_TOKEN=${GITHUB_TOKEN}

  slack:
    Transport: http
    URL: https://mcp.example.com/slack

pflow mcp remove

Remove an MCP server configuration.

pflow mcp remove <NAME> [--force]

Arguments:

NAME - Server name to remove

Options:

--force, -f - Skip confirmation prompt

Examples:

# Remove with confirmation
pflow mcp remove github

# Remove without confirmation
pflow mcp remove github --force

Removing a server also removes all its tools from the registry.

pflow mcp sync

Discover and register tools from MCP servers.

pflow mcp sync [NAME] [--all]

Arguments:

NAME - Server name to sync (conflicts with --all)

Options:

--all, -a - Sync all configured servers

Examples:

# Sync specific server
pflow mcp sync github

# Sync all servers
pflow mcp sync --all

Output:

Syncing server 'github'...
✓ Discovered 15 tools
✓ Registered 15 tools in pflow registry

Registered tools:
  - mcp-github-create-issue
  - mcp-github-list-issues
  - mcp-github-get-issue
  ... and 12 more

pflow mcp add syncs the servers it adds, and workflow runs never sync. Run pflow mcp sync after editing mcp-servers.json by hand, or to retry a server that failed during add.

pflow mcp list

List registered MCP tools.

pflow mcp list [SERVER] [--json]

Arguments:

SERVER - Filter by server name (optional)

Options:

--json - Output as JSON

Examples:

# List all MCP tools
pflow mcp list

# List tools from specific server
pflow mcp list github

# JSON output
pflow mcp list --json

Output:

Registered MCP tools:

  github (15 tools):
    - mcp-github-create-issue: Create a new issue
    - mcp-github-list-issues: List repository issues
    - mcp-github-get-issue: Get issue details
    ...

  slack (8 tools):
    - mcp-slack-send-message: Send a message
    - mcp-slack-list-channels: List channels
    ...

pflow mcp describe

Show detailed information about an MCP tool.

pflow mcp describe <TOOL>

Arguments:

TOOL - Tool name to inspect

Example:

pflow mcp describe mcp-forms-fill

Output:

Tool: mcp-forms-fill
Server: forms
Tool Name: fill
Description: Fill form fields.
Module: pflow.nodes.mcp.node
Class: MCPNode

Parameters:
  - fields: list[dict] (required)
      - name: str (required)
      - value: str (required)
  - mode: str (default: draft) (one of: draft, submit)
  - timeout: int - Timeout in seconds for tool execution (default: 30)
  - result_format: str - Set to json_block to parse the single fenced ```json block of a text result as `result` (error on zero or several blocks)

Outputs:
  - result: any - Tool execution result

Usage in .pflow.md:

    ### step-name

    Describe what this step does and why.

    - type: mcp-forms-fill
    - fields: value

An object parameter, or a list of objects, lists its fields indented beneath it. The usage snippet sets only the required parameters; the rest keep their defaults. Run pflow mcp sync --all after upgrading pflow so tools registered earlier pick up the current parameter types.

pflow mcp serve

Run pflow as an MCP server for AI tools.

pflow mcp serve [--debug]

Options:

--debug - Enable debug logging

This command starts pflow as an MCP server using stdio transport. AI tools connect to pflow and can use its workflow capabilities.

This is typically invoked by AI tools automatically, not run directly. See the integrations guide for setup instructions.

Exposed tools: The MCP server exposes tools for:

Discovering workflows and nodes
Running workflows
Validating workflows
Saving workflows to the library
Managing settings

Tool naming convention

MCP tools are registered with the pattern mcp-{server}-{tool}:

Format	Example
Full	`mcp-github-create-issue`
Server-qualified	`github-create-issue`
Short (if unique)	`create-issue`

Agents can use the shortest unambiguous name in workflows.

Using MCP tools in workflows

After syncing, MCP tools work like any other node:

### create-issue

Create a bug report issue on GitHub.

- type: mcp-github-create-issue
- repo: owner/repo
- title: Bug report
- body: Description of the bug

File locations

Path	Purpose
`~/.pflow/mcp-servers.json`	Server configurations
`~/.pflow/registry.json`	Registered tools

Common workflows

Initial setup

# Add servers
pflow mcp add github.mcp.json

# Sync to discover tools
pflow mcp sync --all

# Verify tools
pflow mcp list

Troubleshooting

# Check configured servers
+pflow mcp servers

# Resync a server
pflow mcp sync github

# Get tool details
pflow mcp describe mcp-github-create-issue

Adding MCP servers guide - Detailed setup guide
CLI overview - Main pflow command
MCP node reference - Using MCP tools in workflows

CLI commands

Nodes

Configuration

Experimental

Commands

pflow mcp add

pflow mcp list

pflow mcp remove

pflow mcp sync

pflow mcp list

pflow mcp describe

pflow mcp serve

Tool naming convention

Using MCP tools in workflows

File locations

Common workflows

Initial setup

Troubleshooting

​Commands

​pflow mcp add

​pflow mcp list

​pflow mcp remove

​pflow mcp sync

​pflow mcp list

​pflow mcp describe

​pflow mcp serve

​Tool naming convention

​Using MCP tools in workflows

​File locations

​Common workflows

​Initial setup

​Troubleshooting

​Related

Commands

pflow mcp add

pflow mcp list

pflow mcp remove

pflow mcp sync

pflow mcp list

pflow mcp describe

pflow mcp serve

Tool naming convention

Using MCP tools in workflows

File locations

Common workflows

Initial setup

Troubleshooting

Related