FlowMattic MCP Server: Developer Integration Guide - Add custom tools to MCP Server

Overview

The FlowMattic MCP (Model Context Protocol) Server provides a powerful way for plugin developers, theme developers, and website developers to integrate their custom functions directly into MCP clients like Claude Desktop, without building an MCP server from scratch.

What is FlowMattic MCP Server?

FlowMattic MCP Server acts as a bridge between your custom WordPress functions and MCP clients. Instead of developing a complete MCP server infrastructure, developers can simply hook their functions into FlowMattic’s existing MCP server using a simple PHP API.

Key Benefits

• Zero MCP Server Development: No need to build MCP server infrastructure
• Automatic Tool Registration: Your tools automatically appear in MCP clients
• Admin Interface: Tools are listed on the FlowMattic MCP server admin page
• Execution History: Track tool usage and performance
• Simple Integration: Just a few lines of PHP code

How It Works

1. Hook Your Functions: Use FlowMattic’s API to register your custom functions
2. Automatic Discovery: FlowMattic lists your tools to connected MCP clients
3. Seamless Execution: FlowMattic handles all MCP communication and function execution
4. Response Handling: Your function responses are automatically formatted for MCP clients

Getting Started

Prerequisites

• WordPress website
• FlowMattic plugin installed and activated
• Basic PHP knowledge

Basic Integration

To add custom tools to FlowMattic MCP Server, use the flowmattic_add_mcp_tools() function:

if ( function_exists('flowmattic_add_mcp_tools') ) {
    $tools = array();
    
    // Define your tools here
    
    flowmattic_add_mcp_tools( 'Your Plugin Name', $tools );
}

Function Structure

Tool Definition Array

Each tool requires the following structure:

array(
    'name'          => 'Tool Display Name',
    'description'   => 'What this tool does',
    'function_name' => 'your_php_function_name',
    'parameters'    => array(
        'param1',
        'param2',
        // ... more parameters
    ),
    'request_type'  => 'array', // Optional: 'array' or omit for individual parameters
)

Complete Examples

Example 1: Simple User Lookup Tool

This example shows how to create a tool that retrieves WordPress user data by ID:

/**
 * Function to get user by ID and return user data.
 *
 * @param int $user_id The WordPress user ID.
 * @return array The user data or an error message if the user does not exist.
 */
function my_plugin_get_user_by_id( $user_id ) {
    // Get user
    $user = get_userdata( $user_id );

    // Check if user exists - Example of error reporting to MCP tool
    if ( ! $user ) {
        return array(
            'error' => 'User not found.',
        );
    }

    // Get the user data
    $user_data = (array) $user->data;
    $user_fields = array();

    foreach ( $user_data as $key => $value ) {
        // Skip empty values
        if ( empty( $value ) ) {
            continue;
        }
        $user_fields[ $key ] = $value;
    }

    // Return user fields - can be string or array
    return $user_fields;
}

// Register the tool
if ( function_exists('flowmattic_add_mcp_tools') ) {
    $tools = array();
    
    $tools[] = array(
        'name'          => 'Get User by ID',
        'description'   => 'Retrieve a user profile details by their WordPress user ID.',
        'function_name' => 'my_plugin_get_user_by_id',
        'parameters'    => array(
            'user_id',
        ),
    );

    flowmattic_add_mcp_tools( 'User Management Plugin', $tools );
}

Example 2: Array-Based Input Tool

This example demonstrates handling multiple parameters as an array:

/**
 * Generate dummy data based on received input array.
 *
 * @param array $input_array The input associative array with some data.
 * @return array The dummy data response, enhanced or modified.
 */
function generate_dummy_data( $input_array ) {
    if ( ! is_array( $input_array ) ) {
        return array(
            'error' => 'Invalid input. Expected an array.',
        );
    }

    $dummy_data = array(
        'name'    => isset( $input_array['name'] ) ? $input_array['name'] : 'John Doe',
        'email'   => isset( $input_array['email'] ) ? $input_array['email'] : '[email protected]',
        'age'     => isset( $input_array['age'] ) ? $input_array['age'] : 30,
        'address' => isset( $input_array['address'] ) ? $input_array['address'] : '123 Main St, Anytown, USA',
        'phone'   => isset( $input_array['phone'] ) ? $input_array['phone'] : '123-456-7890',
        'notes'   => isset( $input_array['notes'] ) ? $input_array['notes'] : 'No additional notes provided.',
    );

    return $dummy_data;
}

// Register the tool with array request type
if ( function_exists('flowmattic_add_mcp_tools') ) {
    $tools = array();
    
    $tools[] = array(
        'name'          => 'Generate Dummy Data',
        'description'   => 'Generate dummy data based on the provided associative array.',
        'function_name' => 'generate_dummy_data',
        'parameters'    => array(
            'name',
            'email',
            'age',
            'address',
        ),
        'request_type'  => 'array', // Parameters passed as array to function
    );

    flowmattic_add_mcp_tools( 'Data Generator Plugin', $tools );
}

Example 3: Database Query Tool

This example shows a more complex tool that queries the database:

/**
 * Search posts by keyword in title or content.
 *
 * @param string $keyword The search keyword.
 * @param string $post_type The post type to search (optional).
 * @return array Search results or error message.
 */
function search_posts_by_keyword( $keyword, $post_type = 'post' ) {
    if ( empty( $keyword ) ) {
        return array(
            'error' => 'Keyword parameter is required.',
        );
    }

    $args = array(
        's'         => sanitize_text_field( $keyword ),
        'post_type' => sanitize_text_field( $post_type ),
        'posts_per_page' => 10,
        'post_status' => 'publish',
    );

    $query = new WP_Query( $args );
    
    if ( ! $query->have_posts() ) {
        return array(
            'message' => 'No posts found matching your search criteria.',
            'results' => array(),
        );
    }

    $results = array();
    while ( $query->have_posts() ) {
        $query->the_post();
        $results[] = array(
            'id'      => get_the_ID(),
            'title'   => get_the_title(),
            'excerpt' => get_the_excerpt(),
            'url'     => get_permalink(),
            'date'    => get_the_date(),
        );
    }
    wp_reset_postdata();

    return array(
        'message' => sprintf( 'Found %d posts matching "%s"', count( $results ), $keyword ),
        'results' => $results,
    );
}

// Register the search tool
if ( function_exists('flowmattic_add_mcp_tools') ) {
    $tools = array();
    
    $tools[] = array(
        'name'          => 'Search Posts',
        'description'   => 'Search for posts by keyword in title or content.',
        'function_name' => 'search_posts_by_keyword',
        'parameters'    => array(
            'keyword',
            'post_type',
        ),
    );

    flowmattic_add_mcp_tools( 'Content Search Plugin', $tools );
}

Parameter Handling

Individual Parameters (Default)

When request_type is not specified, FlowMattic passes parameters individually:

// MCP Client sends: {"keyword": "wordpress", "post_type": "page"}
// Your function receives: search_posts_by_keyword( "wordpress", "page" )

Array Parameters

When request_type is set to "array", all parameters are passed as a single array:

// MCP Client sends: {"name": "John", "email": "[email protected]"}
// Your function receives: generate_dummy_data( array( "name" => "John", "email" => "[email protected]" ) )

Error Handling

Always include proper error handling in your functions:

function my_custom_function( $param ) {
    // Validate input
    if ( empty( $param ) ) {
        return array(
            'error' => 'Parameter is required.',
        );
    }

    // Validate data types
    if ( ! is_numeric( $param ) ) {
        return array(
            'error' => 'Parameter must be a number.',
        );
    }

    // Your logic here...
    
    return $result;
}

Response Formats

Your functions can return:

• String: Simple text response
• Array: Structured data (recommended)
• Error Array: array( 'error' => 'Error message' )

Tool Execution History

FlowMattic automatically tracks:

• When each tool was executed
• What parameters were passed
• Function responses
• Execution time
• Success/error status

This history is available in the FlowMattic MCP server admin interface.

Best Practices

Security

• Always sanitize input parameters
• Use WordPress nonces for sensitive operations
• Validate user permissions when necessary

function secure_user_function( $user_id ) {
    // Sanitize input
    $user_id = absint( $user_id );
    
    // Check permissions
    if ( ! current_user_can( 'manage_users' ) ) {
        return array( 'error' => 'Insufficient permissions.' );
    }
    
    // Your logic here...
}

Performance

• Limit database queries
• Use WordPress caching when appropriate
• Set reasonable limits on returned data

function get_recent_posts( $limit = 10 ) {
    // Limit the number of results
    $limit = min( absint( $limit ), 50 ); // Maximum 50 posts
    
    // Use WordPress query optimization
    $args = array(
        'posts_per_page' => $limit,
        'no_found_rows'  => true,
        'fields'         => 'ids', // Only get IDs if that's all you need
    );
    
    return get_posts( $args );
}

Documentation

• Use clear, descriptive function names
• Write comprehensive descriptions for each tool
• Include parameter documentation in your functions

Multiple Tools Registration

You can register multiple tools at once:

if ( function_exists('flowmattic_add_mcp_tools') ) {
    $tools = array();
    
    // Tool 1: Get user data
    $tools[] = array(
        'name'          => 'Get User Data',
        'description'   => 'Retrieve user information by ID.',
        'function_name' => 'get_user_data',
        'parameters'    => array( 'user_id' ),
    );
    
    // Tool 2: Update user meta
    $tools[] = array(
        'name'          => 'Update User Meta',
        'description'   => 'Update user metadata fields.',
        'function_name' => 'update_user_meta_data',
        'parameters'    => array( 'user_id', 'meta_key', 'meta_value' ),
    );
    
    // Tool 3: Search content
    $tools[] = array(
        'name'          => 'Search Content',
        'description'   => 'Search posts and pages by keyword.',
        'function_name' => 'search_site_content',
        'parameters'    => array( 'keyword', 'post_types' ),
        'request_type'  => 'array',
    );

    // Register all tools under your plugin name
    flowmattic_add_mcp_tools( 'My Awesome Plugin', $tools );
}

Troubleshooting

Common Issues

1. Tool not appearing: Ensure FlowMattic is installed and flowmattic_add_mcp_tools() function exists
2. Function not executing: Check function name matches exactly in the tool definition
3. Parameter errors: Verify parameter names and types match your function signature
4. Permission errors: Ensure proper WordPress capabilities are checked

Debug Tips

• Use WordPress error logs to debug function execution
• Test functions independently before registering as MCP tools
• Check FlowMattic admin interface for execution history and errors

Conclusion

The FlowMattic MCP Server makes it incredibly easy to expose your custom WordPress functionality to MCP clients. With just a few lines of code, you can create powerful tools that integrate seamlessly with AI assistants and other MCP-compatible applications.

Remember to follow WordPress coding standards, implement proper security measures, and thoroughly test your tools before deployment.