MCP Client Integration in FlowMattic

FlowMattic’s MCP Client allows you to connect to any external Model Context Protocol (MCP) server and execute its tools — either as a direct workflow step or as an AI Agent tool. This turns FlowMattic into a universal MCP client that can interact with thousands of MCP-compatible services.

How the MCP Client Works

The MCP Client uses the Streamable HTTP transport protocol to communicate with MCP servers:

1. You provide the MCP server’s endpoint URL and optional authentication.
2. FlowMattic sends a tools/list request to discover available tools on the server.
3. You select a tool and configure its parameters (or let the AI Agent choose dynamically).
4. FlowMattic sends a tools/call request to execute the selected tool.
5. The server processes the request and returns the result.

The client supports session management via Mcp-Session-Id headers, automatic reconnection, and configurable timeouts.

Two Usage Contexts

The MCP Client works in two different contexts depending on where you use it:

Setting Up the MCP Client

Basic Configuration

Every MCP Client configuration requires:

1. Endpoint URL — The MCP server’s Streamable HTTP endpoint (e.g., https://your-server.com/mcp)
2. Authentication — Choose from None, Bearer Token, API Key, or Custom Headers
3. Tool Selection — Pick a specific tool (workflow step) or configure tool filtering (AI Agent)
4. Timeout — Connection timeout in seconds (default: 60)

Authentication Methods

Tip: You can use dynamic tags in auth fields to pull tokens from previous workflow steps, stored options, or environment variables.

Using MCP Client as an AI Agent Tool

When added as a tool inside an AI Agent, the MCP Client expands into individual tools that the AI can call autonomously.

Configuration

1. Open your AI Agent in the Visual Workflow Builder.
2. Add a new tool and select MCP Client > Execute Tool.
3. Enter the MCP server Endpoint URL.
4. Configure Authentication if required.
5. Set the Tools to Include mode:

6. For Selected or Except modes:
   • Click Fetch & Select Tools to load the tool list from the server.
   • Use the search box to filter tools by name or description.
   • Check/uncheck tools as needed.
7. Click Continue and then Save & Close.

How It Works at Runtime

When the AI Agent executes:

1. FlowMattic connects to the MCP server and fetches the tool list.
2. Based on your tools mode, it filters the available tools.
3. Each MCP tool is converted into a function the AI model can call (with name, description, and input schema).
4. The AI decides which tool(s) to call and provides the required parameters.
5. FlowMattic executes the tool call against the MCP server and returns the result to the AI.
6. The AI can chain multiple tool calls across iterations.

Note: MCP tools are expanded alongside any other tools configured in the AI Agent. The AI can use both MCP tools and regular FlowMattic tools in the same conversation.

Token Usage Optimization

MCP servers can expose tools with large input schemas. FlowMattic automatically optimizes tool schemas to reduce token usage by:

• Stripping non-essential metadata fields ($schema, title, examples, default, pattern, format)
• Truncating tool descriptions to 200 characters
• Collapsing deeply nested schemas (beyond 3 levels)

Using MCP Client as a Workflow Step

When used as a regular workflow step, you select a single tool and configure its parameters manually.

Configuration

1. Add a new action step in your workflow.
2. Select MCP Client > Execute Tool.
3. Enter the MCP server Endpoint URL.
4. Configure Authentication if required.
5. Click the refresh button next to the Tool dropdown to fetch available tools.
6. Select the tool you want to execute.
7. Fill in the Tool Parameters that appear based on the tool’s input schema.
8. Set the Timeout value if needed.

Parameter Types

Parameters are dynamically generated based on the selected tool’s inputSchema:

Tip: Use dynamic tags (the + button) to insert values from previous workflow steps into tool parameters.

Response Data

The MCP Client returns the tool’s response as structured data that can be used in subsequent workflow steps via dynamic tags. The response typically includes:

• content — Array of content blocks (text, images, resources)
• isError — Whether the tool execution resulted in an error

Connecting to Popular MCP Servers

FlowMattic MCP Server

Connect one FlowMattic site to another’s MCP server:

Endpoint URL: https://your-site.com/wp-json/flowmattic/v1/mcp-server/{server-id}
Auth: Bearer Token or API Key (as configured on the server)

GitHub MCP Server

Endpoint URL: https://api.githubcopilot.com/mcp/
Auth: Bearer Token (GitHub Personal Access Token)

Zapier MCP Server

Endpoint URL: https://actions.zapier.com/mcp/{your-id}/sse
Auth: Bearer Token (Zapier API Key)

Important: Each MCP server has its own endpoint format and authentication requirements. Refer to the server’s documentation for the correct configuration.

Troubleshooting

Common Issues

“Failed to connect to MCP server”

• Verify the endpoint URL is correct and accessible from your WordPress server.
• Check that your server can make outbound HTTPS requests.
• Ensure the MCP server is running and responding.

“Failed to fetch tools” / Empty tool list

• The MCP server may require authentication. Check your auth configuration.
• The server might not support tools/list. Verify it implements the MCP protocol.
• Check the timeout value — some servers need more time to respond.

“Tool execution failed”

• Verify the parameters match the tool’s expected input schema.
• Check that your authentication token has the required permissions.
• Review the MCP server’s logs for detailed error messages.

AI Agent not using MCP tools

• Ensure the tools mode is set correctly (not “All Tools” with an unreachable server).
• Check that the endpoint URL and auth are configured in the tool settings.
• Verify the MCP server is accessible at the time of AI Agent execution.

High token usage with MCP tools

• Use Selected Tools Only mode to limit the number of tools exposed to the AI.
• MCP servers with many tools (30+) will increase prompt token usage for tool definitions.
• Tool response data from MCP servers contributes to completion tokens — large responses (e.g., full contact lists) will use more tokens.

Summary