Skip to content

Configuration

Jump to bottom
github-actions[bot] edited this page Mar 18, 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

Note: The section name is determined by splitting on the first underscore after MATLAB_MCP_. This means single-word sections work as expected (e.g., MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines), but multi-word section names like code_checker cannot be overridden via environment variables. Use the config file for those sections instead.

Full Configuration Reference

Server

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

Environment overrides: MATLAB_MCP_SERVER_* (e.g., MATLAB_MCP_SERVER_PORT, MATLAB_MCP_SERVER_LOG_LEVEL)

Pool

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 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 number of warm engines to maintain
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 engines
engine_start_timeout integer 120 Seconds to wait for MATLAB process to start
health_check_interval integer 60 Seconds between health check pings
proactive_warmup_threshold float 0.8 Utilization ratio (0–1) that triggers proactive engine warmup
queue_max_size integer 50 Maximum number of pending requests in execution queue
matlab_root string or null null Explicit MATLAB installation path, or null to auto-detect

Environment overrides: MATLAB_MCP_POOL_* (e.g., MATLAB_MCP_POOL_MIN_ENGINES, MATLAB_MCP_POOL_MAX_ENGINES)

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

Execution

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
  temp_cleanup_on_disconnect: true  # Delete temp files when session ends
Field Type Default Description
sync_timeout integer 30 Seconds before auto-promoting long-running code to async job
max_execution_time integer 86400 Hard limit per job in seconds (24 hours)
workspace_isolation boolean true Clear workspace between sessions
engine_affinity boolean false Pin session to same engine for workspace persistence
temp_dir string "./temp" Temporary file directory (resolved relative to config directory)
temp_cleanup_on_disconnect boolean true Delete temporary files when session closes

Environment overrides: MATLAB_MCP_EXECUTION_* (e.g., MATLAB_MCP_EXECUTION_SYNC_TIMEOUT, MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME)

sync_timeout: When code runs longer than this, 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

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 array of strings [] Paths added to MATLAB path on engine start and workspace reset
startup_commands array of strings ["format long"] MATLAB commands executed on each engine start and after workspace reset

Environment overrides: Not supported via environment variables (multi-word section name). Use config file instead.

Toolboxes

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" Toolbox filtering mode
list array of strings [] Toolbox names 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

Environment overrides: Not supported via environment variables (multi-word section name). Use config file instead.

Custom Tools

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

Environment overrides: Not supported via environment variables (multi-word section name). Use config file instead.

See Custom Tools for the full custom tools format.

Security

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         # Set true for production SSE deployments
Field Type Default Description
blocked_functions_enabled boolean true Enable blocking of dangerous functions
blocked_functions array of strings See above MATLAB functions to block from execution
max_upload_size_mb integer 100 Maximum file upload size in megabytes
require_proxy_auth boolean false Acknowledge SSE is behind authentication proxy

Environment overrides: MATLAB_MCP_SECURITY_* (e.g., MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB)

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

Code Checker

code_checker:
  enabled: true
  auto_check_before_execute: false  # Run checkcode before every execution
  severity_levels: ["error", "warning"]
Field Type Default Description
enabled boolean true Enable code checker tool
auto_check_before_execute boolean false Automatically run code checker before every execution
severity_levels array of strings ["error", "warning"] Severity levels to report

Environment overrides: Not supported via environment variables (multi-word section name). Use config file instead.

Output

output:
  plotly_conversion: true           # Convert MATLAB figures to Plotly JSON
  static_image_format: "png"        # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000     # Elements — save large results to file
  max_inline_text_length: 50000     # Chars — save long text to file
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 exports
static_image_dpi integer 150 DPI for rasterized images
thumbnail_enabled boolean 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 to save tabular/matrix data to file
max_inline_text_length integer 50000 Character count above which to save text output to file

Environment overrides: MATLAB_MCP_OUTPUT_* (e.g., MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI)

Sessions

sessions:
  max_sessions: 50
  session_timeout: 3600             # Seconds of inactivity before cleanup (1h)
  job_retention_seconds: 86400      # Keep completed job metadata for 24h
Field Type Default Description
max_sessions integer 50 Maximum number of concurrent sessions
session_timeout integer 3600 Seconds of inactivity before automatic session cleanup
job_retention_seconds integer 86400 How long to keep completed job metadata (in seconds)

Environment overrides: MATLAB_MCP_SESSIONS_* (e.g., MATLAB_MCP_SESSIONS_MAX_SESSIONS)

Monitoring

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

Environment overrides: MATLAB_MCP_MONITORING_* (e.g., MATLAB_MCP_MONITORING_SAMPLE_INTERVAL)

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

Clone this wiki locally