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
    description: "What it does"          # Shown to agents
    parameters:                          # List of parameter definitions
      - name: param_name
        type: string                     # Parameter type (see table below)
        required: true                   # or false
        description: "Parameter help"    # (optional) shown to agents
      - name: optional_param
        type: float
        default: 1.0                     # Default value if not provided
        description: "Help text"
    returns: "Description of return value"  # What the tool returns

Parameter Types

YAML Type	Aliases	Python Type	MATLAB Type
string	str	str	char / string
int	integer	int	int32, int64, etc.
float	number	float	double, single
bool	boolean	bool	logical
double	—	float	double
logical	—	bool	logical
list	—	list	cell, array
dict	—	dict	struct
any	—	Any	any type

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 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. The server reads the custom_tools.config_file path from config.yaml
2. load_custom_tools() parses the YAML file into CustomToolDef objects
3. Each tool definition is validated using Pydantic models:
   • CustomToolParam — validates each parameter (name, type, required, default, description)
   • CustomToolDef — validates the complete tool (name, matlab_function, description, parameters, returns)
4. For each valid tool, make_custom_tool_handler() creates an async handler function with:
   • Proper inspect.Signature for FastMCP introspection
   • Parameter type conversion (string → Python type → MATLAB argument)
   • MATLAB function invocation via the server state
5. The handler is registered as an MCP tool and appears in agent tool listings

Invalid tool definitions are logged as warnings and skipped; the server continues with remaining tools.

Multiple Tools Example

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 .mat signal file"
    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: logical
        default: false
        description: "Apply sharpening filter"
    returns: "Enhanced image saved to workspace"

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

Parameter Descriptions

Each parameter can include an optional description field. This text is shown to agents in tool documentation and helps them understand what each parameter should contain:

parameters:
  - name: input_file
    type: string
    required: true
    description: "Path to the input data file (supports .mat, .csv)"
  - name: threshold
    type: double
    default: 0.5
    description: "Detection threshold (0-1)"

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 too — just reference the function name without the extension
• Parameter descriptions: Add a description field to each parameter for better agent understanding
• Type aliases: Use double or logical to match MATLAB conventions; they map to float and bool respectively
• 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
• Validation: The server validates all parameters against the YAML schema before calling MATLAB