Skip to content

Configuration

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

graph LR
    A["config.yaml"] -->|Load| B["AppConfig"]
    C["Env vars<br/>MATLAB_MCP_*"] -->|Override| B
    B -->|Validate| D["ServerConfig"]
    B -->|Validate| E["PoolConfig"]
    B -->|Validate| F["ExecutionConfig"]
    B -->|Validate| G["SecurityConfig"]
    B -->|Validate| H["OutputConfig"]
    B -->|Validate| I["MonitoringConfig"]
    D --> J["FastMCP Server"]
    E --> K["Engine Pool"]
    F --> L["Job Executor"]
    G --> M["Security Validator"]
    H --> N["Result Formatter"]
    I --> O["Metrics Collector"]
Loading

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
export MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION=false
export MATLAB_MCP_MONITORING_ENABLED=true

Environment Variable Naming Convention:

  • Prefix: MATLAB_MCP_
  • Section name: uppercase with underscores (e.g., POOL, EXECUTION, SECURITY)
  • Key name: uppercase with underscores
  • Format: MATLAB_MCP_<SECTION>_<KEY>
  • Type coercion: integers and booleans are automatically converted
  • Multi-word sections like code_checker and custom_tools cannot be overridden via env vars (use the config file instead)

Full Configuration Reference

Server Configuration

Key Type Default Description
server.name string "matlab-mcp-server" Server name reported to MCP clients
server.transport "stdio" | "sse" "stdio" Communication transport: stdio for single user (default), SSE for multi-user
server.host string "0.0.0.0" Bind address for SSE transport (ignored for stdio)
server.port integer 8765 Port for SSE transport (ignored for stdio)
server.log_level "debug" | "info" | "warning" | "error" "info" Logging verbosity level
server.log_file string "./logs/server.log" Log file path (relative paths resolved from config directory)
server.result_dir string "./results" Directory for storing large result files
server.drain_timeout_seconds integer 300 Max seconds to wait for running jobs during graceful shutdown

Environment Variable Examples:

export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_PORT=9000
export MATLAB_MCP_SERVER_LOG_LEVEL=debug

Pool Configuration

Key Type Default Description
pool.min_engines integer 2 Minimum number of MATLAB engines to keep running (warm pool)
pool.max_engines integer 10 Maximum number of MATLAB engines allowed (hard ceiling)
pool.scale_down_idle_timeout integer 900 Seconds of inactivity before scaling down idle engines beyond minimum
pool.engine_start_timeout integer 120 Seconds to wait for a MATLAB engine to start before timing out
pool.health_check_interval integer 60 Seconds between engine health checks (ping + restart if needed)
pool.proactive_warmup_threshold float 0.8 Utilization ratio (0–1) at which to proactively warm up new engines
pool.queue_max_size integer 50 Maximum pending requests in execution queue before rejecting new submissions
pool.matlab_root string | null null Explicit MATLAB installation path; auto-detected if null

Constraints Validated:

  • min_engines ≤ max_engines (raises error if violated)
  • On macOS: warning logged if max_engines > 4 (known stability limit)

Environment Variable Examples:

export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16
export MATLAB_MCP_POOL_ENGINE_START_TIMEOUT=180

Execution Configuration

Key Type Default Description
execution.sync_timeout integer 30 Seconds to wait for synchronous execution before promoting to async job
execution.max_execution_time integer 86400 Hard time limit per job in seconds (24 hours = 86400)
execution.workspace_isolation boolean true Clear workspace between sessions (security feature)
execution.engine_affinity boolean false Pin a session to the same engine for consistency (ignores pool load balancing)
execution.temp_dir string "./temp" Temporary directory for session files and uploads
execution.temp_cleanup_on_disconnect boolean true Delete temp files when a session ends

sync_timeout Behavior:

  • Code completes within timeout → returns result inline with "status": "completed"
  • Code exceeds timeout → auto-promoted to background job, returns "status": "pending" with job_id
  • Increase this for workloads expected to run 30–60 seconds synchronously

Environment Variable Examples:

export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
export MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=false
export MATLAB_MCP_EXECUTION_TEMP_DIR=/mnt/shared/temp

Workspace Configuration

Key Type Default Description
workspace.default_paths list[string] [] Directories to add to MATLAB path on engine start
workspace.startup_commands list[string] ["format long"] MATLAB commands to run on each engine start

Example:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:
    - "format long"
    - "set(0, 'defaultFigureVisible', 'off')"

Toolboxes Configuration

Key Type Default Description
toolboxes.mode "whitelist" | "blacklist" | "all" "whitelist" Toolbox visibility mode
toolboxes.list list[string] [] Toolbox names for whitelist/blacklist mode
Mode Behavior
whitelist Only listed toolboxes are visible to agents; others are hidden
blacklist All toolboxes EXCEPT listed ones are visible
all All installed toolboxes are visible

Example (whitelist important toolboxes):

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

Custom Tools Configuration

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

See Custom Tools for the full custom tools format and examples.

Security Configuration

Key Type Default Description
security.blocked_functions_enabled boolean true Enable/disable the blocked functions filter
security.blocked_functions list[string] See below MATLAB functions that are blocked from execution
security.max_upload_size_mb integer 100 Maximum file upload size in MB
security.require_proxy_auth boolean false Acknowledge reverse proxy authentication is in place (SSE deployments)

Default Blocked Functions:

security:
  blocked_functions:
    - "system"      # OS command execution
    - "unix"        # Unix command execution
    - "dos"         # DOS/Windows command execution
    - "!"           # Shell escape operator
    - "eval"        # Evaluate string as code
    - "feval"       # Call function by name string
    - "evalc"       # Evaluate and capture
    - "evalin"      # Evaluate in caller workspace
    - "assignin"    # Assign in caller workspace
    - "perl"        # Execute Perl scripts
    - "python"      # Execute Python scripts

Smart Scanning:

  • String literals are stripped before checking (no false positives for disp('system'))
  • Comments are stripped before checking (no false positives for % system('cmd'))
  • Word boundaries enforced (e.g., systematic doesn't match system)

Security Note for SSE: When using SSE transport in production, set require_proxy_auth: true to suppress security warnings. This acknowledges that you've deployed the server behind a reverse proxy with proper authentication.

Environment Variable Examples:

export MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false
export MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB=500
export MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH=true

Code Checker Configuration

Key Type Default Description
code_checker.enabled boolean true Enable/disable code linting via checkcode
code_checker.auto_check_before_execute boolean false Run linting before each code execution
code_checker.severity_levels list[string] ["error", "warning"] Severity levels to report ("error", "warning", "info")

Example:

code_checker:
  enabled: true
  auto_check_before_execute: true  # Lint before running
  severity_levels: ["error", "warning"]  # Skip info-level issues

Output Configuration

Key Type Default Description
output.plotly_conversion boolean true Convert MATLAB figures to interactive Plotly JSON format
output.static_image_format "png" | "jpg" | "svg" "png" Format for static image exports
output.static_image_dpi integer 150 DPI for rasterized image output (PNG/JPG)
output.thumbnail_enabled boolean true Generate thumbnail previews for large images
output.thumbnail_max_width integer 400 Maximum width in pixels for thumbnails
output.large_result_threshold integer 10000 Number of array elements before saving results to file instead of returning inline
output.max_inline_text_length integer 50000 Maximum characters of text before saving to file

Behavior:

  • Results exceeding large_result_threshold or max_inline_text_length are saved to result_dir and referenced by path
  • Plotly conversion creates interactive figure.json files that render in agent UIs
  • Thumbnails reduce bandwidth for image-heavy workflows

Environment Variable Examples:

export MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION=false
export MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD=50000
export MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH=600

Sessions Configuration

Key Type Default Description
sessions.max_sessions integer 50 Maximum number of concurrent sessions allowed
sessions.session_timeout integer 3600 Seconds of inactivity before auto-closing a session (1 hour = 3600)
sessions.job_retention_seconds integer 86400 Seconds to retain completed job metadata (1 day = 86400)

Cleanup Behavior:

  • Sessions inactive for session_timeout are automatically closed and their temp files deleted
  • Completed job metadata (status, results) is pruned after job_retention_seconds to prevent unbounded memory growth
  • Active sessions remain open indefinitely as long as they receive requests

Environment Variable Examples:

export MATLAB_MCP_SESSIONS_MAX_SESSIONS=100
export MATLAB_MCP_SESSIONS_SESSION_TIMEOUT=7200

Monitoring Configuration

Key Type Default Description
monitoring.enabled boolean true Enable/disable metrics collection and dashboard
monitoring.sample_interval integer 10 Seconds between metric samples (pool, jobs, system stats)
monitoring.retention_days integer 7 Days to retain historical metrics in the database
monitoring.db_path string "./monitoring/metrics.db" SQLite database path for time-series metrics
monitoring.dashboard_enabled boolean true Enable web dashboard UI (requires monitoring.enabled=true)
monitoring.http_port integer 8766 HTTP port for dashboard (ignored for SSE transport, which uses same port)

Dependencies: Monitoring requires optional dependencies. Install with:

pip install -e ".[monitoring]"
# or
pip install -e ".[dev]"  # dev includes monitoring + other dev tools

Dashboard Features:

  • Real-time engine pool utilization gauge
  • Historical execution time trends
  • Job completion/failure rates
  • Session and error counters
  • System memory/CPU stats
  • Event log with filtering

Environment Variable Examples:

export MATLAB_MCP_MONITORING_ENABLED=true
export MATLAB_MCP_MONITORING_RETENTION_DAYS=30
export MATLAB_MCP_MONITORING_DASHBOARD_ENABLED=false

Complete Example Configuration File

# MATLAB MCP Server Configuration
# All relative paths are resolved relative to this config file's directory

server:
  name: "matlab-mcp-server"
  transport: "stdio"                # stdio for single-user, sse for multi-user
  host: "0.0.0.0"                   # SSE only; for production use 127.0.0.1 + reverse proxy
  port: 8765
  log_level: "info"                 # debug | info | warning | error
  log_file: "./logs/server.log"
  result_dir: "./results"
  drain_timeout_seconds: 300

pool:
  min_engines: 2                     # Always keep warm
  max_engines: 10                    # Hard ceiling (4 on macOS)
  scale_down_idle_timeout: 900       # 15 minutes
  engine_start_timeout: 120          # 2 minutes
  health_check_interval: 60          # 1 minute
  proactive_warmup_threshold: 0.8    # Warmup when >80% utilized
  queue_max_size: 50
  matlab_root: null                  # Auto-detect, or set explicit path

execution:
  sync_timeout: 30                   # Promote to async after 30 seconds
  max_execution_time: 86400          # Hard limit: 24 hours
  workspace_isolation: true          # Clear workspace between sessions
  engine_affinity: false             # Don't pin sessions to engines
  temp_dir: "./temp"
  temp_cleanup_on_disconnect: true

workspace:
  default_paths:                     # Added to path on engine start
    - "./shared_libs"
  startup_commands:                  # Run on each engine start
    - "format long"
    - "set(0, 'defaultFigureVisible', 'off')"

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

custom_tools:
  config_file: "./custom_tools.yaml"

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 to true for production SSE + reverse proxy

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]

output:
  plotly_conversion: true            # Convert MATLAB figures to interactive Plotly
  static_image_format: "png"         # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000      # Save to file if >10k elements
  max_inline_text_length: 50000      # Save to file if >50k chars

sessions:
  max_sessions: 50
  session_timeout: 3600              # 1 hour
  job_retention_seconds: 86400       # 24 hours

monitoring:
  enabled: true                      # Requires optional deps: pip install -e ".[monitoring]"
  sample_interval: 10                # Seconds between samples
  retention_days: 7
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766                    # Dashboard port (stdio only)

Example Configurations

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

Minimal Configuration (Single User, Local)

server:
  transport: "stdio"
pool:
  min_engines: 1
  max_engines: 2
execution:
  sync_timeout: 30
monitoring:
  enabled: false

Multi-User Configuration (Team Server)

server:
  transport: "sse"
  host: "127.0.0.1"
  port: 8765
pool:
  min_engines: 4
  max_engines: 16
  scale_down_idle_timeout: 600
execution:
  sync_timeout: 60
  max_execution_time: 3600
sessions:
  max_sessions: 100
  session_timeout: 7200
security:
  blocked_functions_enabled: true
  require_proxy_auth: true
monitoring:
  enabled: true
  retention_days: 30

Path Resolution

All relative filesystem paths in the configuration are resolved relative to the directory containing config.yaml. For example:

execution:
  temp_dir: "./temp"          # → {config_dir}/temp
server:
  log_file: "./logs/app.log"  # → {config_dir}/logs/app.log

This ensures consistent behavior whether the server is started from different working directories.

Type Coercion for Environment Variables

When setting config values via environment variables, the system automatically coerces types:

# Integer
export MATLAB_MCP_POOL_MAX_ENGINES=20          # → 20 (int)

# Boolean (case-insensitive: true, false, yes, no, 1, 0)
export MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=false  # → False (bool)
export MATLAB_MCP_MONITORING_ENABLED=1                 # → True (bool)

# String (default)
export MATLAB_MCP_SERVER_LOG_LEVEL=debug       # → "debug" (str)

Strings don't need quotes in the shell; they're quoted automatically by the config loader.

Clone this wiki locally