Skip to content

Configuration

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

Configuration

All settings are in config.yaml with sensible defaults. Every setting can be overridden via environment variables with the MATLAB_MCP_ prefix.

Config File Location

The server looks for config.yaml in the current working directory by default. Override with:

matlab-mcp --config /path/to/my_config.yaml

Environment Variable Overrides

Any config value can be set via environment variable using the pattern MATLAB_MCP_<SECTION>_<KEY>:

export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_PORT=9000

Convention: The first underscore after MATLAB_MCP_ separates section from key. For example:

  • MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines
  • MATLAB_MCP_SERVER_LOG_LEVEL → server.log_level
  • MATLAB_MCP_EXECUTION_SYNC_TIMEOUT → execution.sync_timeout

Type Coercion: Environment variables are automatically coerced to the appropriate type: integers, floats, booleans (true/false), or strings.

Full Configuration Reference

Server

Configuration for the MCP server transport, logging, and shutdown behavior.

server:
  name: "matlab-mcp-server"        # Server name reported to MCP clients
  transport: "stdio"                # stdio | sse
  host: "0.0.0.0"                  # Bind address (SSE transport only)
  port: 8765                        # Port (SSE transport only)
  log_level: "info"                 # debug | info | warning | error
  log_file: "./logs/server.log"    # Log file path (resolved to absolute)
  result_dir: "./results"           # Where to store result files (resolved to absolute)
  drain_timeout_seconds: 300        # Max wait for running jobs during graceful shutdown
Field Type Default Description
name string "matlab-mcp-server" Server name reported to MCP clients
transport stdio | sse "stdio" Transport mechanism; sse requires host and port
host string "0.0.0.0" Bind address for SSE transport
port integer 8765 Port for SSE transport
log_level debug | info | warning | error "info" Log verbosity level
log_file string "./logs/server.log" Log file path; relative paths resolved from config directory
result_dir string "./results" Directory for storing result files; relative paths resolved from config directory
drain_timeout_seconds integer 300 Seconds to wait for in-flight jobs before shutdown

Environment Variable Overrides:

  • MATLAB_MCP_SERVER_NAME
  • MATLAB_MCP_SERVER_TRANSPORT
  • MATLAB_MCP_SERVER_HOST
  • MATLAB_MCP_SERVER_PORT
  • MATLAB_MCP_SERVER_LOG_LEVEL
  • MATLAB_MCP_SERVER_LOG_FILE
  • MATLAB_MCP_SERVER_RESULT_DIR
  • MATLAB_MCP_SERVER_DRAIN_TIMEOUT_SECONDS

Pool

Configuration for the MATLAB engine pool: sizing, auto-scaling, and health checks.

pool:
  min_engines: 2                    # Always keep this many engines warm
  max_engines: 10                   # Hard ceiling (capped at 4 on macOS)
  scale_down_idle_timeout: 900      # Seconds idle before scaling down (15 min)
  engine_start_timeout: 120         # Seconds to wait for MATLAB to start
  health_check_interval: 60         # Seconds between health pings
  proactive_warmup_threshold: 0.8   # Utilization ratio (0.0–1.0) to trigger warmup
  queue_max_size: 50                # Max pending requests in queue
  matlab_root: null                 # Auto-detect, or set explicit MATLAB path
Field Type Default Description
min_engines integer 2 Minimum engines to keep warm; must be ≤ max_engines
max_engines integer 10 Maximum engines; limited to 4 on macOS by default
scale_down_idle_timeout integer 900 Seconds with no activity before scaling down to min_engines
engine_start_timeout integer 120 Seconds to wait for a MATLAB engine to start
health_check_interval integer 60 Seconds between health pings to active engines
proactive_warmup_threshold float 0.8 Pool utilization ratio (0.0–1.0) above which new engines are warmed up
queue_max_size integer 50 Maximum requests allowed in pending queue; requests beyond this are rejected
matlab_root string | null null Explicit MATLAB installation path; if null, auto-detected

Validation:

  • min_engines must be ≤ max_engines (raises ValueError if violated)
  • On macOS, a warning is emitted if max_engines > 4 due to known stability limitations with multiple matlab.engine instances

Environment Variable Overrides:

  • MATLAB_MCP_POOL_MIN_ENGINES
  • MATLAB_MCP_POOL_MAX_ENGINES
  • MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT
  • MATLAB_MCP_POOL_ENGINE_START_TIMEOUT
  • MATLAB_MCP_POOL_HEALTH_CHECK_INTERVAL
  • MATLAB_MCP_POOL_PROACTIVE_WARMUP_THRESHOLD
  • MATLAB_MCP_POOL_QUEUE_MAX_SIZE
  • MATLAB_MCP_POOL_MATLAB_ROOT

Execution

Configuration for code execution: timeouts, workspace isolation, and temp files.

execution:
  sync_timeout: 30                  # Seconds before auto-promoting to async
  max_execution_time: 86400         # Hard limit per job (24h = 86400s)
  workspace_isolation: true         # Clear workspace between sessions
  engine_affinity: false            # Pin session to specific engine
  temp_dir: "./temp"                # Temporary file directory (resolved to absolute)
  temp_cleanup_on_disconnect: true  # Delete temp files when session ends
Field Type Default Description
sync_timeout integer 30 Seconds of execution before auto-promoting sync code to async job; returning job_id for polling
max_execution_time integer 86400 Hard ceiling per job in seconds; prevents runaway execution
workspace_isolation boolean true If true, clear workspace after each execution; if false, preserve variables between calls
engine_affinity boolean false If true, pin a session to a specific engine for workspace persistence; if false, any available engine is used
temp_dir string "./temp" Directory for temporary files; relative paths resolved from config directory
temp_cleanup_on_disconnect boolean true If true, delete session temp files when the session disconnects

Notes:

  • Increasing sync_timeout is useful for environments where most code takes 30–60 seconds.
  • engine_affinity enables workspace persistence but reduces pool flexibility.

Environment Variable Overrides:

  • MATLAB_MCP_EXECUTION_SYNC_TIMEOUT
  • MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME
  • MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION
  • MATLAB_MCP_EXECUTION_ENGINE_AFFINITY
  • MATLAB_MCP_EXECUTION_TEMP_DIR
  • MATLAB_MCP_EXECUTION_TEMP_CLEANUP_ON_DISCONNECT

Workspace

Configuration for MATLAB workspace setup: default paths and startup commands.

workspace:
  default_paths:                    # Added to MATLAB path on engine start
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:                 # Run on each engine start and after workspace reset
    - "format long"
Field Type Default Description
default_paths string[] [] Directories added to MATLAB path (addpath) on engine start and after workspace reset
startup_commands string[] ["format long"] MATLAB commands executed on each engine start and after workspace reset

Notes:

  • Paths are added in order; absolute paths are preferred.
  • Startup commands run after paths are added, so they can reference newly added functions.
  • Both are re-executed after workspace reset if execution.workspace_isolation is true.

Environment Variable Overrides:

  • MATLAB_MCP_WORKSPACE_DEFAULT_PATHS — Not supported (list field; use config file)
  • MATLAB_MCP_WORKSPACE_STARTUP_COMMANDS — Not supported (list field; use config file)

Toolboxes

Configuration for toolbox visibility: expose all, whitelist, or blacklist.

toolboxes:
  mode: "whitelist"                 # whitelist | blacklist | all
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"
Field Type Default Description
mode whitelist | blacklist | all "whitelist" How to filter toolboxes reported to agents
list string[] [] Toolbox names; meaning depends on mode
Mode Behavior
whitelist Only toolboxes in list are reported to agents; all others are hidden
blacklist All installed toolboxes EXCEPT those in list are reported
all All installed toolboxes are reported; list is ignored

Environment Variable Overrides:

  • MATLAB_MCP_TOOLBOXES_MODE
  • MATLAB_MCP_TOOLBOXES_LIST — Not supported (list field; use config file)

Custom Tools

Configuration for user-provided custom MCP tools.

custom_tools:
  config_file: "./custom_tools.yaml"
Field Type Default Description
config_file string "./custom_tools.yaml" Path to YAML file defining custom tools; relative paths resolved from config directory

Notes:

  • See Custom Tools for the full custom tools YAML format.
  • If the file does not exist, custom tools are silently disabled (warning logged).

Environment Variable Overrides:

  • MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE

Security

Configuration for security controls: blocked functions, upload limits, proxy authentication.

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"
  max_upload_size_mb: 100
  require_proxy_auth: false
Field Type Default Description
blocked_functions_enabled boolean true If true, enforce the blocked functions list; if false, allow all functions
blocked_functions string[] See default list MATLAB functions that are not allowed to execute
max_upload_size_mb integer 100 Maximum file upload size in megabytes
require_proxy_auth boolean false Set true if SSE transport is behind an authentication proxy (for production deployments)

Notes:

  • The security validator scans code for function calls but strips string literals and comments, so disp('system') will not trigger a false positive.
  • The default blocked list includes shell execution (system, unix, dos, !), code evaluation (eval, feval, evalc, evalin, assignin), and cross-language calls (perl, python).
  • require_proxy_auth is informational; when true, the server logs a reminder that auth is handled upstream.

Environment Variable Overrides:

  • MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED
  • MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB
  • MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH
  • MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS — Not supported (list field; use config file)

Code Checker

Configuration for code linting via MATLAB's checkcode (mlint).

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]
Field Type Default Description
enabled boolean true If true, enable code checker availability; if false, checker is disabled
auto_check_before_execute boolean false If true, automatically run checkcode before every execution and warn on issues
severity_levels string[] ["error", "warning"] Which severity levels to report (e.g., ["error"] excludes warnings)

Notes:

  • Setting auto_check_before_execute to true adds latency to every execution but catches issues early.
  • Severity levels are "error", "warning", "info", etc.

Environment Variable Overrides:

  • MATLAB_MCP_CODE_CHECKER_ENABLED
  • MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE
  • MATLAB_MCP_CODE_CHECKER_SEVERITY_LEVELS — Not supported (list field; use config file)

Output

Configuration for output formatting: Plotly conversion, image formats, thumbnails, and truncation thresholds.

output:
  plotly_conversion: true
  static_image_format: "png"        # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000
  max_inline_text_length: 50000
Field Type Default Description
plotly_conversion boolean true If true, convert MATLAB figures to Plotly JSON for interactive viewing
static_image_format png | jpg | svg "png" Image format for static figure exports
static_image_dpi integer 150 DPI for static image exports
thumbnail_enabled boolean true If true, generate thumbnails for figures
thumbnail_max_width integer 400 Maximum width in pixels for thumbnails
large_result_threshold integer 10000 Element count above which tabular/matrix data is saved to file instead of inlined
max_inline_text_length integer 50000 Character count above which text output is saved to file instead of inlined

Notes:

  • Large results are saved to the server.result_dir and referenced by path in the response.
  • plotly_conversion requires the plotly library (included with most MATLAB distributions).

Environment Variable Overrides:

  • MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION
  • MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT
  • MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI
  • MATLAB_MCP_OUTPUT_THUMBNAIL_ENABLED
  • MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH
  • MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD
  • MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH

Sessions

Configuration for session management: limits, idle timeout, and job retention.

sessions:
  max_sessions: 50
  session_timeout: 3600
  job_retention_seconds: 86400
Field Type Default Description
max_sessions integer 50 Maximum number of concurrent sessions allowed
session_timeout integer 3600 Seconds of inactivity before a session is cleaned up (1h)
job_retention_seconds integer 86400 Seconds to retain completed job metadata for polling (24h)

Notes:

  • When a session reaches session_timeout without activity, it is garbage-collected and its resources are freed.
  • job_retention_seconds determines how long clients can poll a finished job's status and results.

Environment Variable Overrides:

  • MATLAB_MCP_SESSIONS_MAX_SESSIONS
  • MATLAB_MCP_SESSIONS_SESSION_TIMEOUT
  • MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS

Monitoring

Configuration for the optional monitoring subsystem: metrics collection, database, and dashboard.

monitoring:
  enabled: true
  sample_interval: 10
  retention_days: 7
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766
Field Type Default Description
enabled boolean true If true, enable metrics collection and storage
sample_interval integer 10 Seconds between metric samples (CPU, memory, pool utilization, etc.)
retention_days integer 7 Days to retain historical metrics in the database
db_path string "./monitoring/metrics.db" SQLite database path; relative paths resolved from config directory
dashboard_enabled boolean true If true, enable the web dashboard endpoint
http_port integer 8766 Port for the dashboard HTTP server (stdio transport only; SSE uses main server.port)

Notes:

  • Monitoring requires optional dependencies: pip install -e ".[monitoring]" (includes psutil, uvicorn, etc.)
  • The dashboard is available at http://localhost:8766 (configurable via http_port).
  • For SSE transport, the dashboard uses the same port as the server.
  • Metrics include engine pool utilization, execution times, queue depth, and system resource usage.

Environment Variable Overrides:

  • MATLAB_MCP_MONITORING_ENABLED
  • MATLAB_MCP_MONITORING_SAMPLE_INTERVAL
  • MATLAB_MCP_MONITORING_RETENTION_DAYS
  • MATLAB_MCP_MONITORING_DB_PATH
  • MATLAB_MCP_MONITORING_DASHBOARD_ENABLED
  • MATLAB_MCP_MONITORING_HTTP_PORT

Example Configurations

See the examples/ directory for ready-to-use configurations:

  • config_minimal.yaml — Single user, minimal settings
  • config_multiuser.yaml — Multi-user SSE with larger pool and stricter security

Clone this wiki locally