Custom Tools

Custom Tools

Expose your own MATLAB functions as first-class MCP tools. AI agents can discover and call them directly, with full parameter validation and help text.

How It Works

1. Write your MATLAB function (.m file)
2. Describe it in custom_tools.yaml
3. The server loads and registers it as an MCP tool at startup
4. Agents see it alongside built-in tools and can call it with validated parameters

Configuration

Point your config.yaml to the custom tools file:

custom_tools:
  config_file: "./custom_tools.yaml"

YAML Schema

tools:
  - name: tool_name                    # MCP tool name (what agents call)
    matlab_function: pkg.func          # MATLAB function to call (use pkg.func for packaged functions)
    description: "What it does"        # Shown to agents
    parameters:
      - name: param_name
        type: string                   # Parameter type (see table below)
        required: true                 # or false
        default: null                  # Default value if not provided
        description: "Parameter help"  # Optional: shown to agents
    returns: "Description of return value"

Parameter Types

YAML Type	Aliases	Python Type	Notes
string	str	str	Text parameter
int	integer	int	Integer parameter
float	number, double	float	Floating-point parameter
bool	boolean, logical	bool	Boolean parameter
list	—	list	Array/list parameter
dict	—	dict	Struct/dictionary parameter
any	—	Any	Any type (unvalidated)

Loading and Registration

Custom tools are loaded at server startup via the load_custom_tools() function:

1. The server reads the YAML file path from config.yaml
2. Each tool definition is validated against the CustomToolDef schema
3. For each valid tool, a handler function is created with make_custom_tool_handler()
4. The handler is registered as an MCP tool with FastMCP
5. Invalid definitions are logged as warnings but do not prevent startup

If the config file does not exist or contains no tools section, an empty list is returned and no custom tools are registered.

Complete Example

1. MATLAB Function (mylib/analyze_signal.m)

function result = analyze_signal(signal_path, sample_rate, window_size)
    % ANALYZE_SIGNAL  Frequency analysis of a signal file
    %
    %   result = analyze_signal(signal_path, sample_rate, window_size)
    %
    %   Returns struct with: frequencies, magnitudes, snr, peaks

    data = load(signal_path);
    signal = data.signal;

    N = length(signal);
    Y = fft(signal, window_size);
    f = (0:window_size/2-1) * sample_rate / window_size;
    mag = abs(Y(1:window_size/2)) / N;

    [peaks, locs] = findpeaks(mag, 'MinPeakHeight', max(mag)*0.1);

    result.frequencies = f;
    result.magnitudes = mag;
    result.snr = snr(signal);
    result.peaks = struct('frequencies', f(locs), 'amplitudes', peaks);
end

2. Custom Tool Definition (custom_tools.yaml)

tools:
  - name: analyze_signal
    matlab_function: mylib.analyze_signal
    description: >
      Analyze a signal file and return frequency components, SNR,
      and peak detection results.
    parameters:
      - name: signal_path
        type: string
        required: true
        description: "Path to the signal data file (.mat)"
      - name: sample_rate
        type: double
        required: true
        description: "Sample rate in Hz"
      - name: window_size
        type: int
        default: 1024
        description: "FFT window size"
    returns: "Struct with fields: frequencies, magnitudes, snr, peaks"

3. Make Sure MATLAB Can Find It

Add the directory containing your .m files to the workspace paths in config.yaml:

workspace:
  default_paths:
    - "/path/to/mylib"

4. Agent Usage

The agent now sees analyze_signal as a tool and can call it:

"Analyze the signal in data/recording.mat at 44100 Hz sample rate"

The server:

1. Validates parameters against the YAML schema
2. Calls mylib.analyze_signal('data/recording.mat', 44100, 1024) in MATLAB
3. Returns the result to the agent

Multiple Tools

tools:
  - name: analyze_signal
    matlab_function: mylib.analyze_signal
    description: "Frequency analysis of signal files"
    parameters:
      - name: signal_path
        type: string
        required: true
        description: "Path to the signal data file (.mat)"
    returns: "Frequency analysis struct"

  - name: train_model
    matlab_function: ml.train_classifier
    description: "Train a classification model"
    parameters:
      - name: dataset_path
        type: string
        required: true
        description: "Path to the training data (.mat or .csv)"
      - name: model_type
        type: string
        default: "svm"
        description: "Model type: svm, tree, knn, ensemble"
      - name: validation_split
        type: double
        default: 0.2
        description: "Fraction of data to use for validation (0-1)"
    returns: "Trained model and accuracy metrics"

  - name: process_image
    matlab_function: imgtools.enhance_image
    description: "Image enhancement pipeline"
    parameters:
      - name: image_path
        type: string
        required: true
        description: "Path to the input image"
      - name: denoise_strength
        type: double
        default: 0.5
        description: "Denoising strength (0=none, 1=maximum)"
      - name: sharpen
        type: logical
        default: false
        description: "Apply sharpening filter"
    returns: "Processed image saved to temp directory"

  - name: compute_statistics
    matlab_function: stats.compute_summary
    description: "Compute summary statistics for a .mat data file"
    parameters:
      - name: data_path
        type: string
        required: true
        description: "Path to the .mat file containing the data variable"
    returns: "Struct with mean, std, median, min, max, histogram data"

Handler Creation and Type Introspection

When a custom tool is registered, the server creates a typed async handler function using make_custom_tool_handler(). This factory:

1. Builds an inspect.Signature based on the parameter definitions
2. Creates an async coroutine with the correct signature
3. Registers it with FastMCP, which introspects the signature to understand parameter names and types
4. Validates incoming arguments before calling the MATLAB function

This ensures that agents receive accurate parameter information and requests are validated before reaching MATLAB.

Tips

• Function names with packages: Use pkg.func notation to call functions in MATLAB packages (e.g., +mylib/analyze_signal.m → mylib.analyze_signal)
• MEX files: Custom tools work with .mex files too — just reference the function name without the extension
• Parameter descriptions: Include description fields for parameters to help agents understand what each parameter does
• Type compatibility: The YAML types are converted to Python types for validation; ensure your MATLAB function accepts the corresponding types
• Error handling: If the MATLAB function throws an error, the MCP server returns a structured error response to the agent
• Testing: Test your functions in MATLAB first before exposing them as tools
• Default values: Use default to make parameters optional; if omitted, parameters are required