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.

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

The environment variable naming follows this hierarchy:

  1. Take the YAML path (e.g., pool.max_engines)
  2. Convert to uppercase (e.g., POOL_MAX_ENGINES)
  3. Prepend MATLAB_MCP_ prefix (e.g., MATLAB_MCP_POOL_MAX_ENGINES)

Type Coercion: Integer, boolean, and list values are automatically coerced from string environment variables:

  • "15" → 15 (int)
  • "true" / "false" → True / False (bool)
  • "item1,item2" → ["item1", "item2"] (list, comma-separated)

Configuration Structure

graph TD
    A["AppConfig"] --> B["ServerConfig"]
    A --> C["PoolConfig"]
    A --> D["ExecutionConfig"]
    A --> E["WorkspaceConfig"]
    A --> F["ToolboxesConfig"]
    A --> G["SecurityConfig"]
    A --> H["OutputConfig"]
    A --> I["SessionsConfig"]
    A --> J["MonitoringConfig"]
    A --> K["CustomToolsConfig"]
    A --> L["CodeCheckerConfig"]
    
    B --> B1["name, transport, host, port"]
    B --> B2["log_level, log_file, result_dir"]
    
    C --> C1["min/max_engines, timeouts"]
    C --> C2["health_check_interval, matlab_root"]
    
    D --> D1["sync_timeout, max_execution_time"]
    D --> D2["workspace_isolation, temp_dir"]
    
    F --> F1["mode: whitelist/blacklist/all"]
    F --> F2["list of toolbox names"]
    
    G --> G1["blocked_functions_enabled"]
    G --> G2["blocked_functions list"]
    G --> G3["max_upload_size_mb"]
    
    H --> H1["plotly_conversion, image_format"]
    H --> H2["thumbnail settings, text limits"]
    
    J --> J1["enabled, sample_interval"]
    J --> J2["retention_days, db_path"]
Loading

Configuration Categories

Server Configuration

Option Type Default Environment Variable Description
name string "matlab-mcp-server" MATLAB_MCP_SERVER_NAME Server name reported to MCP clients
transport string "stdio" MATLAB_MCP_SERVER_TRANSPORT stdio (single-user CLI) or sse (multi-user HTTP)
host string "0.0.0.0" MATLAB_MCP_SERVER_HOST Bind address (SSE only) — use 127.0.0.1 for localhost
port integer 8765 MATLAB_MCP_SERVER_PORT TCP port (SSE only)
log_level string "info" MATLAB_MCP_SERVER_LOG_LEVEL debug, info, warning, or error
log_file string "./logs/server.log" MATLAB_MCP_SERVER_LOG_FILE Path to log file
result_dir string "./results" MATLAB_MCP_SERVER_RESULT_DIR Directory for storing large result files
drain_timeout_seconds integer 300 MATLAB_MCP_SERVER_DRAIN_TIMEOUT_SECONDS Max seconds to wait for running jobs during shutdown

Pool Configuration

Option Type Default Environment Variable Description
min_engines integer 2 MATLAB_MCP_POOL_MIN_ENGINES Minimum number of engines to keep warm at startup
max_engines integer 10 MATLAB_MCP_POOL_MAX_ENGINES Maximum engines to spawn (capped at 4 on macOS)
scale_down_idle_timeout integer 900 MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT Seconds idle before scaling down to min_engines (15 min)
engine_start_timeout integer 120 MATLAB_MCP_POOL_ENGINE_START_TIMEOUT Max seconds to wait for MATLAB engine to start
health_check_interval integer 60 MATLAB_MCP_POOL_HEALTH_CHECK_INTERVAL Seconds between periodic health pings
proactive_warmup_threshold float 0.8 MATLAB_MCP_POOL_PROACTIVE_WARMUP_THRESHOLD Pool utilization ratio (0–1) that triggers engine warmup
queue_max_size integer 50 MATLAB_MCP_POOL_QUEUE_MAX_SIZE Maximum pending execution requests in queue
matlab_root string or null null MATLAB_MCP_POOL_MATLAB_ROOT Explicit MATLAB installation path (auto-detected if null)

Pool Scaling Logic:

  • The server starts with min_engines MATLAB processes.
  • If utilization exceeds proactive_warmup_threshold × max_engines, it spawns one new engine (up to max_engines).
  • Idle engines scale down after scale_down_idle_timeout seconds, maintaining at least min_engines.

macOS Note: MATLAB on macOS imposes a hard 4-engine limit due to licensing restrictions. The server will log a warning if configured for more than 4 engines on macOS.

Execution Configuration

Option Type Default Environment Variable Description
sync_timeout integer 30 MATLAB_MCP_EXECUTION_SYNC_TIMEOUT Seconds to wait for code completion before promoting to async job
max_execution_time integer 86400 MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME Hard limit per job in seconds (24 hours)
workspace_isolation boolean true MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION Clear workspace between sessions (clear all; clear global;)
engine_affinity boolean false MATLAB_MCP_EXECUTION_ENGINE_AFFINITY Pin a session to a specific engine (prevents load balancing)
temp_dir string "./temp" MATLAB_MCP_EXECUTION_TEMP_DIR Temporary working directory for session files
temp_cleanup_on_disconnect boolean true MATLAB_MCP_EXECUTION_TEMP_CLEANUP_ON_DISCONNECT Delete session temp files when client disconnects

Hybrid Sync/Async Execution:

  • Code execution starts in the background immediately.
  • The server waits up to sync_timeout seconds for it to complete.
  • If it finishes: result is returned inline with status: "completed".
  • If it times out: execution continues in background, server returns status: "pending" with job_id for polling.

Workspace Configuration

Option Type Default Environment Variable Description
default_paths list of strings [] N/A (use config file) Directories to add to MATLAB path on engine startup
startup_commands list of strings [] N/A (use config file) MATLAB commands to run when engine initializes (e.g., "format long")

Example:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
  startup_commands:
    - "format long"
    - "rng('default')"

Toolboxes Configuration

Option Type Default Environment Variable Description
mode string "all" MATLAB_MCP_TOOLBOXES_MODE whitelist (only listed), blacklist (exclude listed), or all (report all)
list list of strings [] N/A (use config file) Toolbox names to include/exclude based on mode
Mode Behavior
whitelist Only toolboxes in the list are reported to AI agents via list_toolboxes
blacklist All installed toolboxes EXCEPT those in list are reported
all All installed toolboxes are reported (no filtering)

Example (whitelist mode):

toolboxes:
  mode: "whitelist"
  list:
    - "Signal Processing Toolbox"
    - "Image Processing Toolbox"
    - "Optimization Toolbox"

Security Configuration

Option Type Default Environment Variable Description
blocked_functions_enabled boolean true MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED Enable/disable function blocklist enforcement
blocked_functions list of strings (see below) N/A (use config file) MATLAB function names that are blocked from execution
max_upload_size_mb integer 100 MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB Maximum file upload size in megabytes
require_proxy_auth boolean false MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH Flag confirming reverse proxy authentication is configured (SSE only)

Default Blocked Functions:

blocked_functions:
  - "system"        # OS command execution
  - "unix"          # Unix command execution
  - "dos"           # DOS/Windows command execution
  - "!"             # Shell escape operator
  - "eval"          # Dynamic code execution
  - "feval"         # Function evaluation by name string
  - "evalc"         # Evaluate with captured output
  - "evalin"        # Evaluate in specified workspace
  - "assignin"      # Assign variable in specified workspace
  - "perl"          # Perl script execution
  - "python"        # Python script execution
  - "web"           # Open web browser

Smart Scanning: The security validator strips string literals and MATLAB comments before checking for blocked functions. This prevents false positives:

% SAFE — these will NOT be blocked:
disp('system call')              % "system" inside string
msg = "unix-based OS";           % "unix" inside string
% system('ls')                    % "system" inside comment

% BLOCKED:
system('rm -rf /')               % Actual system() call

Output Configuration

Option Type Default Environment Variable Description
plotly_conversion boolean true MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION Convert MATLAB figures to interactive Plotly JSON
static_image_format string "png" MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT Image format for non-Plotly plots: png, jpg, or svg
static_image_dpi integer 150 MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI DPI for rasterized images
thumbnail_enabled boolean true MATLAB_MCP_OUTPUT_THUMBNAIL_ENABLED Generate base64-encoded thumbnail previews
thumbnail_max_width integer 400 MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH Max width in pixels for thumbnail images
large_result_threshold integer 10000 MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD Element count above which results are saved to file
max_inline_text_length integer 50000 MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH Character limit for inline text output

Result Saving Logic:

  • If text output exceeds max_inline_text_length characters, it's saved to a file in result_dir and returned as a file reference.
  • If structured data (arrays, tables) exceeds large_result_threshold elements, it's saved to a .mat file.
  • This keeps responses lean while preserving full data availability.

Sessions Configuration

Option Type Default Environment Variable Description
max_sessions integer 50 MATLAB_MCP_SESSIONS_MAX_SESSIONS Maximum concurrent user sessions
session_timeout integer 3600 MATLAB_MCP_SESSIONS_SESSION_TIMEOUT Seconds of inactivity before session cleanup (1 hour)
job_retention_seconds integer 86400 MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS Duration to keep completed job metadata (24 hours)

Monitoring Configuration

Option Type Default Environment Variable Description
enabled boolean true MATLAB_MCP_MONITORING_ENABLED Enable metrics collection and dashboard
sample_interval integer 10 MATLAB_MCP_MONITORING_SAMPLE_INTERVAL Seconds between metric samples
retention_days integer 7 MATLAB_MCP_MONITORING_RETENTION_DAYS Days to retain historical metrics in SQLite
db_path string "./monitoring/metrics.db" MATLAB_MCP_MONITORING_DB_PATH Path to SQLite metrics database
dashboard_enabled boolean true MATLAB_MCP_MONITORING_DASHBOARD_ENABLED Enable web dashboard at /dashboard
http_port integer 8766 MATLAB_MCP_MONITORING_HTTP_PORT Dashboard HTTP port (stdio transport only)

Note: Monitoring requires optional dependencies. Install with:

pip install -e ".[monitoring]"

Code Checker Configuration

Option Type Default Environment Variable Description
enabled boolean true MATLAB_MCP_CODE_CHECKER_ENABLED Enable the check_code tool
auto_check_before_execute boolean false MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE Run linting on every code execution
severity_levels list of strings ["error", "warning"] N/A (use config file) Issue severities to report: error, warning

Custom Tools Configuration

Option Type Default Environment Variable Description
config_file string "./custom_tools.yaml" MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE Path to external YAML file defining custom tools

See Custom-Tools for the full custom tools schema.

Complete Example Configuration

# ======================================================================
# MATLAB MCP Server — Complete Configuration Example
# ======================================================================

server:
  name: "matlab-mcp-server"
  transport: "stdio"                # stdio | sse
  # SSE settings (ignored if transport is stdio)
  host: "0.0.0.0"
  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
  max_engines: 10
  scale_down_idle_timeout: 900      # 15 minutes
  engine_start_timeout: 120
  health_check_interval: 60
  proactive_warmup_threshold: 0.8
  queue_max_size: 50
  matlab_root: null                 # Auto-detect, or "/path/to/matlab"

execution:
  sync_timeout: 30
  max_execution_time: 86400         # 24 hours
  workspace_isolation: true
  engine_affinity: false
  temp_dir: "./temp"
  temp_cleanup_on_disconnect: true

workspace:
  default_paths:
    - "/shared/libs"
  startup_commands:
    - "format long"
    - "rng('default')"

toolboxes:
  mode: "all"                       # whitelist | blacklist | all
  list: []

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"
    - "web"
  max_upload_size_mb: 100
  require_proxy_auth: false

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels:
    - "error"
    - "warning"

output:
  plotly_conversion: true
  static_image_format: "png"        # png | jpg | svg
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400
  large_result_threshold: 10000
  max_inline_text_length: 50000

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

monitoring:
  enabled: true
  sample_interval: 10
  retention_days: 7
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766

custom_tools:
  config_file: "./custom_tools.yaml"

Data Flow Diagram

graph LR
    A["Config File (YAML)"] -->|load_config| B["AppConfig"]
    C["Env Vars (MATLAB_MCP_*)"] -->|override| B
    B --> D["ServerConfig"]
    B --> E["PoolConfig"]
    B --> F["ExecutionConfig"]
    B --> G["SecurityConfig"]
    B --> H["OutputConfig"]
    D --> I["MCP Server Transport"]
    E --> J["Engine Pool Manager"]
    F --> K["Job Executor"]
    G --> L["Security Validator"]
    H --> M["Result Formatter"]
    
    style A fill:#e1f5ff
    style C fill:#e1f5ff
    style B fill:#fff3e0
    style I fill:#f3e5f5
    style J fill:#f3e5f5
    style K fill:#f3e5f5
    style L fill:#f3e5f5
    style M fill:#f3e5f5
Loading

Common Configuration Scenarios

Scenario 1: Local Development (stdio)

server:
  transport: "stdio"
  log_level: "debug"

pool:
  min_engines: 1
  max_engines: 2
  health_check_interval: 30

execution:
  sync_timeout: 30
  workspace_isolation: true

monitoring:
  enabled: false  # Reduces overhead

Scenario 2: Multi-User Server (SSE)

server:
  transport: "sse"
  host: "127.0.0.1"          # Behind reverse proxy only
  port: 8765
  log_level: "info"

pool:
  min_engines: 4
  max_engines: 16
  scale_down_idle_timeout: 600

execution:
  sync_timeout: 60

security:
  require_proxy_auth: true   # Acknowledges reverse proxy auth
  max_upload_size_mb: 500

sessions:
  max_sessions: 100
  session_timeout: 1800      # 30 minutes

monitoring:
  enabled: true
  sample_interval: 5         # More frequent sampling
  retention_days: 30         # Keep longer history

Scenario 3: Compute-Heavy Batch Processing

pool:
  min_engines: 8
  max_engines: 32
  scale_down_idle_timeout: 120  # Aggressive scale-down

execution:
  sync_timeout: 120          # Longer timeout for complex computations
  max_execution_time: 604800 # 7 days

output:
  max_inline_text_length: 1000000  # Keep large results inline
  large_result_threshold: 1000000

sessions:
  session_timeout: 86400     # 24 hours
  job_retention_seconds: 604800  # 7 days

Environment Variable Examples

# Override pool configuration
export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=20
export MATLAB_MCP_POOL_MATLAB_ROOT="/opt/matlab/R2024a"

# Change transport and port
export MATLAB_MCP_SERVER_TRANSPORT=sse
export MATLAB_MCP_SERVER_PORT=9000
export MATLAB_MCP_SERVER_HOST=0.0.0.0

# Increase timeouts for heavy computation
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=120
export MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME=604800

# Enable debug logging
export MATLAB_MCP_SERVER_LOG_LEVEL=debug

# Security settings
export MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB=500
export MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH=true

# Start the server
matlab-mcp --config ./config.yaml

Validation & Constraints

The configuration system enforces the following constraints:

Constraint Behavior
min_engines > max_engines Error at startup; adjust config
max_engines > 4 on macOS Warning logged; server still respects config but may fail
sync_timeout < 0 Treated as infinite (no auto-promotion)
session_timeout < 1 Treated as 1 second minimum
max_upload_size_mb < 1 Disables uploads (size check always fails)
Relative paths in temp_dir, result_dir, etc. Resolved to absolute paths based on config file location

Clone this wiki locally