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.

Overview

The MATLAB MCP Server configuration system uses a hierarchical Pydantic-based model with support for:

  • YAML file loading from config.yaml (or custom path)
  • Environment variable overrides using the MATLAB_MCP_* prefix
  • Automatic path resolution (relative paths resolved relative to config file location)
  • Validation (e.g., min_engines ≤ max_engines, macOS stability warnings)

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_OUTPUT_PLOTLY_CONVERSION=false

Environment variables always take precedence over YAML file values.

Naming Convention

The environment variable naming convention is:

MATLAB_MCP_<SECTION>_<FIELD_NAME>
  • SECTION is the top-level key in the config (e.g., pool, server, execution)
  • FIELD_NAME is the nested key name in uppercase with underscores preserved
  • Type coercion is automatic (strings → int, bool, list as needed)

Examples:

YAML Path Environment Variable
pool.min_engines MATLAB_MCP_POOL_MIN_ENGINES
server.transport MATLAB_MCP_SERVER_TRANSPORT
execution.sync_timeout MATLAB_MCP_EXECUTION_SYNC_TIMEOUT
sessions.max_sessions MATLAB_MCP_SESSIONS_MAX_SESSIONS

Limitation: Multi-word section names like code_checker and custom_tools cannot be overridden via environment variables due to the single-underscore split rule. Use the YAML config file for those sections instead.

Configuration Sections

Server

General server settings (name, transport, host/port, logging).

Key Type Default Description
name string "matlab-mcp-server" Server name reported to MCP clients
transport "stdio" | "sse" "stdio" Communication transport (stdio for local, SSE for network)
host string "0.0.0.0" Bind address (SSE only)
port integer 8765 Port number (SSE only)
log_level "debug" | "info" | "warning" | "error" "info" Logging verbosity
log_file string "./logs/server.log" Log file path
result_dir string "./results" Directory for storing result files
drain_timeout_seconds integer 300 Max seconds to wait for running jobs during shutdown

Environment Variables:

MATLAB_MCP_SERVER_TRANSPORT=sse
MATLAB_MCP_SERVER_HOST=127.0.0.1
MATLAB_MCP_SERVER_PORT=9000
MATLAB_MCP_SERVER_LOG_LEVEL=debug

Pool

MATLAB engine pool sizing, auto-scaling, and health management.

Key Type Default Description
min_engines integer 2 Minimum engines to keep warm at all times
max_engines integer 10 Maximum engines (hard ceiling; capped at 4 on macOS)
scale_down_idle_timeout integer 900 Seconds of idleness before scaling down (15 min)
engine_start_timeout integer 120 Seconds to wait for MATLAB process to start
health_check_interval integer 60 Seconds between automatic health checks
proactive_warmup_threshold float 0.8 Utilization ratio (0–1) that triggers warmup of additional engines
queue_max_size integer 50 Maximum pending execution requests in queue
matlab_root string | null null Explicit MATLAB installation path (auto-detected if null)

Validation Rules:

  • min_engines must be ≤ max_engines (raises ValueError otherwise)
  • macOS warning: if max_engines > 4, a warning is logged (MATLAB engine has stability limits on macOS)

Environment Variables:

MATLAB_MCP_POOL_MIN_ENGINES=4
MATLAB_MCP_POOL_MAX_ENGINES=16
MATLAB_MCP_POOL_ENGINE_START_TIMEOUT=180
MATLAB_MCP_POOL_MATLAB_ROOT=/Applications/MATLAB_R2023b.app

Execution

Code execution timeouts, workspace isolation, and temporary file management.

Key Type Default Description
sync_timeout integer 30 Seconds before auto-promoting code to async job
max_execution_time integer 86400 Hard limit per job (24 hours = 86400 seconds)
workspace_isolation boolean true Clear workspace between sessions
engine_affinity boolean false Pin a session to the same engine
temp_dir string "./temp" Temporary file directory for session data
temp_cleanup_on_disconnect boolean true Delete temp files when session ends

Details:

  • sync_timeout: When MATLAB code runs longer than this, the server automatically promotes it to an async job and returns a job_id for polling. Increase this for workloads that typically take 30–60 seconds.

  • workspace_isolation: When true, each session's workspace is cleared when the session ends or when a new job starts in stdio mode. When false, variables persist across jobs in the same session.

  • engine_affinity: If true, a session is pinned to a single engine for consistency (useful for debugging). If false, any available engine can be used (better load balancing).

Environment Variables:

MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60
MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME=172800  # 48 hours
MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION=false

Workspace

MATLAB workspace initialization: default paths and startup commands.

Key Type Default Description
default_paths list of strings [] Paths to add to MATLAB search path on engine startup
startup_commands list of strings ["format long"] MATLAB commands to run on each engine start

Example:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/data"
    - "/opt/matlab_addons"
  startup_commands:
    - "format long"
    - "warning off"
    - "addpath('/some/path')"

Toolboxes

Toolbox visibility mode: whitelist, blacklist, or expose all.

Key Type Default Description
mode "whitelist" | "blacklist" | "all" "whitelist" How to filter available toolboxes
list list of strings [] Toolbox names to include (whitelist) or exclude (blacklist)
Mode Behavior
whitelist Only listed toolboxes are reported to agents; all others hidden
blacklist All installed toolboxes EXCEPT listed ones are reported
all All installed toolboxes are reported (no filtering)

Example (whitelist):

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

Example (blacklist):

toolboxes:
  mode: "blacklist"
  list:
    - "Embedded Coder"
    - "HDL Coder"

Custom Tools

Path to the YAML file that defines user-provided custom tools.

Key Type Default Description
config_file string "./custom_tools.yaml" Path to the custom tools configuration file

Custom tools are loaded from this file and exposed as first-class MCP tools to agents. See the Custom Tools page for the full YAML schema.

Security

Security controls: blocked functions, upload limits, reverse proxy authentication.

Key Type Default Description
blocked_functions_enabled boolean true Enable blocking of dangerous MATLAB functions
blocked_functions list of strings See below Functions to block from execution
max_upload_size_mb integer 100 Maximum file upload size in MB
require_proxy_auth boolean false Require reverse proxy authentication (SSE only)

Default Blocked Functions:

security:
  blocked_functions:
    - "system"      # Execute system commands
    - "unix"        # UNIX command execution
    - "dos"         # DOS command execution
    - "!"           # Shell escape operator
    - "eval"        # Dynamic code execution
    - "feval"       # Function evaluation
    - "evalc"       # Evaluation with capture
    - "evalin"      # Evaluation in workspace
    - "assignin"    # Assignment in workspace
    - "perl"        # Perl script execution
    - "python"      # Python script execution

Details:

  • blocked_functions_enabled: When false, all functions are allowed (security validation disabled).

  • Scanning: The security validator strips string literals and comments before scanning to avoid false positives (e.g., disp('system') won't trigger a block).

  • max_upload_size_mb: Enforced when uploading files via the upload_data tool. Filenames are sanitized to prevent path traversal.

  • require_proxy_auth: For SSE transport in production, set this to true to enforce that authentication is handled by a reverse proxy (e.g., nginx with OAuth2).

Environment Variables:

MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED=false
MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB=500
MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH=true

Code Checker

MATLAB code linting via checkcode/mlint.

Key Type Default Description
enabled boolean true Enable code checking
auto_check_before_execute boolean false Run checkcode before every execute_code call
severity_levels list of strings ["error", "warning"] Issue severities to report

Example:

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]

Output

Output formatting: Plotly conversion, image formats, thumbnails, and truncation thresholds.

Key Type Default Description
plotly_conversion boolean true Convert MATLAB figures to Plotly JSON
static_image_format "png" | "jpg" | "svg" "png" Format for static image exports
static_image_dpi integer 150 DPI for static image rendering
thumbnail_enabled boolean true Generate thumbnail images
thumbnail_max_width integer 400 Maximum width of thumbnail in pixels
large_result_threshold integer 10000 Element count before saving to file instead of inlining
max_inline_text_length integer 50000 Character count before saving text to file

Details:

  • plotly_conversion: When true, MATLAB figures are automatically converted to interactive Plotly JSON and embedded in responses.

  • thumbnail_enabled: When true, large images are resized to thumbnail_max_width and base64-encoded for agent display.

  • large_result_threshold: Results with more than this many elements (e.g., array size) are saved to disk and a reference is returned instead of inlining.

  • max_inline_text_length: Output text longer than this is saved to a file and a reference is returned.

Environment Variables:

MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION=false
MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI=300
MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH=100000

Sessions

Session lifecycle management: limits, timeouts, and job retention.

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

Details:

  • max_sessions: In SSE mode, limits the number of concurrent client sessions. In stdio mode, only one session ("default") is created.

  • session_timeout: Sessions with no activity (no jobs submitted) for this duration are automatically cleaned up and their temp directories deleted.

  • job_retention_seconds: Completed, failed, or cancelled job metadata is retained for this duration before pruning to save memory.

Environment Variables:

MATLAB_MCP_SESSIONS_MAX_SESSIONS=100
MATLAB_MCP_SESSIONS_SESSION_TIMEOUT=7200
MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS=172800

Monitoring

Server monitoring: metrics collection, time-series storage, and web dashboard.

Key Type Default Description
enabled boolean true Enable metrics collection
sample_interval integer 10 Seconds between metric snapshots
retention_days integer 7 Days of historical data to retain
db_path string "./monitoring/metrics.db" SQLite database path for metrics
dashboard_enabled boolean true Enable web dashboard UI
http_port integer 8766 Port for the dashboard (stdio only)

Details:

  • enabled: When false, no metrics are collected, reducing overhead.

  • sample_interval: Metrics (pool utilization, job counts, system stats) are sampled every N seconds and written to the time-series database.

  • retention_days: Old metric records are automatically pruned to keep the database size manageable.

  • dashboard_enabled: When true, a web UI is available at http://localhost:8766/dashboard (stdio) or http://<host>:<http_port>/dashboard (SSE).

Environment Variables:

MATLAB_MCP_MONITORING_ENABLED=true
MATLAB_MCP_MONITORING_SAMPLE_INTERVAL=5
MATLAB_MCP_MONITORING_HTTP_PORT=9999

Optional Dependencies:

Monitoring requires optional packages. Install with:

pip install -e ".[monitoring]"
# or for full dev setup:
pip install -e ".[dev]"

Complete Example Configuration

# config.yaml

server:
  name: "matlab-mcp-server"
  transport: "stdio"                 # Use stdio for local development
  host: "0.0.0.0"
  port: 8765
  log_level: "info"
  log_file: "./logs/server.log"
  result_dir: "./results"
  drain_timeout_seconds: 300

pool:
  min_engines: 2                     # Keep 2 engines warm
  max_engines: 10                    # Up to 10 engines under load
  scale_down_idle_timeout: 900       # 15 min idle before shutdown
  engine_start_timeout: 120          # 2 min timeout per engine startup
  health_check_interval: 60          # Check engine health every minute
  proactive_warmup_threshold: 0.8    # Warmup when 80% utilized
  queue_max_size: 50
  matlab_root: null                  # Auto-detect MATLAB installation

execution:
  sync_timeout: 30                   # Code > 30s becomes async job
  max_execution_time: 86400          # 24 hour hard limit per job
  workspace_isolation: true          # Clear workspace between sessions
  engine_affinity: false             # Load-balance across engines
  temp_dir: "./temp"
  temp_cleanup_on_disconnect: true

workspace:
  default_paths:
    - "/opt/matlab_addons/custom"
  startup_commands:
    - "format long"
    - "warning off"

toolboxes:
  mode: "whitelist"                  # Only expose whitelisted toolboxes
  list:
    - "Signal Processing Toolbox"
    - "Statistics and Machine Learning Toolbox"
    - "Image Processing Toolbox"
    - "Optimization Toolbox"

custom_tools:
  config_file: "./custom_tools.yaml"

security:
  blocked_functions_enabled: true    # Always enabled in production
  blocked_functions:
    - "system"
    - "unix"
    - "dos"
    - "!"
    - "eval"
    - "feval"
    - "evalc"
    - "evalin"
    - "assignin"
    - "perl"
    - "python"
  max_upload_size_mb: 100
  require_proxy_auth: false          # Set to true behind reverse proxy

code_checker:
  enabled: true
  auto_check_before_execute: false
  severity_levels: ["error", "warning"]

output:
  plotly_conversion: true            # Convert MATLAB figures to Plotly
  static_image_format: "png"
  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 idle timeout
  job_retention_seconds: 86400       # Keep job metadata 24 hours

monitoring:
  enabled: true
  sample_interval: 10                # Sample every 10 seconds
  retention_days: 7                  # Keep 7 days of history
  db_path: "./monitoring/metrics.db"
  dashboard_enabled: true
  http_port: 8766

Configuration Architecture

graph TB
    subgraph Input["Configuration Input"]
        YAML["config.yaml"]
        ENV["Environment Variables<br/>(MATLAB_MCP_*)"]
        CLI["CLI Arguments"]
    end
    
    subgraph Loading["Configuration Loading"]
        Load["load_config()"]
        Validate["Pydantic Validation"]
        Resolve["Path Resolution"]
    end
    
    subgraph Models["Config Model Hierarchy"]
        App["AppConfig"]
        App --> S["ServerConfig"]
        App --> P["PoolConfig"]
        App --> E["ExecutionConfig"]
        App --> W["WorkspaceConfig"]
        App --> T["ToolboxesConfig"]
        App --> C["CustomToolsConfig"]
        App --> SC["SecurityConfig"]
        App --> CC["CodeCheckerConfig"]
        App --> OC["OutputConfig"]
        App --> SES["SessionsConfig"]
        App --> M["MonitoringConfig"]
    end
    
    subgraph Components["Server Components"]
        EnginePool["EnginePoolManager"]
        JobTracker["JobTracker"]
        JobExecutor["JobExecutor"]
        SessionMgr["SessionManager"]
        Security["SecurityValidator"]
        Collector["MetricsCollector"]
    end
    
    YAML --> Load
    ENV --> Load
    CLI --> Load
    Load --> Validate
    Validate --> Resolve
    Resolve --> Models
    
    Models --> Components
    S --> EnginePool
    P --> EnginePool
    E --> JobExecutor
    W --> EnginePool
    T --> Components
    SC --> Security
    CC --> Components
    OC --> Components
    SES --> SessionMgr
    M --> Collector
Loading

Example Deployment Configurations

See the examples/ directory for ready-to-use templates:

config_minimal.yaml

Single-user, local deployment with minimal settings:

server:
  transport: "stdio"

pool:
  min_engines: 1
  max_engines: 2

execution:
  sync_timeout: 30
  temp_dir: "./temp"

monitoring:
  enabled: false

config_multiuser.yaml

Multi-user, production-ready SSE deployment with larger pool and stricter security:

server:
  transport: "sse"
  port: 8765
  host: "127.0.0.1"

pool:
  min_engines: 4
  max_engines: 16
  engine_start_timeout: 180

execution:
  sync_timeout: 60
  max_execution_time: 172800

security:
  blocked_functions_enabled: true
  require_proxy_auth: true
  max_upload_size_mb: 500

sessions:
  max_sessions: 100
  session_timeout: 7200
  job_retention_seconds: 172800

monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 14

Configuration File Location Precedence

  1. CLI argument (if provided): --config /path/to/config.yaml
  2. Environment variable: MATLAB_MCP_CONFIG
  3. Current directory: ./config.yaml
  4. Fallback: Defaults (no file required)

Path Resolution

All relative filesystem paths in the configuration are automatically resolved to absolute paths based on the directory containing the config file:

# In /home/user/matlab-mcp/config.yaml
execution:
  temp_dir: "./temp"         # Resolved to /home/user/matlab-mcp/temp

server:
  result_dir: "./results"    # Resolved to /home/user/matlab-mcp/results

custom_tools:
  config_file: "./custom_tools.yaml"  # Resolved to /home/user/matlab-mcp/custom_tools.yaml

If no config file is used (defaults only), relative paths are resolved relative to the current working directory.

Validation and Error Handling

The configuration system performs several validations:

Validation Error Condition Action
Pool sizing min_engines > max_engines Raises ValueError
macOS stability max_engines > 4 on macOS Logs warning (continues)
Timeouts sync_timeout > max_execution_time Allowed (sync code gets promoted)
Paths Invalid directory path Resolved relative to config file

All validation occurs during load_config() before the server starts, ensuring early detection of configuration errors.

Clone this wiki locally