Configuration

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

Note: The section name is determined by splitting on the first underscore after MATLAB_MCP_. Environment variables use uppercase with underscores; they are converted to lowercase section and key names. For example:

• MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines
• MATLAB_MCP_SERVER_LOG_LEVEL → server.log_level

Multi-word sections like code_checker or custom_tools are supported via environment variables by using the lowercase underscore format (e.g., MATLAB_MCP_CODE_CHECKER_ENABLED=true).

Full Configuration Reference

Server

Field	Type	Default	Environment Variable	Description
name	string	"matlab-mcp-server"	MATLAB_MCP_SERVER_NAME	Server name reported to MCP clients
transport	stdio | sse	"stdio"	MATLAB_MCP_SERVER_TRANSPORT	Transport mechanism: stdio for stdio, sse for HTTP Server-Sent Events
host	string	"0.0.0.0"	MATLAB_MCP_SERVER_HOST	Bind address (SSE transport only)
port	integer	8765	MATLAB_MCP_SERVER_PORT	Server port (SSE transport only)
log_level	debug | info | warning | error	"info"	MATLAB_MCP_SERVER_LOG_LEVEL	Logging verbosity level
log_file	string	"./logs/server.log"	MATLAB_MCP_SERVER_LOG_FILE	Log file path (resolved to absolute on startup)
result_dir	string	"./results"	MATLAB_MCP_SERVER_RESULT_DIR	Directory for storing result files (resolved to absolute on startup)
drain_timeout_seconds	integer	300	MATLAB_MCP_SERVER_DRAIN_TIMEOUT_SECONDS	Maximum seconds to wait for running jobs during graceful shutdown

Pool

Field	Type	Default	Environment Variable	Description
min_engines	integer	2	MATLAB_MCP_POOL_MIN_ENGINES	Minimum MATLAB engines to keep warm at all times
max_engines	integer	10	MATLAB_MCP_POOL_MAX_ENGINES	Maximum MATLAB engines to create (capped at 4 on macOS)
scale_down_idle_timeout	integer	900	MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT	Seconds of idle time before scaling down to min_engines
engine_start_timeout	integer	120	MATLAB_MCP_POOL_ENGINE_START_TIMEOUT	Seconds to wait for MATLAB engine to start
health_check_interval	integer	60	MATLAB_MCP_POOL_HEALTH_CHECK_INTERVAL	Seconds between engine health check pings
proactive_warmup_threshold	float	0.8	MATLAB_MCP_POOL_PROACTIVE_WARMUP_THRESHOLD	Pool utilization ratio (0.0–1.0) triggering warmup of additional engines
queue_max_size	integer	50	MATLAB_MCP_POOL_QUEUE_MAX_SIZE	Maximum pending execution requests in queue
matlab_root	string | null	null	MATLAB_MCP_POOL_MATLAB_ROOT	Explicit MATLAB root directory (auto-detected if null)

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

Execution

Field	Type	Default	Environment Variable	Description
sync_timeout	integer	30	MATLAB_MCP_EXECUTION_SYNC_TIMEOUT	Seconds before auto-promoting synchronous execution to async with job polling
max_execution_time	integer	86400	MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME	Hard limit per job in seconds (24 hours = 86400)
workspace_isolation	boolean	true	MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION	Clear workspace between sessions
engine_affinity	boolean	false	MATLAB_MCP_EXECUTION_ENGINE_AFFINITY	Pin session to specific engine for workspace persistence across calls
temp_dir	string	"./temp"	MATLAB_MCP_EXECUTION_TEMP_DIR	Temporary file directory (resolved to absolute on startup)
temp_cleanup_on_disconnect	boolean	true	MATLAB_MCP_EXECUTION_TEMP_CLEANUP_ON_DISCONNECT	Delete temporary files when session ends

sync_timeout: When code runs longer than this duration, the server automatically promotes it to an async job and returns a job_id for polling. Increase this for environments where most code is expected to take 30–60 seconds.

Workspace

Field	Type	Default	Environment Variable	Description
default_paths	list of strings	[]	—	Paths added to MATLAB search path on engine start and after workspace reset
startup_commands	list of strings	["format long"]	—	MATLAB commands executed on each engine start and after workspace reset

Note: Environment variable overrides are not supported for list fields. Use the config file to specify these values.

Toolboxes

Field	Type	Default	Environment Variable	Description
mode	whitelist | blacklist | all	"whitelist"	MATLAB_MCP_TOOLBOXES_MODE	Toolbox visibility mode
list	list of strings	["Signal Processing Toolbox", "Optimization Toolbox", "Statistics and Machine Learning Toolbox", "Image Processing Toolbox"]	—	List of toolboxes to whitelist or blacklist

Mode	Behavior
whitelist	Only listed toolboxes are reported to agents
blacklist	All toolboxes EXCEPT listed ones are reported
all	All installed toolboxes are reported

Note: Environment variable overrides are not supported for the list field. Use the config file to specify toolbox lists.

Custom Tools

Field	Type	Default	Environment Variable	Description
config_file	string	"./custom_tools.yaml"	MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE	Path to YAML file defining user-provided custom MCP tools (resolved to absolute on startup)

See Custom Tools for the full custom tools format.

Security

Field	Type	Default	Environment Variable	Description
blocked_functions_enabled	boolean	true	MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED	Enable blocking of dangerous MATLAB functions
blocked_functions	list of strings	["system", "unix", "dos", "!", "eval", "feval", "evalc", "evalin", "assignin", "perl", "python"]	—	MATLAB functions blocked from execution
max_upload_size_mb	integer	100	MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB	Maximum file upload size in megabytes
require_proxy_auth	boolean	false	MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH	Set to true to acknowledge that SSE transport is behind an authentication proxy

blocked_functions: These MATLAB functions are blocked from execution. The security validator strips string literals and comments before scanning, so disp('system') won't trigger a false positive.

Note: Environment variable overrides are not supported for the blocked_functions list. Use the config file to customize blocked functions.

Code Checker

Field	Type	Default	Environment Variable	Description
enabled	boolean	true	MATLAB_MCP_CODE_CHECKER_ENABLED	Enable code linting via checkcode
auto_check_before_execute	boolean	false	MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE	Automatically run checkcode before every execution
severity_levels	list of strings	["error", "warning"]	—	Severity levels to report (error, warning, info)

Note: Environment variable overrides are not supported for the severity_levels list. Use the config file to customize reported severity levels.

Output

Field	Type	Default	Environment Variable	Description
plotly_conversion	boolean	true	MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION	Convert MATLAB figures to Plotly JSON for interactive display
static_image_format	png | jpg | svg	"png"	MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT	Image format for figure export
static_image_dpi	integer	150	MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI	DPI for raster image exports
thumbnail_enabled	boolean	true	MATLAB_MCP_OUTPUT_THUMBNAIL_ENABLED	Generate thumbnails of figures
thumbnail_max_width	integer	400	MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH	Maximum width in pixels for generated thumbnails
large_result_threshold	integer	10000	MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD	Element count threshold; above this, large tabular/matrix data is saved to file
max_inline_text_length	integer	50000	MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH	Character count threshold; above this, text output is saved to file

Sessions

Field	Type	Default	Environment Variable	Description
max_sessions	integer	50	MATLAB_MCP_SESSIONS_MAX_SESSIONS	Maximum concurrent sessions allowed
session_timeout	integer	3600	MATLAB_MCP_SESSIONS_SESSION_TIMEOUT	Seconds of inactivity before automatic session cleanup
job_retention_seconds	integer	86400	MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS	How long to retain metadata of completed jobs (24 hours = 86400)

Monitoring

Field	Type	Default	Environment Variable	Description
enabled	boolean	true	MATLAB_MCP_MONITORING_ENABLED	Enable metrics collection and monitoring subsystem
sample_interval	integer	10	MATLAB_MCP_MONITORING_SAMPLE_INTERVAL	Seconds between metric samples
retention_days	integer	7	MATLAB_MCP_MONITORING_RETENTION_DAYS	Days to retain historical monitoring data
db_path	string	"./monitoring/metrics.db"	MATLAB_MCP_MONITORING_DB_PATH	SQLite database path for metrics (resolved to absolute on startup)
dashboard_enabled	boolean	true	MATLAB_MCP_MONITORING_DASHBOARD_ENABLED	Enable web dashboard for monitoring
http_port	integer	8766	MATLAB_MCP_MONITORING_HTTP_PORT	Dashboard and health check port (stdio transport only)

Note: Monitoring requires optional dependencies (psutil, uvicorn). Install with:

pip install -e ".[monitoring]"
# or pip install -e ".[dev]"  (dev includes monitoring dependencies)

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