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

Environment Variable Parsing: The section and key are determined by splitting on the first underscore after MATLAB_MCP_. Underscores in the key name are preserved. For example:

MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines
MATLAB_MCP_SERVER_LOG_LEVEL → server.log_level

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

Full Configuration Reference

Server

Configuration for transport, host/port, logging, and graceful shutdown.

Field	Type	Default	Description
`name`	string	`"matlab-mcp-server"`	Server name reported to MCP clients
`transport`	`stdio` \| `sse`	`"stdio"`	Transport protocol (stdio for stdio, sse for HTTP Server-Sent Events)
`host`	string	`"0.0.0.0"`	Bind address (SSE transport only)
`port`	integer	`8765`	TCP port (SSE transport only)
`log_level`	`debug` \| `info` \| `warning` \| `error`	`"info"`	Logging verbosity
`log_file`	string	`"./logs/server.log"`	Path to log file (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`	Max seconds to wait for running jobs during graceful 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 MATLAB engine pool sizing, timeouts, and auto-scaling behavior.

Field	Type	Default	Description
`min_engines`	integer	`2`	Minimum number of engines to keep warm
`max_engines`	integer	`10`	Maximum number of engines (capped at 4 on macOS)
`scale_down_idle_timeout`	integer	`900`	Seconds of idle time before scaling down an engine
`engine_start_timeout`	integer	`120`	Seconds to wait for MATLAB to start
`health_check_interval`	integer	`60`	Seconds between engine health pings
`proactive_warmup_threshold`	float	`0.8`	Utilization ratio (0.0–1.0) that triggers proactive engine startup
`queue_max_size`	integer	`50`	Maximum pending requests in the execution queue
`matlab_root`	string \| null	`null`	MATLAB installation root (auto-detected if null)

Validation: min_engines must not exceed max_engines.

macOS Note: MATLAB on macOS has a 4-engine limit. The server logs a warning if max_engines > 4 on macOS but still respects the configured value.

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 behavior, and temporary files.

Field	Type	Default	Description
`sync_timeout`	integer	`30`	Seconds before auto-promoting long-running code to async
`max_execution_time`	integer	`86400`	Hard time limit per job in seconds (24 hours)
`workspace_isolation`	boolean	`true`	Clear workspace between sessions
`engine_affinity`	boolean	`false`	Pin session to specific engine for workspace persistence
`temp_dir`	string	`"./temp"`	Temporary file directory (relative paths resolved from config directory)
`temp_cleanup_on_disconnect`	boolean	`true`	Delete temp files when session disconnects

sync_timeout Behavior: When code runs longer than this threshold, the server automatically returns a job_id for polling instead of blocking. Increase for workflows expecting longer execution times.

engine_affinity: When enabled, a session is pinned to a single engine and workspace state persists across executions. When disabled, sessions may execute on different engines with isolated workspaces.

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 initialization.

Field	Type	Default	Description
`default_paths`	list of strings	`[]`	Directories added to MATLAB path on engine start and after workspace reset
`startup_commands`	list of strings	`["format long"]`	MATLAB commands executed on engine start and after workspace reset

Example:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:
    - "format long"
    - "addpath(genpath('/shared/functions'))"

Toolboxes

Configuration for toolbox visibility and filtering.

Field	Type	Default	Description
`mode`	`whitelist` \| `blacklist` \| `all`	`"whitelist"`	Toolbox filtering mode
`list`	list of strings	See defaults below	Toolbox names to whitelist, blacklist, or reference

Mode Behavior:

Mode	Behavior
`whitelist`	Only listed toolboxes are reported to agents
`blacklist`	All installed toolboxes EXCEPT listed ones are reported
`all`	All installed toolboxes are reported (list is ignored)

Default Whitelist:

toolboxes:
  mode: "whitelist"
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"

Custom Tools

Configuration for user-provided custom MCP tools.

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

See the Custom Tools documentation for the YAML format and examples.

Security

Configuration for function blocking, file uploads, and authentication requirements.

Field	Type	Default	Description
`blocked_functions_enabled`	boolean	`true`	Enable function blocking
`blocked_functions`	list of strings	See defaults below	MATLAB functions to block from execution
`max_upload_size_mb`	integer	`100`	Maximum upload file size in megabytes
`require_proxy_auth`	boolean	`false`	Require authentication (set to true for SSE behind proxy)

Default Blocked Functions:

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"

Function Blocking: The security validator strips string literals and comments before scanning code, so disp('system') won't trigger a false positive.

require_proxy_auth: Set to true when deploying SSE transport behind an authentication proxy to indicate that authentication is handled externally.

Environment Variable Overrides:

MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED
MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB
MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH

Code Checker

Configuration for code linting and validation via MATLAB's checkcode function.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable code checker
`auto_check_before_execute`	boolean	`false`	Automatically run checkcode before every execution
`severity_levels`	list of strings	`["error", "warning"]`	Message severity levels to report

Severity Levels: Supported values are "error" and "warning". Other MATLAB message IDs can be included but are typically not reported by checkcode.

Environment Variable Overrides:

MATLAB_MCP_CODE_CHECKER_ENABLED
MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE

Output

Configuration for output formatting, image conversion, and result truncation.

Field	Type	Default	Description
`plotly_conversion`	boolean	`true`	Convert MATLAB figures to Plotly JSON format
`static_image_format`	`png` \| `jpg` \| `svg`	`"png"`	Static image format for figure export
`static_image_dpi`	integer	`150`	DPI for raster image export
`thumbnail_enabled`	boolean	`true`	Generate thumbnails for figures
`thumbnail_max_width`	integer	`400`	Maximum thumbnail width in pixels
`large_result_threshold`	integer	`10000`	Element count above which tabular/matrix results are saved to file
`max_inline_text_length`	integer	`50000`	Character count above which text output is saved to file

Result Storage: When results exceed large_result_threshold (for data) or max_inline_text_length (for text), they are saved to the result_dir and a reference URL is returned instead of inline content.

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 and job retention.

Field	Type	Default	Description
`max_sessions`	integer	`50`	Maximum concurrent sessions
`session_timeout`	integer	`3600`	Seconds of inactivity before session cleanup (1 hour)
`job_retention_seconds`	integer	`86400`	How long to keep completed job metadata before cleanup (24 hours)

session_timeout: Sessions that have no activity for this duration are automatically cleaned up. Resets on each request.

job_retention_seconds: Completed jobs are retained for this duration, allowing clients to poll results. After expiration, job records are removed.

Environment Variable Overrides:

MATLAB_MCP_SESSIONS_MAX_SESSIONS
MATLAB_MCP_SESSIONS_SESSION_TIMEOUT
MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS

Monitoring

Configuration for the optional metrics collection and web dashboard.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable metrics collection and monitoring subsystem
`sample_interval`	integer	`10`	Seconds between metric samples
`retention_days`	integer	`7`	Days to keep historical metrics data
`db_path`	string	`"./monitoring/metrics.db"`	SQLite database path (relative paths resolved from config directory)
`dashboard_enabled`	boolean	`true`	Enable web dashboard
`http_port`	integer	`8766`	HTTP port for dashboard and health endpoints (stdio transport only)

Dependencies: Monitoring requires optional dependencies. Install with:

pip install -e ".[monitoring]"

Dashboard Access: When enabled and using stdio transport, the dashboard is accessible at http://localhost:8766 (or configured http_port). SSE transport does not run a separate HTTP server for the dashboard.

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

Path Resolution

Relative filesystem paths (in log_file, result_dir, temp_dir, custom_tools.config_file, and monitoring.db_path) are resolved to absolute paths relative to the directory containing config.yaml. This behavior occurs after config loading and environment variable overrides are applied.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Configuration

Configuration

Config File Location

Environment Variable Overrides

Full Configuration Reference

Server

Pool

Execution

Workspace

Toolboxes

Custom Tools

Security

Code Checker

Output

Sessions

Monitoring

Path Resolution

Example Configurations

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally