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": {"size": "[1 1]", "type": "double"},
    "y": {"size": "[1 1]", "type": "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"
    },
    {
      "line": 7,
      "column": 1,
      "message": "Undefined function or variable",
      "severity": "error"
    }
  ],
  "summary": "1 warning(s), 1 error(s)"
}

get_workspace

Get variables in the current MATLAB workspace.

Parameter Type Required Description
(none) — — —

Example response:

{
  "output": "Name       Size            Bytes  Class     Attributes\n\n  A          2x2               32  double\n  data       1000x1          8000  double\n  result     1x1                8  double",
  "variables": {
    "A": {"size": "[2 2]", "bytes": 32, "type": "double"},
    "data": {"size": "[1000 1]", "bytes": 8000, "type": "double"},
    "result": {"size": "[1 1]", "bytes": 8, "type": "double"}
  }
}

Returns the output of MATLAB's whos command with parsed variable details.

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-def456",
  "status": "running",
  "progress": 65.0,
  "message": "Trial 650000/1000000",
  "elapsed_seconds": 120.5,
  "estimated_remaining": 64.3
}

Possible status values: pending, running, completed, failed, cancelled

get_job_result

Get the full result of a completed job.

Parameter Type Required Description
job_id string yes Job ID

Example response (completed):

{
  "job_id": "abc123-def456",
  "status": "completed",
  "output": "ans =\n  1.2345",
  "execution_time": 245.3,
  "variables": {
    "result": {"size": "[1 1]", "type": "double"}
  }
}

Example response (failed):

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

cancel_job

Cancel a pending or running job.

Parameter Type Required Description
job_id string yes Job ID

Example response:

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

list_jobs

List all jobs in the current session.

Parameter Type Required Description
(none) — — —

Example response:

{
  "jobs": [
    {
      "job_id": "abc123",
      "status": "completed",
      "submitted_at": "2025-01-15T10:30:45Z",
      "elapsed_seconds": 12.5
    },
    {
      "job_id": "def456",
      "status": "running",
      "submitted_at": "2025-01-15T10:45:20Z",
      "elapsed_seconds": 120.3
    }
  ],
  "summary": "2 total, 1 completed, 1 running"
}

Discovery

list_toolboxes

List available MATLAB toolboxes (filtered by configuration).

Parameter Type Required Description
(none) — — —

Example response:

{
  "toolboxes": [
    {
      "name": "MATLAB",
      "version": "R2024a",
      "release": "Update 1"
    },
    {
      "name": "Signal Processing Toolbox",
      "version": "9.4",
      "release": ""
    },
    {
      "name": "Statistics and Machine Learning Toolbox",
      "version": "12.5",
      "release": ""
    }
  ],
  "total": 3
}

list_functions

List functions in a specific toolbox.

Parameter Type Required Description
toolbox_name string yes Name of the toolbox

Example response:

{
  "toolbox": "Signal Processing Toolbox",
  "functions": [
    "fft",
    "ifft",
    "filter",
    "freqz",
    "butter",
    "cheby1",
    "ellip",
    "firpm"
  ],
  "output": "Signal Processing Toolbox\n  fft - Fast Fourier Transform\n  ..."
}

get_help

Get MATLAB help text for any function.

Parameter Type Required Description
function_name string yes Name of the function

Example response:

{
  "function": "fft",
  "output": "fft Fast Fourier Transform.\n   fft(X) computes the discrete Fourier transform of X.\n   ...",
  "available": true
}

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": 4096,
  "message": "File uploaded successfully"
}

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",
  "path": "/tmp/session-abc123/data.csv",
  "message": "File deleted successfully"
}

list_files

List files in the session's temporary directory.

Parameter Type Required Description
(none) — — —

Example response:

{
  "files": [
    {
      "name": "data.csv",
      "path": "/tmp/session-abc123/data.csv",
      "size_bytes": 4096,
      "modified": "2025-01-15T10:30:45Z"
    },
    {
      "name": "results.mat",
      "path": "/tmp/session-abc123/results.mat",
      "size_bytes": 8192,
      "modified": "2025-01-15T10:31:20Z"
    }
  ],
  "total_files": 2,
  "total_size_bytes": 12288
}

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

Example response:

{
  "filename": "myScript.m",
  "content": "% Main script\nx = 1:100;\ny = sin(x);\nplot(x, y);\ntitle('Sine Wave');"
}

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. For .mat files, summary shows variable info; raw returns base64 content.

Example response (summary mode, .mat file):

{
  "filename": "results.mat",
  "format": "summary",
  "variables": [
    {
      "name": "A",
      "size": "[3 3]",
      "bytes": 72,
      "class": "double"
    },
    {
      "name": "B",
      "size": "[100 1]",
      "bytes": 800,
      "class": "double"
    }
  ]
}

Example response (text file):

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

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: Image as an inline content block that renders in agent UIs.

Example response:

{
  "type": "image",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "mimeType": "image/png"
}

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": 2,
  "busy_engines": 2,
  "max_engines": 8,
  "pool_utilization_percent": 50.0
}

Monitoring

get_server_metrics

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

Parameter Type Required Description
(none) — — —

Example response:

{
  "pool": {
    "total_engines": 4,
    "available_engines": 2,
    "busy_engines": 2
  },
  "jobs": {
    "total": 42,
    "completed": 35,
    "running": 5,
    "failed": 2
  },
  "sessions": {
    "active": 3,
    "total_created": 15
  },
  "system": {
    "uptime_seconds": 86400,
    "memory_usage_percent": 65.3,
    "cpu_usage_percent": 22.5
  }
}

get_server_health

Get server health status with issue detection.

Parameter Type Required Description
(none) — — —

Example response:

{
  "status": "healthy",
  "checks": {
    "pool_availability": "ok",
    "job_queue": "ok",
    "memory_usage": "ok",
    "recent_errors": "ok"
  },
  "issues": [],
  "message": "All systems operational"
}

Possible status values: healthy, degraded, unhealthy

Example response (degraded):

{
  "status": "degraded",
  "checks": {
    "pool_availability": "warning",
    "job_queue": "ok",
    "memory_usage": "warning",
    "recent_errors": "ok"
  },
  "issues": [
    "Pool utilization at 87% (high)",
    "Memory usage at 78% (elevated)"
  ],
  "message": "One or more system checks show degraded conditions"
}

get_error_log

Get recent server errors and notable events for diagnosing issues.

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

Example response:

{
  "errors": [
    {
      "timestamp": "2025-01-15T10:45:30Z",
      "level": "error",
      "source": "job_executor",
      "message": "Job abc123 failed: Undefined function 'myFunc'"
    },
    {
      "timestamp": "2025-01-15T10:30:15Z",
      "level": "warning",
      "source": "pool_manager",
      "message": "Engine pool utilization exceeded 80%"
    },
    {
      "timestamp": "2025-01-15T10:15:00Z",
      "level": "info",
      "source": "session_manager",
      "message": "Session xyz789 created"
    }
  ],
  "total_errors": 3,
  "total_warnings": 5,
  "total_info": 12
}

Custom Tools

Custom tools are configured via custom_tools.yaml and are dynamically registered at runtime. Each custom tool follows the same interface as built-in tools and appears in the tool list with its configured name, description, and parameters. Custom tools are executed with access to the same MATLAB session and workspace as built-in execution tools.

To define custom tools, create a custom_tools.yaml file in your server configuration directory with tool definitions including name, description, parameters, and the MATLAB code to execute. Custom tools are loaded when the server starts and can be called like any other MCP tool.

Clone this wiki locally