Skip to content

MCP Tools Reference

Jump to bottom
github-actions[bot] edited this page Mar 18, 2026 · 13 revisions

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 synchronously if it completes within sync_timeout (default 30s)
  • Auto-promotes to async if it exceeds the timeout
  • Returns inline result for sync, or job_id for async

Example response (sync):

{
  "status": "completed",
  "output": "ans =\n    15",
  "execution_time": 0.23
}

Example response (async promotion):

{
  "status": "running",
  "job_id": "abc123-def456",
  "message": "Job promoted to async execution"
}

check_code

Lint MATLAB code using checkcode/mlint.

Parameter Type Required Description
code string yes MATLAB code to check

Example response:

{
  "issues": [
    {
      "line": 3,
      "column": 5,
      "message": "Variable 'x' might be unused",
      "severity": "warning"
    }
  ],
  "summary": "1 warning(s), 0 error(s)"
}

get_workspace

Get variables in the current MATLAB workspace.

Parameter Type Required Description
(none) — — —

Returns the output of MATLAB's whos command, listing all variables with their sizes, classes, and byte counts.

Job Management

get_job_status

Get status and progress of a running job.

Parameter Type Required Description
job_id string yes Job ID from execute_code

Example response:

{
  "job_id": "abc123",
  "status": "running",
  "progress": 65.0,
  "message": "Trial 650000/1000000",
  "elapsed_seconds": 120.5
}

get_job_result

Get the full result of a completed job.

Parameter Type Required Description
job_id string yes Job ID

Returns the complete result dict for completed jobs, or the error dict for failed jobs, including output, variables, and execution timing.

cancel_job

Cancel a pending or running job.

Parameter Type Required Description
job_id string yes Job ID

Attempts to cancel the underlying MATLAB future and marks the job as cancelled in the job tracker.

list_jobs

List all jobs in the current session.

Parameter Type Required Description
(none) — — —

Returns a list of job summaries including job IDs, status, and execution timing for all jobs in the current session.

Discovery

list_toolboxes

List available MATLAB toolboxes (filtered by configuration).

Parameter Type Required Description
(none) — — —

Runs MATLAB's ver command and returns the output along with toolbox configuration information.

Example response:

{
  "output": "MATLAB Version 23.2.1\n\nSignal Processing Toolbox...",
  "toolboxes": [
    {
      "name": "Signal Processing Toolbox",
      "version": "9.2"
    }
  ]
}

list_functions

List functions in a specific MATLAB toolbox.

Parameter Type Required Description
toolbox_name string yes Name of the toolbox

Runs MATLAB's help <toolbox_name> command and returns the function list and documentation.

get_help

Get MATLAB help text for any function.

Parameter Type Required Description
function_name string yes Name of the function

Runs MATLAB's help <function_name> command and returns the full documentation.

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

The file is written to the session temp directory and can be accessed from MATLAB code.

Example response:

{
  "status": "success",
  "filename": "data.csv",
  "path": "/tmp/matlab_session_xyz/data.csv",
  "size_bytes": 1024
}

delete_file

Delete a file from the session's temporary directory.

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

Only files in the session temp directory can be deleted. Non-existent files will return an error.

list_files

List all files in the session's temporary directory.

Parameter Type Required Description
(none) — — —

Returns names, sizes, and paths for all files in the session temp directory.

Example response:

{
  "files": [
    {
      "name": "data.csv",
      "size_bytes": 2048,
      "path": "/tmp/matlab_session_xyz/data.csv"
    },
    {
      "name": "results.mat",
      "size_bytes": 5120,
      "path": "/tmp/matlab_session_xyz/results.mat"
    }
  ],
  "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 file to read

Returns the file content as text. Use list_files to see available files.

Example response:

{
  "filename": "myScript.m",
  "content": "% My MATLAB script\nx = linspace(0, 2*pi, 100);\ny = sin(x);\nplot(x, y);"
}

read_data

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

Parameter Type Required Description
filename string yes Name of the file (.mat, .csv, .json, .txt, .xlsx)
format string no summary (default) or raw for .mat files

For .mat files, 'summary' mode shows variable names, sizes, and types via MATLAB. 'raw' mode returns base64-encoded content. Text files return inline content.

Example response (summary):

{
  "filename": "results.mat",
  "format": "summary",
  "variables": [
    {
      "name": "x",
      "size": "[100 1]",
      "type": "double"
    }
  ]
}

Example response (text file):

{
  "filename": "data.csv",
  "content": "x,y,z\n1,2,3\n4,5,6"
}

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)

Returns the image as an inline content block that renders in agent UIs.

Admin

get_pool_status

Get the current status of the MATLAB engine pool.

Parameter Type Required Description
(none) — — —

Returns the total, available, busy, and maximum engine counts.

Example response:

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

Monitoring

get_server_metrics

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

Parameter Type Required Description
(none) — — —

Returns detailed metrics about server health, resource utilization, and job activity.

Example response:

{
  "pool": {
    "total_engines": 4,
    "available_engines": 2,
    "busy_engines": 2
  },
  "jobs": {
    "total": 150,
    "running": 5,
    "completed": 140,
    "failed": 5
  },
  "sessions": {
    "active": 3,
    "total_created": 25
  },
  "system": {
    "uptime_seconds": 86400,
    "memory_usage_percent": 45.2
  }
}

get_server_health

Get server health status with issue detection.

Parameter Type Required Description
(none) — — —

Returns overall health status as healthy, degraded, or unhealthy, with details about any detected issues.

Example response:

{
  "status": "healthy",
  "checks": {
    "pool": "ok",
    "jobs": "ok",
    "memory": "ok"
  },
  "issues": []
}

get_error_log

Get recent server errors and notable events for diagnosing issues.

Parameter Type Required Description
limit integer no Maximum number of log entries (default: 20)

Returns recent error messages and notable events from the server log.

Example response:

{
  "errors": [
    {
      "timestamp": "2024-01-15T10:23:45Z",
      "level": "error",
      "message": "MATLAB engine timeout on job abc123",
      "job_id": "abc123"
    }
  ],
  "total_errors": 42
}

Custom Tools

Custom tools can be defined in your custom_tools.yaml configuration file and are dynamically registered at runtime. Custom tools follow the same conventions as built-in tools and can be called using the standard MCP tool interface. Refer to your custom_tools.yaml for the complete list of custom tools available in your deployment.

Clone this wiki locally