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

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 or custom_tools 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

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

macOS Note: MATLAB on macOS has a 4-engine limit. The server will log a warning if max_engines > 4 on macOS but still respects 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

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
    - "format long"

Toolboxes

toolboxes:
  mode: "whitelist"                # whitelist | blacklist | all
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"
Mode Behavior
whitelist Only listed toolboxes are reported to agents
blacklist All toolboxes EXCEPT listed ones are reported
all All installed toolboxes are reported

Custom Tools

custom_tools:
  config_file: "./custom_tools.yaml"  # Path to custom tools YAML

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

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.

Code Checker

code_checker:
  enabled: true
  auto_check_before_execute: false  # Run checkcode before every execution
  severity_levels: ["error", "warning"]

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

Sessions

sessions:
  max_sessions: 50
  session_timeout: 3600            # Seconds of inactivity before cleanup (1h)
  job_retention_seconds: 86400     # Keep completed job metadata for 24h

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)

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