MCP Tools Reference

The server exposes 20 built-in tools plus any custom tools defined in your custom_tools.yaml.

Execution & Workspace

`execute_code`

Execute MATLAB code in the session's engine.

Parameter	Type	Required	Description
`code`	string	yes	MATLAB code to execute

Behavior:

Runs asynchronously and returns a job_id for tracking
Returns a result dict with status, job_id, output, variables, etc.
Use get_job_status to monitor progress and get_job_result to retrieve the final result

Example response:

{
  "status": "running",
  "job_id": "abc123-def456",
  "message": "Code execution started"
}

`check_code`

Lint MATLAB code using checkcode/mlint.

Parameter	Type	Required	Description
`code`	string	yes	MATLAB code to check

Behavior:

Writes the code to a temporary file and runs mcp_checkcode() on it
Returns a list of issues with line, column, message, and severity

Example response:

{
  "issues": [
    {
      "line": 3,
      "column": 5,
      "message": "Variable 'x' might be unused",
      "severity": "warning"
    },
    {
      "line": 7,
      "column": 10,
      "message": "Missing semicolon",
      "severity": "info"
    }
  ],
  "summary": "1 warning(s), 1 info(s)"
}

`get_workspace`

Get variables in the current MATLAB workspace.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Runs whos in MATLAB and returns workspace variable information
Includes variable names, sizes, bytes, and class types

Example response:

{
  "variables": [
    {
      "name": "x",
      "size": "1x100",
      "bytes": 800,
      "class": "double"
    },
    {
      "name": "data",
      "size": "10x10",
      "bytes": 800,
      "class": "double"
    }
  ],
  "total_bytes": 1600
}

Job Management

`get_job_status`

Get the status and progress of a MATLAB execution job.

Parameter	Type	Required	Description
`job_id`	string	yes	Job ID from `execute_code`

Behavior:

Returns status, timing info, and optional progress for running jobs
Progress is read from a .progress file if the job supports it
Useful for long-running computations

Example response:

{
  "job_id": "abc123-def456",
  "status": "running",
  "progress": 65.0,
  "message": "Processing trial 650000/1000000",
  "elapsed_seconds": 120.5,
  "started_at": "2024-01-15T10:30:00Z"
}

`get_job_result`

Get the full result of a completed MATLAB execution job.

Parameter	Type	Required	Description
`job_id`	string	yes	Job ID

Behavior:

Returns the complete result dict for completed jobs
Returns the error dict and error message for failed jobs
Only available after the job has finished executing

Example response (success):

{
  "status": "completed",
  "job_id": "abc123-def456",
  "output": "ans =\n    1250000",
  "execution_time": 245.32,
  "variables": {
    "result": "1x1 double"
  }
}

Example response (failure):

{
  "status": "failed",
  "job_id": "abc123-def456",
  "error": "Undefined function or variable 'undefined_var'",
  "execution_time": 2.15
}

`cancel_job`

Cancel a pending or running MATLAB execution job.

Parameter	Type	Required	Description
`job_id`	string	yes	Job ID

Behavior:

Attempts to cancel the underlying MATLAB future
Marks the job as cancelled in the job tracker
Returns success or error status

Example response:

{
  "job_id": "abc123-def456",
  "status": "cancelled",
  "message": "Job cancelled successfully"
}

`list_jobs`

List all jobs for the current session.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Returns a list of job summaries including status and timing
Includes all jobs (running, completed, failed, cancelled)

Example response:

{
  "jobs": [
    {
      "job_id": "abc123-def456",
      "status": "running",
      "elapsed_seconds": 120.5,
      "started_at": "2024-01-15T10:30:00Z"
    },
    {
      "job_id": "xyz789-uvw456",
      "status": "completed",
      "elapsed_seconds": 45.2,
      "started_at": "2024-01-15T10:20:00Z",
      "completed_at": "2024-01-15T10:20:45Z"
    }
  ],
  "total_count": 2
}

Discovery

`list_toolboxes`

List available MATLAB toolboxes.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Runs ver in MATLAB and returns the output
Includes toolbox names, versions, and configuration info
Shows only toolboxes available in your MATLAB installation

Example response:

{
  "toolboxes": [
    {
      "name": "MATLAB",
      "version": "R2023b"
    },
    {
      "name": "Signal Processing Toolbox",
      "version": "9.1"
    },
    {
      "name": "Statistics and Machine Learning Toolbox",
      "version": "12.4"
    }
  ],
  "matlab_version": "R2023b"
}

`list_functions`

List functions in a MATLAB toolbox.

Parameter	Type	Required	Description
`toolbox_name`	string	yes	Name of the toolbox

Behavior:

Runs help <toolbox_name> in MATLAB and returns the output
Returns function categories and function names for the specified toolbox

Example response:

{
  "toolbox_name": "Signal Processing Toolbox",
  "output": "Signal Processing Toolbox\n\nSignal analysis.\n  butter      - Butterworth analog and digital filter design\n  fft         - Fast Fourier transform\n  filter      - 1-D digital filter\n  ...\n",
  "status": "success"
}

`get_help`

Get MATLAB help text for any function.

Parameter	Type	Required	Description
`function_name`	string	yes	Name of the MATLAB function

Behavior:

Runs help <function_name> in MATLAB and returns the documentation
Returns the full help text including syntax, description, and examples

Example response:

{
  "function_name": "fft",
  "help_text": "fft Fast Fourier transform\n\n   Y = fft(X) computes the discrete Fourier transform of X.\n   If X is a matrix, fft computes the FFT of each column of X.\n   ...\n",
  "status": "success"
}

File Operations

`upload_data`

Upload a data file to the session's temporary directory.

Parameter	Type	Required	Description
`filename`	string	yes	Name of the file to create
`content_base64`	string	yes	Base64-encoded file content

Behavior:

Decodes the base64 content and writes it to the session temp directory
The file can then be accessed from MATLAB code using the temp directory path
Useful for uploading CSV, JSON, MAT, or other data files

Example response:

{
  "filename": "data.csv",
  "path": "/tmp/matlab_session_abc123/data.csv",
  "size_bytes": 2048,
  "status": "uploaded"
}

`delete_file`

Delete a file from the session's temporary directory.

Parameter	Type	Required	Description
`filename`	string	yes	Name of the file to delete

Behavior:

Only files in the session temp directory can be deleted
Returns success or error if file doesn't exist

Example response:

{
  "filename": "data.csv",
  "status": "deleted",
  "message": "File deleted successfully"
}

`list_files`

List files in the session's temporary directory.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Returns names, sizes, and paths for all files in the session temp directory
Includes both uploaded and generated files

Example response:

{
  "files": [
    {
      "name": "data.csv",
      "size_bytes": 2048,
      "path": "/tmp/matlab_session_abc123/data.csv",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "name": "results.mat",
      "size_bytes": 4096,
      "path": "/tmp/matlab_session_abc123/results.mat",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "total_files": 2
}

`read_script`

Read a MATLAB .m script file from the session's temporary directory.

Parameter	Type	Required	Description
`filename`	string	yes	Name of the .m script file

Behavior:

Returns the file content as plain text
Use list_files to see available scripts

Example response:

{
  "filename": "analysis.m",
  "content": "% Perform data analysis\ndata = readtable('data.csv');\nresults = mean(data{:,:});\ndisp(results);\n",
  "status": "success"
}

`read_data`

Read a data file from the session's temporary directory.

Parameter	Type	Required	Description
`filename`	string	yes	Name of the data file (.mat, .csv, .json, .txt, .xlsx)
`format`	string	no	Read mode: `summary` (default) or `raw`

Behavior:

For .mat files in summary mode: shows variable names, sizes, and types via MATLAB
For .mat files in raw mode: returns base64-encoded content
For text files (.csv, .json, .txt): returns inline content
For .xlsx files: returns sheet information or raw content

Example response (summary mode for .mat):

{
  "filename": "results.mat",
  "format": "summary",
  "variables": [
    {
      "name": "x",
      "size": "1x1000",
      "class": "double",
      "bytes": 8000
    },
    {
      "name": "metadata",
      "size": "1x1",
      "class": "struct",
      "bytes": 512
    }
  ],
  "status": "success"
}

Example response (raw mode for .mat):

{
  "filename": "results.mat",
  "format": "raw",
  "content_base64": "TUFUIzUuMDA7c2F2ZWQgaW4gTUFUTEFCIDkuMTM...",
  "size_bytes": 4096,
  "status": "success"
}

Example response (text file):

{
  "filename": "data.csv",
  "format": "text",
  "content": "x,y,z\n1,2,3\n4,5,6\n7,8,9\n",
  "status": "success"
}

`read_image`

Read an image file from the session's temporary directory.

Parameter	Type	Required	Description
`filename`	string	yes	Name of the image file (.png, .jpg, .gif)

Behavior:

Returns the image as an inline content block that renders in agent UIs
Supports PNG, JPEG, and GIF formats
Useful for retrieving plots and visualizations generated by MATLAB

Example response:

{
  "filename": "plot.png",
  "content_type": "image/png",
  "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAyQAAAMoCAYAAADhGzBzAAAA...",
  "size_bytes": 8192,
  "status": "success"
}

Admin

`get_pool_status`

Get the current status of the MATLAB engine pool.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Returns the total, available, busy, and max engine counts
Useful for monitoring resource availability

Example response:

{
  "total_engines": 4,
  "available_engines": 2,
  "busy_engines": 2,
  "max_engines": 4,
  "status": "healthy"
}

Monitoring

`get_server_metrics`

Get comprehensive server metrics including pool, jobs, sessions, and system stats.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Returns detailed metrics on engine pool, running jobs, active sessions, and system resources
Includes CPU, memory, and uptime information
Useful for system health monitoring and capacity planning

Example response:

{
  "timestamp": "2024-01-15T10:45:00Z",
  "uptime_seconds": 3600,
  "pool_metrics": {
    "total_engines": 4,
    "available_engines": 2,
    "busy_engines": 2,
    "max_engines": 4
  },
  "job_metrics": {
    "total_jobs": 25,
    "running_jobs": 3,
    "completed_jobs": 20,
    "failed_jobs": 2
  },
  "session_metrics": {
    "active_sessions": 5,
    "total_sessions": 10
  },
  "system_metrics": {
    "cpu_percent": 45.2,
    "memory_percent": 62.1,
    "memory_mb": 8192
  }
}

`get_server_health`

Get server health status with issue detection.

Parameter	Type	Required	Description
(none)	—	—	—

Behavior:

Returns health status: healthy, degraded, or unhealthy
Detects issues with engine pool, jobs, and system resources
Includes diagnostics and recommendations

Example response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:45:00Z",
  "checks": {
    "engine_pool": {
      "status": "healthy",
      "message": "All engines operational"
    },
    "job_queue": {
      "status": "healthy",
      "message": "Queue is processing normally"
    },
    "system_resources": {
      "status": "healthy",
      "message": "CPU and memory usage normal"
    }
  },
  "summary": "Server is operating normally"
}

`get_error_log`

Get recent server errors and notable events for diagnosing issues.

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of errors to return (default: 20)

Behavior:

Returns recent server errors and notable events
Useful for debugging and monitoring server issues
Errors are timestamped and include context

Example response:

{
  "errors": [
    {
      "timestamp": "2024-01-15T10:40:00Z",
      "level": "ERROR",
      "message": "Job abc123 failed: Undefined variable 'x'",
      "context": "execution"
    },
    {
      "timestamp": "2024-01-15T10:35:00Z",
      "level": "WARNING",
      "message": "Engine pool at 95% capacity",
      "context": "pool_management"
    },
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "INFO",
      "message": "Session xyz789 started",
      "context": "session_management"
    }
  ],
  "total_errors": 3,
  "limit": 20
}

Custom Tools

Custom tools can be registered by providing a custom_tools.yaml configuration file. Custom tools are dynamically loaded at server startup and exposed through the same interface as built-in tools. Define your custom tools in the following format:

tools:
  - name: my_custom_tool
    description: "Description of what the tool does"
    function: module.function_name
    parameters:
      - name: param1
        type: string
        required: true
        description: "Description of param1"
      - name: param2
        type: integer
        required: false
        description: "Description of param2"

Custom tools have the same capabilities as built-in tools and can execute arbitrary MATLAB code or interact with the session workspace.

MCP Tools Reference

MCP Tools Reference

Execution & Workspace

execute_code

check_code

get_workspace

Job Management

get_job_status

get_job_result

cancel_job

list_jobs

Discovery

list_toolboxes

list_functions

get_help

File Operations

upload_data

delete_file

list_files

read_script

read_data

read_image

Admin

get_pool_status

Monitoring

get_server_metrics

get_server_health

get_error_log

Custom Tools

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`execute_code`

`check_code`

`get_workspace`

`get_job_status`

`get_job_result`

`cancel_job`

`list_jobs`

`list_toolboxes`

`list_functions`

`get_help`

`upload_data`

`delete_file`

`list_files`

`read_script`

`read_data`

`read_image`

`get_pool_status`

`get_server_metrics`

`get_server_health`

`get_error_log`