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.

Configuration System Overview

graph TD
    A["YAML Config File<br/>config.yaml"] -->|Load| B["AppConfig<br/>Pydantic Model"]
    C["Environment Variables<br/>MATLAB_MCP_*"] -->|Override| B
    B -->|Resolve Paths| D["Absolute Paths<br/>Config Ready"]
    D -->|Pass to Components| E["EnginePoolManager"]
    D -->|Pass to Components| F["JobExecutor"]
    D -->|Pass to Components| G["SessionManager"]
    D -->|Pass to Components| H["SecurityValidator"]
    D -->|Pass to Components| I["Monitoring System"]
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_SERVER_LOG_LEVEL=debug
export MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false
export MATLAB_MCP_SESSIONS_MAX_SESSIONS=100

Override Convention: Environment variable names follow the pattern MATLAB_MCP_<SECTION>_<KEY> where:

  • <SECTION> is the top-level config section (e.g., POOL, EXECUTION, SECURITY)
  • <KEY> is the setting name in UPPER_CASE (e.g., MIN_ENGINES, SYNC_TIMEOUT)

Type Coercion: The system automatically converts environment variable strings to the correct type:

  • "true"/"false" → boolean
  • "123" → integer
  • "3.14" → float
  • Everything else → string

Full Configuration Reference

Server

Key Type Default Description
server.name string "matlab-mcp-server" Server name reported to MCP clients
server.transport "stdio" | "sse" "stdio" Transport mechanism: stdio for stdio mode, sse for HTTP streaming
server.host string "0.0.0.0" Bind address (SSE only); use "127.0.0.1" for localhost-only
server.port integer 8765 TCP port (SSE only)
server.log_level "debug" | "info" | "warning" | "error" "info" Logging verbosity
server.log_file string "./logs/server.log" Path to log file; relative paths resolved from config directory
server.result_dir string "./results" Directory for storing execution result files
server.drain_timeout_seconds integer 300 Max seconds to wait for running jobs during graceful shutdown

Environment Variable Examples:

  • MATLAB_MCP_SERVER_TRANSPORT=sse
  • MATLAB_MCP_SERVER_PORT=9000
  • MATLAB_MCP_SERVER_LOG_LEVEL=debug

Pool

Key Type Default Description
pool.min_engines integer 2 Minimum MATLAB engines to keep warm; must be ≤ max_engines
pool.max_engines integer 10 Maximum MATLAB engines (hard ceiling); ⚠️ capped at 4 on macOS due to stability issues
pool.scale_down_idle_timeout integer 900 Seconds an engine idles before being terminated (15 minutes)
pool.engine_start_timeout integer 120 Seconds to wait for MATLAB process to start and respond
pool.health_check_interval integer 60 Seconds between automatic health checks on idle engines
pool.proactive_warmup_threshold float 0.8 Pool utilization ratio (0–1) above which new engines are pre-warmed
pool.queue_max_size integer 50 Maximum pending requests in the acquisition queue
pool.matlab_root string | null null Explicit MATLAB installation path; null for auto-detection

Pool Constraints:

  • min_engines must be ≤ max_engines, or a ValueError is raised
  • macOS: if max_engines > 4, a warning is logged (MATLAB has known concurrency limits on macOS)

Environment Variable Examples:

  • MATLAB_MCP_POOL_MIN_ENGINES=4
  • MATLAB_MCP_POOL_MAX_ENGINES=16
  • MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT=1800

Execution

Key Type Default Description
execution.sync_timeout integer 30 Seconds before auto-promoting blocking code to async job
execution.max_execution_time integer 86400 Hard ceiling on per-job execution time in seconds (24 hours)
execution.workspace_isolation boolean true Clear workspace between sessions to prevent variable leakage
execution.engine_affinity boolean false Pin a session to a single engine (reduces context switching, less scalable)
execution.temp_dir string "./temp" Directory for session-specific temporary files
execution.temp_cleanup_on_disconnect boolean true Delete temp directory when session ends

sync_timeout Guidance:

  • Use 30–60 for typical agents (most code is short-running)
  • Use 5–10 for real-time interactive scenarios
  • Use 300+ for batch processing environments where blocking is acceptable

Environment Variable Examples:

  • MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
  • MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME=172800 (48 hours)
  • MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=true

Workspace

Key Type Default Description
workspace.default_paths list of strings [] Paths to add to MATLAB's search path on engine start
workspace.startup_commands list of strings ["format long"] MATLAB commands to run on engine initialization

Startup Commands Example:

workspace:
  default_paths:
    - "/shared/matlab_libs"
    - "/shared/toolboxes"
  startup_commands:
    - "format long"
    - "set(0, 'DefaultFigureVisible', 'off')"
    - "warning('off', 'MATLAB:dispatcher:UnresolvedFunctionHandle')"

Toolboxes

Key Type Default Description
toolboxes.mode "whitelist" | "blacklist" | "all" "whitelist" How to filter toolbox visibility to agents
toolboxes.list list of strings [] Toolbox names to whitelist/blacklist

Mode Behavior:

  • "whitelist": Only toolboxes in the list are reported via list_toolboxes tool
  • "blacklist": All toolboxes EXCEPT those in the list are reported
  • "all": All installed toolboxes are reported (ignore list)

Example Configuration:

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

Custom Tools

Key Type Default Description
custom_tools.config_file string "./custom_tools.yaml" Path to custom tool definitions (see Custom Tools)

Note: The config file path is resolved relative to the config directory.

Security

Key Type Default Description
security.blocked_functions_enabled boolean true Enable blocking of dangerous MATLAB functions
security.blocked_functions list of strings See below MATLAB functions to block from execution
security.max_upload_size_mb integer 100 Maximum size for upload_data tool in MB
security.require_proxy_auth boolean false Acknowledge that SSE is behind a reverse proxy with auth

Default Blocked Functions:

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

Smart Scanning: The security validator strips string literals and comments before checking for blocked functions. This prevents false positives like disp('The system is working').

Environment Variable Examples:

  • MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false (disable all blocking)
  • MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB=500
  • MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH=true

Code Checker

Key Type Default Description
code_checker.enabled boolean true Enable code linting via MATLAB's checkcode
code_checker.auto_check_before_execute boolean false Run linting before every code execution
code_checker.severity_levels list of strings ["error", "warning"] Report issues at these severity levels

Example:

code_checker:
  enabled: true
  auto_check_before_execute: true  # Lint every submission
  severity_levels: ["error", "warning"]

Output

Key Type Default Description
output.plotly_conversion boolean true Convert MATLAB figures to interactive Plotly JSON
output.static_image_format "png" | "jpg" | "svg" "png" Format for non-Plotly figures
output.static_image_dpi integer 150 DPI for rasterized images (affects file size and quality)
output.thumbnail_enabled boolean true Generate thumbnail images for large outputs
output.thumbnail_max_width integer 400 Max width in pixels for thumbnail
output.large_result_threshold integer 10000 Number of elements above which results are saved to file instead of inlined
output.max_inline_text_length integer 50000 Character limit for inlined text output

Output Logic:

  • Text longer than max_inline_text_length is saved to a file and referenced instead of inlined
  • Arrays/matrices with more than large_result_threshold elements are summarized (type + size)
  • Figures are converted to Plotly JSON if plotly_conversion: true, otherwise exported as static images
  • Thumbnails are generated for large images to keep response sizes manageable

Environment Variable Examples:

  • MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION=true
  • MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI=200
  • MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH=100000

Sessions

Key Type Default Description
sessions.max_sessions integer 50 Maximum concurrent sessions allowed
sessions.session_timeout integer 3600 Seconds of inactivity before a session is cleaned up (1 hour)
sessions.job_retention_seconds integer 86400 Seconds to keep completed job metadata before pruning (24 hours)

Session Lifecycle:

  1. Session created on first request
  2. Session activity timestamp updated on every request
  3. If idle for session_timeout, session is automatically cleaned up
  4. Session temp directory is deleted if execution.temp_cleanup_on_disconnect: true
  5. Job metadata is pruned after job_retention_seconds

Environment Variable Examples:

  • MATLAB_MCP_SESSIONS_MAX_SESSIONS=100
  • MATLAB_MCP_SESSIONS_SESSION_TIMEOUT=7200 (2 hours)
  • MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS=604800 (7 days)

Monitoring

Key Type Default Description
monitoring.enabled boolean true Enable metrics collection and health checks
monitoring.sample_interval integer 10 Seconds between metric samples
monitoring.retention_days integer 7 Days to keep historical metrics before pruning
monitoring.db_path string "./monitoring/metrics.db" SQLite database path for metrics storage
monitoring.dashboard_enabled boolean true Enable web dashboard (stdio transport only)
monitoring.http_port integer 8766 HTTP port for dashboard (stdio transport only)

Monitoring Dependencies: Monitoring requires optional dependencies. Install with:

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

Dashboard Features:

  • Real-time metrics (pool utilization, job throughput, memory, CPU)
  • Historical charts (time-series data for past 24 hours)
  • Event log (job completions, failures, security events)
  • Health status indicator

Environment Variable Examples:

  • MATLAB_MCP_MONITORING_ENABLED=true
  • MATLAB_MCP_MONITORING_SAMPLE_INTERVAL=5
  • MATLAB_MCP_MONITORING_DASHBOARD_ENABLED=true
  • MATLAB_MCP_MONITORING_HTTP_PORT=9000

Complete Example Configuration File

# =========================================================================
# MATLAB MCP Server Configuration
# =========================================================================
#
# All paths can be relative (resolved from config directory) or absolute.
# Every setting can be overridden via environment variables:
#   export MATLAB_MCP_POOL_MAX_ENGINES=20
#   export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
#

# =========================================================================
# Server Configuration
# =========================================================================
server:
  name: "matlab-mcp-server"
  transport: "stdio"           # stdio or 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"
  result_dir: "./results"
  drain_timeout_seconds: 300   # Wait for jobs on shutdown

# =========================================================================
# MATLAB Engine Pool Configuration
# =========================================================================
pool:
  # Engine count
  min_engines: 2               # Always keep warm
  max_engines: 10              # Hard ceiling (max 4 on macOS)
  
  # Timeouts and health
  engine_start_timeout: 120    # Seconds to wait for MATLAB to start
  scale_down_idle_timeout: 900 # 15 min idle before terminating engine
  health_check_interval: 60    # Seconds between health pings
  
  # Auto-scaling
  proactive_warmup_threshold: 0.8  # Utilization ratio for pre-warming
  queue_max_size: 50           # Max pending requests
  
  # MATLAB discovery
  matlab_root: null            # null = auto-detect

# =========================================================================
# Code Execution Configuration
# =========================================================================
execution:
  sync_timeout: 30             # Seconds before auto-promote to async
  max_execution_time: 86400    # 24 hours hard limit
  workspace_isolation: true    # Clear workspace between sessions
  engine_affinity: false       # Pin session to single engine
  temp_dir: "./temp"
  temp_cleanup_on_disconnect: true

# =========================================================================
# MATLAB Workspace Setup
# =========================================================================
workspace:
  default_paths:
    # - "/shared/matlab_libs"
    # - "/shared/data"
  startup_commands:
    - "format long"
    # - "warning('off', 'MATLAB:dispatcher:IncompatibleContext')"

# =========================================================================
# Toolbox Visibility Configuration
# =========================================================================
toolboxes:
  mode: "whitelist"    # whitelist, blacklist, or all
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"
    - "Control System Toolbox"

# =========================================================================
# Custom Tools Configuration
# =========================================================================
custom_tools:
  config_file: "./custom_tools.yaml"

# =========================================================================
# Security Configuration
# =========================================================================
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

# =========================================================================
# Code Quality Checking
# =========================================================================
code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]

# =========================================================================
# Output Formatting
# =========================================================================
output:
  plotly_conversion: true      # Convert MATLAB figures to Plotly
  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

# =========================================================================
# Session Management
# =========================================================================
sessions:
  max_sessions: 50
  session_timeout: 3600        # 1 hour inactivity timeout
  job_retention_seconds: 86400 # 24 hours

# =========================================================================
# Monitoring and Dashboard
# =========================================================================
monitoring:
  enabled: true
  sample_interval: 10          # Seconds between samples
  retention_days: 7            # Historical data retention
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766              # Dashboard port (stdio only)

Configuration by Deployment Type

Minimal Single-User (stdio)

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

Multi-User Server (SSE)

server:
  transport: "sse"
  host: "127.0.0.1"      # Behind reverse proxy
  port: 8765
pool:
  min_engines: 4
  max_engines: 16
  health_check_interval: 30
execution:
  sync_timeout: 60
  max_execution_time: 172800  # 48 hours
sessions:
  max_sessions: 100
  session_timeout: 7200       # 2 hours
security:
  require_proxy_auth: true
monitoring:
  enabled: true
  http_port: 8766

Production with High Availability

server:
  transport: "sse"
  host: "127.0.0.1"
  port: 8765
  log_level: "warning"
pool:
  min_engines: 8
  max_engines: 32
  scale_down_idle_timeout: 600
  health_check_interval: 30
  proactive_warmup_threshold: 0.7
execution:
  sync_timeout: 45
  max_execution_time: 604800  # 7 days
sessions:
  max_sessions: 200
  session_timeout: 14400      # 4 hours
  job_retention_seconds: 604800  # 7 days
security:
  require_proxy_auth: true
  max_upload_size_mb: 500
code_checker:
  enabled: true
  auto_check_before_execute: true
monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 30

Path Resolution

Relative paths in the configuration are resolved relative to the directory containing config.yaml:

project/
├── config.yaml
├── custom_tools.yaml
├── temp/                    ← execution.temp_dir: "./temp"
├── logs/
│   └── server.log          ← server.log_file: "./logs/server.log"
├── results/                ← server.result_dir: "./results"
└── monitoring/
    └── metrics.db          ← monitoring.db_path: "./monitoring/metrics.db"

If you use absolute paths (starting with / on Unix or a drive letter on Windows), they are used as-is:

execution:
  temp_dir: "/mnt/shared/matlab_temp"
monitoring:
  db_path: "/var/lib/matlab-mcp/metrics.db"

Configuration Data Flow

graph LR
    YAML["config.yaml<br/>on disk"]
    ENV["Environment<br/>Variables"]
    LOAD["YAML Loader"]
    OVERRIDE["Env Override<br/>Layer"]
    VALIDATE["Pydantic<br/>Validation"]
    RESOLVE["Path<br/>Resolution"]
    READY["Ready Config<br/>AppConfig"]
    
    YAML -->|Read| LOAD
    LOAD -->|Parsed dict| OVERRIDE
    ENV -->|MATLAB_MCP_*| OVERRIDE
    OVERRIDE -->|Merged dict| VALIDATE
    VALIDATE -->|Type check| RESOLVE
    RESOLVE -->|Absolute paths| READY
Loading

Clone this wiki locally