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.

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 configuration value can be overridden via environment variables 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=streamablehttp
export MATLAB_MCP_SERVER_PORT=9000
export MATLAB_MCP_AUTH_TOKEN=your_64_char_hex_token
export MATLAB_MCP_HITL_ENABLED=true

Environment Variable Naming Convention:

  • Prefix: MATLAB_MCP_
  • Section name (from YAML): POOL, SERVER, EXECUTION, SECURITY, AUTH, HITL, etc.
  • Field name (from YAML): MIN_ENGINES, PORT, SYNC_TIMEOUT, ENABLED, etc.
  • Pattern: MATLAB_MCP_<SECTION>_<KEY>=value
  • Special case: Boolean values are coerced from "true"/"false" strings automatically

Note: Multi-word section names like custom_tools cannot be overridden via environment variables. Use the config file for those sections instead.

Full Configuration Reference

Server Configuration

Key Type Default Description
server.name string "matlab-mcp-server" Server name reported to MCP clients in capability handshake
server.transport enum "stdio" Transport mode: "stdio" (single local agent), "sse" (deprecated—multi-agent over SSE), "streamablehttp" (recommended—multi-agent over HTTP)
server.host string "127.0.0.1" Bind address for HTTP/SSE (no firewall prompts on Windows 10 with loopback). Set to "0.0.0.0" for remote agent access (requires firewall exception or reverse proxy with auth).
server.port integer 8765 Port for HTTP/SSE transport. Must be >1024 for non-admin deployments.
server.stateless_http boolean false When true, each HTTP request gets its own ephemeral temp directory (no session affinity). Enable for load-balanced deployments where requests may hit different server instances.
server.log_level enum "info" Logging level: "debug", "info", "warning", "error"
server.log_file string null Log file path. If null, logs go to stdout only. Create ./logs/ directory manually if specified.
server.result_dir string "./results" Directory for saving large result files (>threshold) and execution artifacts.
server.drain_timeout_seconds integer 300 Max seconds to wait for running jobs before server shutdown (graceful drain).

Transport Selection Guide:

graph TD
    A["Choose Transport"] --> B{Local or Remote?}
    B -->|Local, single agent| C["stdio"]
    B -->|Remote or multi-agent| D{HTTP preferred?}
    D -->|Yes, modern agents| E["streamablehttp (RECOMMENDED)"]
    D -->|Legacy agents only| F["sse (DEPRECATED)"]
    
    C --> C1["✓ No auth needed<br/>✓ No firewall issues<br/>✓ Zero latency<br/>✗ One agent at a time"]
    E --> E1["✓ Multi-agent support<br/>✓ Stateless mode for scaling<br/>✓ Bearer token auth<br/>✓ Modern MCP standard"]
    F --> F1["⚠ Deprecated in v2.0<br/>✓ Still functional<br/>✗ No new agent support<br/>✗ Requires reverse proxy for auth"]
Loading

Example Server Configurations:

# Development: single local agent, stdio
server:
  transport: "stdio"

# Multi-user: streamable HTTP with local binding (Windows 10 friendly)
server:
  transport: "streamablehttp"
  host: "127.0.0.1"
  port: 8765

# Production: streamable HTTP with stateless mode (load-balanced cluster)
server:
  transport: "streamablehttp"
  host: "0.0.0.0"
  port: 8765
  stateless_http: true

Pool Configuration

Key Type Default Description
pool.min_engines integer 2 Minimum number of warm MATLAB engines. Pool maintains at least this many, even when idle.
pool.max_engines integer 10 Maximum number of engines. Pool never exceeds this. macOS limit: 4 engines max. Server logs a warning if configured higher on macOS.
pool.scale_down_idle_timeout integer 900 Seconds (900 = 15 min) before idle engines beyond min_engines are shut down and released. Reduces resource consumption during idle periods.
pool.engine_start_timeout integer 120 Seconds to wait for MATLAB to start a new engine before timeout. Increase if MATLAB startup is slow on your system.
pool.health_check_interval integer 60 Seconds between health checks. Server periodically pings engines; unhealthy ones are replaced.
pool.proactive_warmup_threshold float 0.8 Utilization ratio (0.0–1.0) above which the pool proactively starts a new engine. Set to 0.8 to start warming when 80% of engines are busy.
pool.queue_max_size integer 50 Maximum pending requests in the job queue. Requests beyond this return "pool busy" errors.
pool.matlab_root string or null null Explicit path to MATLAB installation. If null, auto-detection searches standard locations. Set if auto-detection fails or multiple MATLAB versions are installed.

Example Pool Configurations:

# Small deployment (1–2 agents)
pool:
  min_engines: 1
  max_engines: 4
  health_check_interval: 120

# Large deployment (10+ agents, many long-running jobs)
pool:
  min_engines: 4
  max_engines: 32
  health_check_interval: 30
  proactive_warmup_threshold: 0.7

# macOS (respect 4-engine limit)
pool:
  min_engines: 1
  max_engines: 4

Execution Configuration

Key Type Default Description
execution.sync_timeout integer 30 Seconds before MATLAB code is auto-promoted from synchronous to asynchronous execution. If code runs longer than this, the server returns a job_id and moves execution to the background.
execution.max_execution_time integer 86400 Hard ceiling (seconds, 86400 = 24 hours) for any single job. Jobs exceeding this are forcibly terminated.
execution.workspace_isolation boolean true Clear workspace between sessions. When true, each session starts with a fresh workspace. When false, variables persist across jobs in the same session.
execution.engine_affinity boolean false Pin session to a specific engine. When true, a session's jobs always use the same engine (for stateful computations). When false, jobs can use any available engine.
execution.temp_dir string null Base temporary directory for session workspaces. If null, uses system temp directory (/tmp on Unix, %TEMP% on Windows). Per-session subdirectories are created within this path.
execution.temp_cleanup_on_disconnect boolean true Delete session temporary files when the session ends or times out. Set to false to retain temp files for debugging.

Example Execution Configurations:

# Fast, short-lived jobs
execution:
  sync_timeout: 10
  max_execution_time: 3600  # 1 hour

# Long-running simulations
execution:
  sync_timeout: 120
  max_execution_time: 604800  # 7 days

# Stateful computations (reuse engine)
execution:
  engine_affinity: true
  workspace_isolation: false

Workspace Configuration

Key Type Default Description
workspace.default_paths list of strings [] Paths added to MATLAB search path on every engine startup. Use for shared libraries, custom toolboxes, or data directories.
workspace.startup_commands list of strings [] MATLAB commands executed on engine startup. Examples: "format long", "tic", "rng(42)" for seeding randomness.

Example Workspace Configuration:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
    - "/opt/vendor_toolbox"
  startup_commands:
    - "format long"
    - "clear all"
    - "rng(42)"
    - "addpath(genpath('/shared/custom_libs'))"

Toolboxes Configuration

Key Type Default Description
toolboxes.mode enum "all" Filter mode for toolbox discovery: "whitelist" (report only listed toolboxes), "blacklist" (report all except listed), "all" (report all installed toolboxes).
toolboxes.list list of strings [] Toolbox names to whitelist or blacklist depending on mode.
Mode Behavior
whitelist Only toolboxes in list are reported to agents; all others hidden
blacklist All toolboxes EXCEPT those in list are reported
all All installed toolboxes are reported; list is ignored

Example Toolboxes Configuration:

# Whitelist: expose only these toolboxes
toolboxes:
  mode: "whitelist"
  list:
    - "Signal Processing Toolbox"
    - "Optimization Toolbox"
    - "Statistics and Machine Learning Toolbox"

# Blacklist: hide proprietary toolboxes
toolboxes:
  mode: "blacklist"
  list:
    - "Proprietary Toolbox A"
    - "Proprietary Toolbox B"

Security Configuration

Key Type Default Description
security.blocked_functions_enabled boolean true Master switch for function blocklist. When false, all functions are allowed.
security.blocked_functions list of strings See default list MATLAB function or operator names that are blocked from execution (e.g., "system", "!", "eval", "unix", "dos"). Security validator strips string literals and comments before scanning, so disp('system') does not trigger false positives.
security.max_upload_size_mb integer 100 Maximum file upload size in MB. upload_data tool rejects files larger than this.
security.require_proxy_auth boolean false When true (production SSE deployments), expect reverse proxy to provide authenticated user header. Server logs a warning if this is enabled without actually seeing the header.

Default Blocked Functions:

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"      # Execute system commands
    - "unix"        # Execute Unix commands
    - "dos"         # Execute DOS commands
    - "!"           # System command shorthand
    - "eval"        # Dynamic code evaluation
    - "feval"       # Function evaluation
    - "evalc"       # Evaluate with capture
    - "evalin"      # Evaluate in workspace
    - "assignin"    # Assign to workspace
    - "perl"        # Call Perl
    - "python"      # Call Python

Example Security Configurations:

# Development: all functions allowed
security:
  blocked_functions_enabled: false

# Production: strict blocklist
security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "eval"
    - "assignin"
    - "!"
  max_upload_size_mb: 50
  require_proxy_auth: true

Authentication Configuration

Key Type Default Description
auth.enabled boolean false Master switch for bearer token authentication. Applies only to HTTP/SSE transports; stdio is never authenticated.
auth.token_env_var string "MATLAB_MCP_AUTH_TOKEN" Environment variable name to read the bearer token from at server startup. Token must be a 64-character hex string or valid JWT.

Environment Variable Override: MATLAB_MCP_AUTH_TOKEN=<your_token>

Generating a Token:

matlab-mcp --generate-token

Outputs a 64-character hex token with shell snippets for POSIX, Windows cmd, and PowerShell:

Generated token:
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

POSIX (bash, zsh, sh):
  export MATLAB_MCP_AUTH_TOKEN="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"

Windows cmd.exe:
  set MATLAB_MCP_AUTH_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Windows PowerShell:
  $env:MATLAB_MCP_AUTH_TOKEN="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"

Example Auth Configuration:

# Development: no auth
auth:
  enabled: false

# Production: token from env var
auth:
  enabled: true
  token_env_var: "MATLAB_MCP_AUTH_TOKEN"

Human-in-the-Loop (HITL) Configuration

Key Type Default Description
hitl.enabled boolean false Master switch. When true, protected operations pause and request human approval via MCP elicitation protocol.
hitl.protected_functions list of strings [] MATLAB function names that require approval before execution. Examples: "delete", "rmdir", "system". Code is scanned (without string/comment literals) for calls to these functions.
hitl.protect_file_ops boolean false When true, upload_data and delete_file tools require approval before proceeding.
hitl.all_execute boolean false When true, ALL calls to execute_code require approval regardless of function scanning. Useful for high-security environments where every code execution must be audited.

Example HITL Configurations:

# Development: no HITL
hitl:
  enabled: false

# Moderate security: protect dangerous functions
hitl:
  enabled: true
  protected_functions:
    - "delete"
    - "rmdir"
    - "system"
    - "eval"
  protect_file_ops: true

# High security: approve all code execution
hitl:
  enabled: true
  all_execute: true
  protect_file_ops: true

Code Checker Configuration

Key Type Default Description
code_checker.enabled boolean true Enable the check_code tool for MATLAB linting.
code_checker.auto_check_before_execute boolean false Automatically run linting before every execute_code call. If warnings are found, return linting results before executing.
code_checker.severity_levels list of strings ["error", "warning"] Which severity levels to report: "error", "warning", "info".

Example Code Checker Configuration:

# Default: linting available but not automatic
code_checker:
  enabled: true
  auto_check_before_execute: false

# Strict: auto-lint before every execution
code_checker:
  enabled: true
  auto_check_before_execute: true
  severity_levels: ["error", "warning"]

Output Configuration

Key Type Default Description
output.plotly_conversion boolean true Automatically convert MATLAB figures to interactive Plotly JSON. Enables agents to request and view plots in their UI.
output.static_image_format enum "png" Static image format for figure snapshots: "png", "jpg", "svg".
output.static_image_dpi integer 150 DPI (dots per inch) for static images. Higher values = larger file sizes but better clarity.
output.thumbnail_enabled boolean true Generate base64-encoded thumbnails of result images for inline display.
output.thumbnail_max_width integer 400 Max width (pixels) for thumbnails while preserving aspect ratio.
output.large_result_threshold integer 10000 Element count above which results are saved to a file instead of inlined (avoids huge JSON responses).
output.max_inline_text_length integer 50000 Character count above which text output is saved to a file instead of inlined.

Example Output Configuration:

# Default: Plotly conversion + thumbnails
output:
  plotly_conversion: true
  static_image_format: "png"
  static_image_dpi: 150
  thumbnail_enabled: true
  thumbnail_max_width: 400

# High-fidelity: SVG vectors, no size limits
output:
  plotly_conversion: true
  static_image_format: "svg"
  large_result_threshold: 100000
  max_inline_text_length: 500000

Sessions Configuration

Key Type Default Description
sessions.max_sessions integer 50 Maximum concurrent sessions. New session requests beyond this return "max sessions reached" errors.
sessions.session_timeout integer 3600 Seconds (3600 = 1 hour) of inactivity before a session is automatically cleaned up and destroyed.
sessions.job_retention_seconds integer 86400 Seconds (86400 = 24 hours) to retain completed job metadata before pruning. Enables historical job queries.

Example Sessions Configuration:

# Development: permissive
sessions:
  max_sessions: 100
  session_timeout: 86400  # 24 hours

# Production: strict cleanup
sessions:
  max_sessions: 10
  session_timeout: 1800   # 30 minutes
  job_retention_seconds: 3600  # 1 hour

Monitoring Configuration

Key Type Default Description
monitoring.enabled boolean true Master switch for metrics collection and health monitoring. When false, all monitoring/telemetry is disabled.
monitoring.sample_interval integer 10 Seconds between metric samples (pool utilization, engine health, job stats, memory).
monitoring.retention_days integer 7 Days to retain historical metrics in SQLite database before cleanup.
monitoring.db_path string "./monitoring/metrics.db" Path to SQLite database for metrics storage. Directory is created if missing.
monitoring.dashboard_enabled boolean true Enable the web dashboard at http://host:port/dashboard for real-time metrics visualization.

Example Monitoring Configuration:

# Development: all metrics
monitoring:
  enabled: true
  sample_interval: 10
  retention_days: 30
  dashboard_enabled: true

# Production: high-frequency sampling, longer retention
monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 90
  dashboard_enabled: true

# Minimal: metrics disabled
monitoring:
  enabled: false

Custom Tools Configuration

Key Type Default Description
custom_tools.config_file string null Path to YAML file defining custom MATLAB-backed tools. If null, no custom tools are loaded. See Custom-Tools for full format reference.
custom_tools.auto_reload boolean false When true, re-read the custom tools file every reload_interval seconds without restarting the server.
custom_tools.reload_interval integer 60 Seconds between auto-reload checks (only applies if auto_reload: true).

Example Custom Tools Configuration:

# Load custom tools from a file
custom_tools:
  config_file: "./custom_tools.yaml"
  auto_reload: false

# Dynamic reload (development)
custom_tools:
  config_file: "./custom_tools.yaml"
  auto_reload: true
  reload_interval: 30

Complete Example Configuration Files

Minimal Single-User (stdio)

# Minimal config for a single local agent
server:
  transport: "stdio"

pool:
  min_engines: 1
  max_engines: 2

security:
  blocked_functions_enabled: true

monitoring:
  enabled: false

Multi-User with Streamable HTTP

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

pool:
  min_engines: 2
  max_engines: 8
  health_check_interval: 60

execution:
  sync_timeout: 30
  workspace_isolation: true

security:
  blocked_functions_enabled: true
  blocked_functions:
    - "system"
    - "eval"
    - "assignin"

auth:
  enabled: true
  token_env_var: "MATLAB_MCP_AUTH_TOKEN"

sessions:
  max_sessions: 20
  session_timeout: 3600

monitoring:
  enabled: true
  sample_interval: 10
  dashboard_enabled: true

Production with HITL and Custom Tools

server:
  transport: "streamablehttp"
  host: "0.0.0.0"
  port: 8765
  stateless_http: false
  log_level: "warning"

pool:
  min_engines: 4
  max_engines: 32
  proactive_warmup_threshold: 0.7
  health_check_interval: 30

execution:
  sync_timeout: 120
  max_execution_time: 604800  # 7 days
  workspace_isolation: true

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 50
  require_proxy_auth: true

auth:
  enabled: true
  token_env_var: "MATLAB_MCP_AUTH_TOKEN"

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

sessions:
  max_sessions: 100
  session_timeout: 7200

monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 90
  dashboard_enabled: true

custom_tools:
  config_file: "/etc/matlab_mcp/custom_tools.yaml"

Architecture: Configuration Validation Flow

graph TD
    A["Config File<br/>config.yaml"] -->|read YAML| B["Raw Dict"]
    C["Environment Variables<br/>MATLAB_MCP_*"] -->|extract & parse| B
    B -->|Pydantic models| D["ServerConfig<br/>PoolConfig<br/>SecurityConfig<br/>..."]
    D -->|validate & coerce| E["AppConfig"]
    E -->|_apply_env_overrides| F["Final Config<br/>with env vars applied"]
    F -->|passed to server| G["MatlabMCPServer"]
    G -->|governs behavior| H["Execution:<br/>pools, auth,<br/>monitoring"]
    
    style A fill:#e1f5ff
    style C fill:#c8e6c9
    style D fill:#fff9c4
    style F fill:#f3e5f5
    style H fill:#fce4ec
Loading

Debugging Configuration Issues

Check which config was loaded

matlab-mcp --config ./config.yaml 2>&1 | grep "Loaded config"

Verify environment variable override

export MATLAB_MCP_POOL_MIN_ENGINES=8
matlab-mcp --config ./config.yaml 2>&1 | grep -i "min_engines"

Enable debug logging to see config values

export MATLAB_MCP_SERVER_LOG_LEVEL=debug
matlab-mcp --config ./config.yaml 2>&1 | grep config

Validate YAML syntax

python -c "import yaml; yaml.safe_load(open('config.yaml'))" && echo "Valid YAML"

Clone this wiki locally