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

Each tool definition in custom_tools.yaml must include:

tools:
  - name: tool_name                      # MCP tool name (what agents call)
    matlab_function: pkg.func            # MATLAB function reference (e.g., mylib.analyze_signal)
    description: "What it does"          # Shown to agents in tool discovery
    parameters:                          # List of parameters
      - name: param_name
        type: string                     # Parameter type (see table below)
        required: true                   # or false
        description: "Parameter help text"
      - name: optional_param
        type: double
        default: 1.0                     # Default value if not provided
        description: "Optional parameter"
    returns: "Description of return value"

Parameter Types

YAML Type	Aliases	Python Type	Notes
string	str	str	Text parameters
double	float, number	float	Floating-point numbers
int	integer	int	Integer values
bool	boolean, logical	bool	Boolean flags
list	—	list	Array/list parameters
dict	—	dict	Structured data
any	—	Any	Any type (use sparingly)

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:
    - "./mylib"
    - "/path/to/other/toolbox"

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 analyze_signal('data/recording.mat', 44100, 1024) in MATLAB
3. Returns the result to the agent

Loading and Registration

Custom tools are loaded at server startup:

1. Parse YAML: The server reads custom_tools.yaml and validates each tool definition using Pydantic models (CustomToolDef, CustomToolParam)
2. Build handlers: For each valid tool, a typed async handler function is created with a proper inspect.Signature
3. Register with FastMCP: Each handler is registered as an MCP tool, making it discoverable by agents
4. Parameter validation: When an agent calls the tool, FastMCP validates parameters against the declared types before passing to the MATLAB function

If a tool definition is invalid (missing required fields, invalid types), a warning is logged and that tool is skipped.

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 signal 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 training data"
      - name: model_type
        type: string
        default: "svm"
        description: "Model type: svm, tree, knn, ensemble"
      - name: validation_split
        type: double
        default: 0.2
        description: "Validation data fraction (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 input image"
      - name: denoise_strength
        type: double
        default: 0.5
        description: "Denoising strength (0=none, 1=maximum)"
      - name: sharpen
        type: bool
        default: false
        description: "Apply sharpening filter"
    returns: "Enhanced image path"

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

Tips

• Package notation: 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 — just reference the function name without the extension
• Type consistency: Use double instead of float for MATLAB compatibility; both are supported
• Descriptions: Include parameter descriptions so agents understand what each input does
• 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
• Return values: MATLAB structs are automatically converted to JSON-serializable dicts for the agent