Skip to content

MCP Tools Reference

Jump to bottom
github-actions[bot] edited this page Mar 22, 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": {"class": "double", "size": "1x1", "value": 5},
    "y": {"class": "double", "size": "1x1", "value": 3}
  }
}

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"
    },
    {
      "line": 7,
      "column": 1,
      "message": "Undefined function 'foo'",
      "severity": "error"
    }
  ],
  "summary": "1 warning(s), 1 error(s)"
}

get_workspace

Get variables in the current MATLAB workspace.

Parameter Type Required Description
(none) — — —

Returns the output of MATLAB's whos command with variable names, sizes, types, and memory usage.

Example response:

{
  "workspace": "Name          Size            Bytes  Class     Attributes\n  x             1x1                8  double    \n  y             1x1                8  double    \n  data        100x50            40000  double",
  "status": "success"
}

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

Example response (running):

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

Example response (completed):

{
  "job_id": "abc123",
  "status": "completed",
  "elapsed_seconds": 185.0,
  "completion_time": "2024-01-15T10:30:45Z"
}

get_job_result

Get the full result of a completed job, including output, variables, and execution details.

Parameter Type Required Description
job_id string yes Job ID

Example response:

{
  "job_id": "abc123",
  "status": "completed",
  "output": "Processing complete.\nResult: 42",
  "variables": {
    "result": {"class": "double", "size": "1x1", "value": 42}
  },
  "execution_time": 185.3
}

cancel_job

Cancel a pending or running job.

Parameter Type Required Description
job_id string yes Job ID

Example response:

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

list_jobs

List all jobs in the current session with their statuses.

Parameter Type Required Description
(none) — — —

Example response:

{
  "jobs": [
    {
      "job_id": "abc123",
      "status": "completed",
      "submitted": "2024-01-15T10:25:00Z",
      "completion_time": "2024-01-15T10:30:45Z",
      "execution_time": 185.3
    },
    {
      "job_id": "def456",
      "status": "running",
      "submitted": "2024-01-15T10:31:00Z",
      "elapsed_seconds": 5.2
    }
  ],
  "total": 2,
  "completed": 1,
  "running": 1
}

Discovery

list_toolboxes

List available MATLAB toolboxes installed and configured.

Parameter Type Required Description
(none) — — —

Example response:

{
  "toolboxes": [
    {
      "name": "MATLAB",
      "version": "R2023b"
    },
    {
      "name": "Signal Processing Toolbox",
      "version": "9.5"
    },
    {
      "name": "Image Processing Toolbox",
      "version": "11.6"
    }
  ],
  "count": 3
}

list_functions

List functions available in a specific MATLAB toolbox.

Parameter Type Required Description
toolbox_name string yes Name of the toolbox (e.g., "Signal Processing Toolbox")

Example response:

{
  "toolbox": "Signal Processing Toolbox",
  "output": "Signal Processing Toolbox\n\nTime series objects.\n  timetable - Create a timetable\n  ...\n\nFrequency Analysis.\n  periodogram - Estimate power spectral density using periodogram method\n  pwelch     - Estimate power spectral density using Welch method\n  ..."
}

get_help

Get MATLAB help documentation for any function or topic.

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

Example response:

{
  "function": "fft",
  "documentation": "FFT Discrete Fourier transform.\n   FFT(X) is the discrete Fourier transform of vector X.\n   For matrices, the FFT operation is applied to each column.\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

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

Example response:

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

list_files

List all files in the session's temporary directory.

Parameter Type Required Description
(none) — — —

Example response:

{
  "files": [
    {
      "filename": "data.csv",
      "path": "/tmp/session_abc123/data.csv",
      "size_bytes": 1024,
      "modified": "2024-01-15T10:25:00Z"
    },
    {
      "filename": "script.m",
      "path": "/tmp/session_abc123/script.m",
      "size_bytes": 512,
      "modified": "2024-01-15T10:20:00Z"
    }
  ],
  "total_files": 2,
  "total_size_bytes": 1536
}

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

Example response:

{
  "filename": "script.m",
  "content": "function result = myfunction(x)\n  % Calculate something\n  result = x * 2;\nend",
  "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 to read (.mat, .csv, .json, .txt, .xlsx)
format string no Format mode: "summary" (default) or "raw"

Example response (summary mode for .mat):

{
  "filename": "data.mat",
  "format": "summary",
  "variables": [
    {
      "name": "x",
      "class": "double",
      "size": "1000x1",
      "bytes": 8000
    },
    {
      "name": "y",
      "class": "double",
      "size": "1000x1",
      "bytes": 8000
    }
  ]
}

Example response (text file):

{
  "filename": "data.txt",
  "content": "Line 1\nLine 2\nLine 3",
  "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)

Returns an inline content block with the image data that renders in compatible clients.

Example response:

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

Admin

get_pool_status

Get the current status of the MATLAB engine pool.

Parameter Type Required Description
(none) — — —

Example response:

{
  "total_engines": 4,
  "available_engines": 3,
  "busy_engines": 1,
  "max_engines": 4,
  "utilization_percent": 25.0
}

Monitoring

get_server_metrics

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

Parameter Type Required Description
(none) — — —

Example response:

{
  "timestamp": "2024-01-15T10:35:00Z",
  "pool": {
    "total_engines": 4,
    "available_engines": 2,
    "busy_engines": 2,
    "utilization_percent": 50.0
  },
  "jobs": {
    "total": 12,
    "running": 2,
    "completed": 9,
    "failed": 1,
    "cancelled": 0
  },
  "sessions": {
    "active_sessions": 3,
    "total_created": 15
  },
  "system": {
    "cpu_percent": 45.2,
    "memory_percent": 62.1,
    "uptime_seconds": 86400
  }
}

get_server_health

Get server health status with issue detection.

Parameter Type Required Description
(none) — — —

Example response (healthy):

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

Example response (degraded):

{
  "status": "degraded",
  "issues": [
    "Pool utilization above 80%",
    "2 jobs failed in last hour"
  ],
  "last_check": "2024-01-15T10:35: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)

Example response:

{
  "errors": [
    {
      "timestamp": "2024-01-15T10:32:15Z",
      "level": "error",
      "message": "Job abc123 failed: Out of memory",
      "source": "job_executor"
    },
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "warning",
      "message": "Pool utilization at 95%",
      "source": "pool_manager"
    }
  ],
  "total_returned": 2,
  "limit": 20
}

Custom Tools

Custom tools can be defined and configured via the custom_tools.yaml file in your server configuration. These tools are dynamically registered at runtime and become available through the MCP protocol alongside the 20 built-in tools.

To add custom tools:

  1. Create or edit custom_tools.yaml in your configuration directory
  2. Define your custom tools with their parameters and implementations
  3. Restart the server to load the new tools
  4. Custom tools will appear in the same discovery and execution interfaces as built-in tools

Custom tools can wrap MATLAB functions, integrate with external services, or implement custom logic specific to your workflow.

Clone this wiki locally