Skip to content

Configuration

Jump to bottom
github-actions[bot] edited this page Apr 3, 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 TD
    A["config.yaml<br/>(optional)"] -->|load_config| B["AppConfig<br/>Pydantic Model"]
    C["Environment<br/>Variables<br/>MATLAB_MCP_*"] -->|_apply_env_overrides| B
    B -->|propagate| D["Server Runtime"]
    D -->|use| E["Pool Manager"]
    D -->|use| F["Session Manager"]
    D -->|use| G["Job Executor"]
    D -->|use| H["Security Validator"]
    D -->|use| I["Output Formatter"]
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

If no config file is found or if the path is None, all defaults are used.

Environment Variable Overrides

Any configuration value can be overridden via environment variables using the pattern MATLAB_MCP_<SECTION>_<KEY>. Environment variables take priority over values in config.yaml.

Naming Convention

For nested configuration like pool.max_engines:

export MATLAB_MCP_POOL_MAX_ENGINES=20

For simple boolean values:

export MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=false
export MATLAB_MCP_MONITORING_ENABLED=true

For integer values, the string is coerced automatically:

export MATLAB_MCP_SERVER_PORT=9000
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

Examples

# Pool scaling
export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16

# Execution timeouts
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
export MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME=3600

# Transport mode
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_PORT=9000

# Security
export MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB=500

# Monitoring
export MATLAB_MCP_MONITORING_ENABLED=false

# Authentication (if using bearer tokens)
export MATLAB_MCP_AUTH_TOKEN=your_token_here

Note: Not all configuration sections support environment variable overrides due to nested structure complexity. Use the config file for complex sections like custom_tools, workspace.default_paths, and security.blocked_functions.

Configuration Schema

Server Configuration

Key Type Default Description
server.name string "matlab-mcp-server" Server name reported to MCP clients
server.transport enum "stdio" Transport mode: stdio (single-user, local) | sse (multi-user, deprecated) | streamablehttp (multi-user, modern)
server.host string "127.0.0.1" Bind address for HTTP/SSE (loopback by default to avoid Windows Firewall UAC; use "0.0.0.0" for remote agents)
server.port integer 8765 Port for HTTP/SSE endpoint
server.log_level enum "info" Logging level: debug | info | warning | error
server.log_file string "./logs/server.log" Path to log file (optional; logs to stderr if omitted)
server.result_dir string "./results" Directory for storing result files and artifacts
server.drain_timeout_seconds integer 300 Max seconds to wait for running jobs during graceful shutdown

Pool Configuration

Key Type Default Description
pool.min_engines integer 2 Minimum MATLAB engines to keep warm at all times
pool.max_engines integer 10 Maximum MATLAB engines to scale up to (capped at 4 on macOS due to MATLAB licensing)
pool.scale_down_idle_timeout integer 900 Seconds of inactivity before scaling down idle engines (15 min)
pool.engine_start_timeout integer 120 Seconds to wait for a MATLAB engine to start
pool.health_check_interval integer 60 Seconds between automatic health checks of engines
pool.proactive_warmup_threshold float 0.8 Pool utilization ratio (0–1) above which extra engines are pre-warmed
pool.queue_max_size integer 50 Maximum pending requests in the acquisition queue
pool.matlab_root string null Explicit MATLAB installation root (auto-detected if null)

Execution Configuration

Key Type Default Description
execution.sync_timeout integer 30 Seconds before auto-promoting code to async job execution
execution.max_execution_time integer 86400 Hard limit per job in seconds (24 hours)
execution.workspace_isolation boolean true Clear workspace between sessions (prevents variable leakage)
execution.engine_affinity boolean false Pin sessions to specific engines for consistency (advanced)
execution.temp_cleanup_on_disconnect boolean true Delete temporary files when a session ends

Workspace Configuration

Key Type Default Description
workspace.default_paths list[string] [] MATLAB search paths added on engine startup (e.g., shared libraries)
workspace.startup_commands list[string] [] MATLAB commands run once per engine (e.g., "format long", "addpath /shared/libs")

Toolbox Configuration

Key Type Default Description
toolboxes.mode enum "all" Filtering mode: all (show all) | whitelist (show only listed) | blacklist (hide listed)
toolboxes.list list[string] [] Toolbox names to whitelist or blacklist (based on mode)

Custom Tools Configuration

Key Type Default Description
custom_tools.config_file string "./custom_tools.yaml" Path to YAML file defining custom MCP tools wrapping MATLAB functions

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 blocking of dangerous MATLAB functions
security.blocked_functions list[string] See below MATLAB functions that cannot be executed
security.max_upload_size_mb integer 100 Maximum file upload size in megabytes
security.require_proxy_auth boolean false For production SSE deployments behind a reverse proxy with auth

Default blocked functions:

security.blocked_functions:
  - "system"      # Execute shell commands
  - "unix"        # Execute Unix commands
  - "dos"         # Execute DOS commands
  - "!"           # Shell escape operator
  - "eval"        # Dynamic code execution
  - "feval"       # Function evaluation
  - "evalc"       # Code evaluation with capture
  - "evalin"      # Evaluation in specific workspace
  - "assignin"    # Variable assignment to other workspaces
  - "perl"        # Execute Perl commands
  - "python"      # Execute Python commands

The security validator strips string literals and comments before scanning, so disp('system') won't trigger a false positive.

Code Checker Configuration

Key Type Default Description
code_checker.enabled boolean true Enable the code checking tool
code_checker.auto_check_before_execute boolean false Run checkcode before every execution (adds latency)
code_checker.severity_levels list[string] ["error", "warning"] Which severity levels to report

Output Configuration

Key Type Default Description
output.plotly_conversion boolean true Convert MATLAB figures to interactive Plotly JSON
output.static_image_format enum "png" Fallback image format: png | jpg | svg
output.static_image_dpi integer 150 DPI for static images
output.thumbnail_enabled boolean true Generate thumbnail images for large figures
output.thumbnail_max_width integer 400 Maximum width of thumbnails in pixels
output.large_result_threshold integer 10000 Elements threshold — save large arrays to file
output.max_inline_text_length integer 50000 Character threshold — save long text output to file

Sessions Configuration

Key Type Default Description
sessions.max_sessions integer 50 Maximum concurrent user sessions
sessions.session_timeout integer 3600 Seconds of inactivity before session cleanup (1 hour)
sessions.job_retention_seconds integer 86400 Duration to keep completed job metadata for polling (24 hours)

Monitoring Configuration

Key Type Default Description
monitoring.enabled boolean true Enable metrics collection and dashboard
monitoring.sample_interval integer 10 Seconds between metric snapshots
monitoring.retention_days integer 7 Days to keep historical metrics in SQLite
monitoring.db_path string "./monitoring/metrics.db" Path to SQLite metrics database
monitoring.dashboard_enabled boolean true Enable web dashboard at /dashboard
monitoring.http_port integer 8766 Port for standalone dashboard HTTP server (stdio transport only)

Note: Monitoring requires optional dependencies:

pip install -e ".[monitoring]"     # Install monitoring extras
# or
pip install -e ".[dev]"            # Install all dev + monitoring extras

HITL (Human-In-The-Loop) Configuration

Key Type Default Description
hitl.enabled boolean false Enable human approval gates for sensitive operations
hitl.protected_functions list[string] [] Function names requiring manual approval before execution
hitl.protect_file_ops boolean false Require approval for upload/delete file operations
hitl.all_execute boolean false Require approval for ALL code execution (overrides protected_functions)

Example:

hitl:
  enabled: true
  protected_functions:
    - "delete"
    - "rmdir"
    - "system"
  protect_file_ops: true
  all_execute: false

Example Configurations

Minimal (Single-User, Local)

server:
  name: "matlab-local"
  transport: "stdio"
  log_level: "info"

pool:
  min_engines: 1
  max_engines: 2

execution:
  sync_timeout: 30
  max_execution_time: 3600

security:
  blocked_functions_enabled: true

Run:

matlab-mcp --config examples/config_minimal.yaml

Multi-User (Shared Server with HTTP)

server:
  name: "matlab-shared"
  transport: "streamablehttp"
  host: "0.0.0.0"
  port: 8765
  log_level: "info"
  log_file: "./logs/server.log"

pool:
  min_engines: 4
  max_engines: 16
  health_check_interval: 30

execution:
  sync_timeout: 30
  max_execution_time: 86400
  workspace_isolation: true
  temp_cleanup_on_disconnect: true

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 500

monitoring:
  enabled: true
  dashboard_enabled: true
  http_port: 8766

sessions:
  max_sessions: 100
  session_timeout: 7200

Run with auth:

export MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token)
matlab-mcp --config examples/config_multiuser.yaml

Production (with HITL approval gates)

server:
  transport: "streamablehttp"
  host: "127.0.0.1"
  port: 8765
  log_level: "warning"

pool:
  min_engines: 8
  max_engines: 32
  matlab_root: "/opt/matlab/r2024a"

execution:
  workspace_isolation: true
  engine_affinity: true

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 1000

hitl:
  enabled: true
  protected_functions:
    - "system"
    - "eval"
    - "delete"
    - "rmdir"
  protect_file_ops: true

monitoring:
  enabled: true
  retention_days: 30
  dashboard_enabled: true

Complete Example Configuration File

# ============================================================================
# MATLAB MCP Server Configuration
# ============================================================================
# This is a comprehensive configuration file with all available options
# and detailed comments. Most values have sensible defaults.

server:
  # User-facing name for this server instance
  name: "matlab-mcp-server"
  
  # Transport mode:
  # - stdio: Single-user, local connections (default, zero network overhead)
  # - sse: Multi-user, Server-Sent Events (deprecated, use streamablehttp)
  # - streamablehttp: Multi-user, Streamable HTTP/JSON-RPC (recommended)
  transport: "stdio"
  
  # HTTP bind address (for sse/streamablehttp transports)
  # - "127.0.0.1": Loopback only, no firewall prompts on Windows
  # - "0.0.0.0": Accept from any network (requires firewall rules)
  host: "127.0.0.1"
  
  # HTTP port (for sse/streamablehttp transports)
  port: 8765
  
  # Logging level: debug | info | warning | error
  log_level: "info"
  
  # Optional log file path (omit to log only to stderr)
  log_file: "./logs/server.log"
  
  # Directory for result files and artifacts
  result_dir: "./results"
  
  # Max seconds to wait for running jobs during graceful shutdown
  drain_timeout_seconds: 300

# ============================================================================
pool:
  # MATLAB engine pool sizing
  
  # Always keep this many engines warm (min=1, default=2)
  min_engines: 2
  
  # Never exceed this many engines (macOS capped at 4, default=10)
  max_engines: 10
  
  # Scale down idle engines after this many seconds (default=900, 15 min)
  scale_down_idle_timeout: 900
  
  # Wait up to this many seconds for a MATLAB engine to start (default=120)
  engine_start_timeout: 120
  
  # Check engine health every N seconds (default=60)
  health_check_interval: 60
  
  # Pre-warm engines when pool utilization exceeds this ratio (0.0–1.0, default=0.8)
  # E.g., if max=10 and threshold=0.8, start warming when 8+ engines are in use
  proactive_warmup_threshold: 0.8
  
  # Max pending acquisition requests before rejecting new code (default=50)
  queue_max_size: 50
  
  # Optional: Explicit MATLAB installation root
  # (auto-detected if null)
  matlab_root: null

# ============================================================================
execution:
  # Code execution and job orchestration
  
  # Seconds before auto-promoting code to async job
  # (short-running code runs sync; longer code becomes async)
  sync_timeout: 30
  
  # Hard limit per job in seconds (86400 = 24 hours)
  max_execution_time: 86400
  
  # Clear workspace between sessions (prevents cross-user leakage)
  workspace_isolation: true
  
  # Pin sessions to specific engines (advanced feature)
  engine_affinity: false
  
  # Delete temporary files when session ends
  temp_cleanup_on_disconnect: true

# ============================================================================
workspace:
  # MATLAB workspace setup
  
  # Paths to add to MATLAB search path on engine startup
  default_paths:
    # - "/shared/custom_libs"
    # - "/shared/data"
  
  # MATLAB commands to run once per engine
  startup_commands:
    # - "format long"
    # - "addpath /shared/libs"

# ============================================================================
toolboxes:
  # Which MATLAB toolboxes to expose to agents
  
  # Mode: all | whitelist | blacklist
  # - all: Expose all installed toolboxes
  # - whitelist: Only expose listed toolboxes
  # - blacklist: Expose all EXCEPT listed toolboxes
  mode: "all"
  
  # Toolbox names (mode-dependent)
  list: []
    # - "Signal Processing Toolbox"
    # - "Optimization Toolbox"
    # - "Statistics and Machine Learning Toolbox"

# ============================================================================
custom_tools:
  # Custom MCP tools wrapping MATLAB functions
  
  # Path to YAML file defining custom tools
  config_file: "./custom_tools.yaml"

# ============================================================================
security:
  # Security constraints and blocking
  
  # Enable/disable function blocking
  blocked_functions_enabled: true
  
  # MATLAB functions that cannot be executed
  # (evaluated after string/comment stripping)
  blocked_functions:
    - "system"      # Shell commands
    - "unix"        # Unix commands
    - "dos"         # DOS commands
    - "!"           # Shell escape
    - "eval"        # Dynamic code execution
    - "feval"       # Function evaluation
    - "evalc"       # Code evaluation with capture
    - "evalin"      # Evaluation in other workspace
    - "assignin"    # Assign to other workspace
    - "perl"        # Execute Perl
    - "python"      # Execute Python
  
  # Max file upload size in megabytes
  max_upload_size_mb: 100
  
  # For production: set true if SSE is behind auth-providing reverse proxy
  require_proxy_auth: false

# ============================================================================
code_checker:
  # MATLAB code quality checking (checkcode/mlint)
  
  # Enable the check_code tool
  enabled: true
  
  # Auto-run checkcode before every execution (adds latency)
  auto_check_before_execute: false
  
  # Report these severity levels: error | warning
  severity_levels:
    - "error"
    - "warning"

# ============================================================================
output:
  # Result formatting and visualization
  
  # Convert MATLAB figures to interactive Plotly JSON
  plotly_conversion: true
  
  # Fallback static image format: png | jpg | svg
  static_image_format: "png"
  
  # DPI for static images
  static_image_dpi: 150
  
  # Generate thumbnail images
  thumbnail_enabled: true
  
  # Max thumbnail width in pixels
  thumbnail_max_width: 400
  
  # Save large arrays (>N elements) to file instead of inline
  large_result_threshold: 10000
  
  # Save long text output (>N chars) to file instead of inline
  max_inline_text_length: 50000

# ============================================================================
sessions:
  # User session management
  
  # Max concurrent sessions
  max_sessions: 50
  
  # Clean up sessions idle for this many seconds (3600 = 1 hour)
  session_timeout: 3600
  
  # Keep completed job metadata for this long (86400 = 24 hours)
  job_retention_seconds: 86400

# ============================================================================
monitoring:
  # Metrics collection and dashboard
  
  # Enable metrics and dashboard
  enabled: true
  
  # Seconds between metric snapshots
  sample_interval: 10
  
  # Days to keep historical metrics in SQLite
  retention_days: 7
  
  # Path to SQLite metrics database
  db_path: "./monitoring/metrics.db"
  
  # Enable web dashboard at /dashboard
  dashboard_enabled: true
  
  # Port for standalone dashboard (stdio transport only)
  http_port: 8766

# ============================================================================
hitl:
  # Human-In-The-Loop approval gates
  # (requires agents to support ctx.elicit() API)
  
  # Enable approval gates
  enabled: false
  
  # Function names requiring approval before execution
  protected_functions: []
    # - "delete"
    # - "rmdir"
    # - "system"
  
  # Require approval for file operations (upload/delete)
  protect_file_ops: false
  
  # Require approval for ALL code execution (overrides protected_functions)
  all_execute: false

Configuration Validation

The server validates all configuration on startup:

matlab-mcp --config config.yaml

If validation fails, you'll see a clear error message:

Error loading configuration:
  pool.max_engines=2 is less than pool.min_engines=4
  
  Fix: Ensure min_engines <= max_engines

Troubleshooting Configuration

"Config file not found"

Make sure config.yaml exists in the current directory or pass an explicit path:

matlab-mcp --config /path/to/config.yaml

Environment variables not taking effect

Check the variable name format: MATLAB_MCP_<SECTION>_<KEY> with all uppercase and underscores:

# Correct:
export MATLAB_MCP_POOL_MAX_ENGINES=20

# Incorrect (won't work):
export matlab_mcp_pool_max_engines=20
export MATLAB_MCP_POOL_MAX_engines=20

Pool not scaling up

Check pool.proactive_warmup_threshold and ensure it's set to trigger warmup:

# Current pool utilization:
matlab-mcp --transport sse   # then check GET /metrics in dashboard

If all engines are busy and max is reached, jobs will queue. Increase max_engines or pool.queue_max_size.

Clone this wiki locally