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

Convention: The section name is determined by splitting on the first underscore after MATLAB_MCP_. For example:

  • MATLAB_MCP_POOL_MAX_ENGINES → pool.max_engines
  • MATLAB_MCP_SERVER_LOG_LEVEL → server.log_level
  • MATLAB_MCP_EXECUTION_SYNC_TIMEOUT → execution.sync_timeout

Type Coercion: Environment variables are automatically converted to the appropriate type (int, float, bool, or string).

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 (resolved to absolute path at startup)
  result_dir: "./results"          # Where to store result files (resolved to absolute path at startup)
  drain_timeout_seconds: 300       # Max wait for running jobs during graceful shutdown
Field Type Default Description
name string "matlab-mcp-server" Server identifier for MCP clients
transport "stdio" | "sse" "stdio" Communication protocol
host string "0.0.0.0" Bind address for SSE transport
port integer 8765 Listen port for SSE transport
log_level "debug" | "info" | "warning" | "error" "info" Logging verbosity
log_file string "./logs/server.log" Log output file path
result_dir string "./results" Directory for storing result files
drain_timeout_seconds integer 300 Graceful shutdown timeout for pending jobs

Environment Variables: MATLAB_MCP_SERVER_*

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 warm engines to maintain
max_engines integer 10 Maximum concurrent engines (macOS capped at 4)
scale_down_idle_timeout integer 900 Idle time (seconds) before scaling down
engine_start_timeout integer 120 Wait time (seconds) for MATLAB process startup
health_check_interval integer 60 Interval (seconds) between health checks
proactive_warmup_threshold float 0.8 Utilization ratio (0–1) triggering warmup
queue_max_size integer 50 Maximum queued execution requests
matlab_root string | null null Explicit MATLAB installation path, or auto-detect

Environment Variables: MATLAB_MCP_POOL_*

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
Field Type Default Description
sync_timeout integer 30 Timeout (seconds) before auto-promoting to async job
max_execution_time integer 86400 Hard limit (seconds) per job execution
workspace_isolation boolean true Clear workspace between client sessions
engine_affinity boolean false Pin session to same engine for workspace persistence
temp_dir string "./temp" Temporary file storage directory
temp_cleanup_on_disconnect boolean true Delete session temp files on disconnect

Environment Variables: MATLAB_MCP_EXECUTION_*

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

engine_affinity: When enabled, a client session is pinned to a specific engine, allowing workspace variables to persist across multiple executions. When disabled, each execution may run on a different engine with a clean workspace.

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"
Field Type Default Description
default_paths string[] [] Directories to add to MATLAB path on startup
startup_commands string[] ["format long"] MATLAB commands to run on engine start and after workspace reset

Environment Variables: Not applicable (use config file)

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 string[] [] Toolbox names to whitelist or blacklist

Environment Variables: Not applicable (use config file)

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
Field Type Default Description
config_file string "./custom_tools.yaml" Path to custom tools YAML definition file

Environment Variables: MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE

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 function blocklist enforcement
blocked_functions string[] See default list MATLAB functions blocked from execution
max_upload_size_mb integer 100 Maximum allowed file upload size in MB
require_proxy_auth boolean false Acknowledge SSE is behind authentication proxy

Environment Variables: MATLAB_MCP_SECURITY_* (except blocked_functions list—use config file)

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"]
Field Type Default Description
enabled boolean true Enable code checker tool
auto_check_before_execute boolean false Automatically run checkcode before each execution
severity_levels string[] ["error", "warning"] Severity levels to report

Environment Variables: MATLAB_MCP_CODE_CHECKER_*

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" Format for static figure export
static_image_dpi integer 150 DPI for rasterized figures
thumbnail_enabled boolean true Generate figure thumbnails
thumbnail_max_width integer 400 Maximum pixel width for thumbnails
large_result_threshold integer 10000 Element count threshold for saving tabular data to file
max_inline_text_length integer 50000 Character count threshold for saving text output to file

Environment Variables: MATLAB_MCP_OUTPUT_*

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 concurrent client sessions
session_timeout integer 3600 Inactivity timeout (seconds) before cleanup
job_retention_seconds integer 86400 Retention time (seconds) for completed job metadata

Environment Variables: MATLAB_MCP_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 storage
sample_interval integer 10 Metric sampling interval (seconds)
retention_days integer 7 Data retention period (days)
db_path string "./monitoring/metrics.db" SQLite metrics database path
dashboard_enabled boolean true Enable web dashboard (stdio transport only)
http_port integer 8766 Dashboard HTTP port (stdio transport only)

Environment Variables: MATLAB_MCP_MONITORING_*

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