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,
  "variables": {
    "x": "1×1 double"
  }
}

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) — — —

Description: Returns the output of MATLAB's whos command, listing all variables in the workspace with their sizes, classes, and memory usage.

Example response:

{
  "output": "  Name      Size            Bytes  Class     Attributes\n  x         1×1                8  double",
  "status": "completed"
}

Job Management

get_job_status

Get status and progress of a running or completed job.

Parameter Type Required Description
job_id string yes Job ID from execute_code

Behavior:

  • For running jobs, returns status, timing info, and progress (if available)
  • For completed jobs, returns completion status and results
  • For failed jobs, returns error information

Example response:

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

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 result dict for successfully completed jobs
  • Returns error dict with error message and traceback for failed jobs
  • Includes output, variables, and execution timing

Example response:

{
  "status": "completed",
  "job_id": "abc123",
  "output": "ans =\n  1.2345",
  "variables": {
    "result": "1×1 double"
  },
  "execution_time": 45.3
}

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 tracker
  • Returns success/failure status

Example response:

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

list_jobs

List all jobs in the current session.

Parameter Type Required Description
(none) — — —

Description: Returns a list of job summaries including status, timing, and brief execution info for all jobs submitted in this session.

Example response:

{
  "jobs": [
    {
      "job_id": "abc123",
      "status": "completed",
      "submitted_at": "2024-01-15T10:30:45Z",
      "execution_time": 2.5
    },
    {
      "job_id": "def456",
      "status": "running",
      "submitted_at": "2024-01-15T10:31:12Z",
      "progress": 42.0
    }
  ],
  "total": 2
}

Discovery

list_toolboxes

List available MATLAB toolboxes (filtered by server configuration).

Parameter Type Required Description
(none) — — —

Description: Runs MATLAB's ver command and returns installed toolboxes along with version and configuration info.

Example response:

{
  "toolboxes": [
    {
      "name": "MATLAB",
      "version": "R2023b"
    },
    {
      "name": "Signal Processing Toolbox",
      "version": "9.1"
    }
  ],
  "output": "MATLAB Version ...\nSignal Processing Toolbox Version 9.1 ..."
}

list_functions

List functions in a specific MATLAB toolbox.

Parameter Type Required Description
toolbox_name string yes Name of the toolbox (e.g., "signal", "image")

Description: Runs MATLAB's help <toolbox_name> command and returns the function list for the specified toolbox.

Example response:

{
  "toolbox_name": "signal",
  "output": "Signal Processing Toolbox\n\nSignal Generation...\n  chirp - ...\n  cos - ...",
  "status": "completed"
}

get_help

Get MATLAB help text for any function.

Parameter Type Required Description
function_name string yes Name of the function (e.g., "fft", "sin")

Description: Runs MATLAB's help <function_name> command and returns the documentation for the specified function.

Example response:

{
  "function_name": "fft",
  "output": "FFT    Discrete Fourier transform.\n\n    FFT(X) is the discrete Fourier transform of vector X.\n    FFT(X,N) pads X with zeros...",
  "status": "completed"
}

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:

  • Writes the file to the session's temporary directory
  • File can be accessed from MATLAB code using relative paths
  • Supports any file type

Example response:

{
  "filename": "data.csv",
  "path": "/tmp/session-abc123/data.csv",
  "size_bytes": 1024,
  "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
  • Permanent deletion; cannot be recovered

Example response:

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

list_files

List files in the session's temporary directory.

Parameter Type Required Description
(none) — — —

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

Example response:

{
  "files": [
    {
      "name": "data.csv",
      "size_bytes": 2048,
      "path": "/tmp/session-abc123/data.csv"
    },
    {
      "name": "script.m",
      "size_bytes": 512,
      "path": "/tmp/session-abc123/script.m"
    }
  ],
  "total": 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

Description: Returns the MATLAB script content as text. Use list_files to see available files.

Example response:

{
  "filename": "script.m",
  "content": "% My MATLAB script\nx = 1:10;\ny = sin(x);\nplot(x, y);",
  "status": "success"
}

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 Read format: summary (default) or raw

Behavior:

  • For .mat files: summary shows variable names/sizes/types; raw returns base64-encoded content
  • For text files (.csv, .json, .txt): returns inline content
  • For .xlsx files: returns tabular data

Example response (summary mode):

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

Example response (text file):

{
  "filename": "data.csv",
  "content": "x,y\n1,2\n3,4\n5,6",
  "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)

Description: Returns the image as an inline content block that renders in agent UIs. Useful for viewing MATLAB plot outputs and visualizations.

Example response:

{
  "filename": "plot.png",
  "content_type": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "status": "success"
}

Admin

get_pool_status

Get the current status of the MATLAB engine pool.

Parameter Type Required Description
(none) — — —

Description: Returns the total, available, busy, and max engine counts. Useful for monitoring resource utilization.

Example response:

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

Monitoring

get_server_metrics

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

Parameter Type Required Description
(none) — — —

Description: Returns detailed metrics about server health, resource usage, job statistics, and system performance.

Example response:

{
  "timestamp": "2024-01-15T10:32:00Z",
  "pool": {
    "total_engines": 4,
    "available_engines": 2,
    "busy_engines": 2,
    "utilization_percent": 50.0
  },
  "jobs": {
    "total": 42,
    "completed": 38,
    "running": 2,
    "failed": 2
  },
  "sessions": {
    "active": 5,
    "total_created": 12
  },
  "system": {
    "memory_percent": 45.2,
    "cpu_percent": 23.5,
    "uptime_seconds": 86400
  }
}

get_server_health

Get server health status with issue detection.

Parameter Type Required Description
(none) — — —

Description: Returns overall health status (healthy/degraded/unhealthy) and a list of any detected issues or warnings.

Example response:

{
  "status": "healthy",
  "issues": [],
  "warnings": [],
  "last_check": "2024-01-15T10:32:00Z"
}

Example response (degraded):

{
  "status": "degraded",
  "issues": [
    "High memory usage (85%)"
  ],
  "warnings": [
    "One engine unavailable"
  ],
  "last_check": "2024-01-15T10:32:00Z"
}

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)

Description: Returns a chronological list of recent server errors, warnings, and notable events.

Example response:

{
  "errors": [
    {
      "timestamp": "2024-01-15T10:31:30Z",
      "level": "error",
      "message": "Job abc123 failed with timeout",
      "job_id": "abc123"
    },
    {
      "timestamp": "2024-01-15T10:30:45Z",
      "level": "warning",
      "message": "Engine pool utilization at 95%"
    }
  ],
  "total_available": 127,
  "returned": 2
}

Custom Tools

Custom tools can be registered by defining them in your custom_tools.yaml configuration file. These tools are dynamically loaded at server startup and become available alongside the built-in tools. Each custom tool follows the same MCP protocol and can be called using the standard MCP tools mechanism. For details on creating custom tools, refer to the server configuration documentation.

Clone this wiki locally