Skip to content

Configuration

Jump to bottom
github-actions[bot] edited this page Apr 3, 2026 · 20 revisions

Configuration

This page documents every configuration option for the MATLAB MCP Server, organized by category. All settings are loaded from config.yaml with environment variable overrides via the MATLAB_MCP_* prefix convention.

Configuration Overview

graph TB
    A["config.yaml<br/>+ ENV overrides"] -->|load_config| B["AppConfig<br/>Pydantic models"]
    B --> C["ServerConfig<br/>PoolConfig"]
    B --> D["ExecutionConfig<br/>WorkspaceConfig"]
    B --> E["SecurityConfig<br/>MonitoringConfig"]
    C --> F["server.py<br/>MatlabMCPServer"]
    D --> F
    E --> F
    F --> G["Engine Pool<br/>Job Executor<br/>Sessions"]
    style A fill:#e1f5ff
    style B fill:#f3e5f5
    style F fill:#e8f5e9
Loading

Configuration Options by Category

Server

Controls transport mode, binding address, logging, and shutdown behavior.

Option Type Default Environment Variable Description
name string "matlab-mcp-server" MATLAB_MCP_SERVER_NAME Server name reported in /health endpoint and MCP protocol handshake
transport enum "stdio" MATLAB_MCP_SERVER_TRANSPORT Transport layer: "stdio" (single user, no auth), "sse" (SSE, deprecated), or "streamablehttp" (HTTP POST/GET)
host string "127.0.0.1" MATLAB_MCP_SERVER_HOST Bind address for HTTP/SSE transports (ignored for stdio). "127.0.0.1" prevents Windows Firewall UAC prompts.
port integer 8765 MATLAB_MCP_SERVER_PORT Bind port for HTTP/SSE transports (ignored for stdio)
log_level enum "info" MATLAB_MCP_SERVER_LOG_LEVEL Logging level: "debug", "info", "warning", "error"
log_file string null MATLAB_MCP_SERVER_LOG_FILE Path to log file; if null, logs to stderr only
result_dir string "./results" MATLAB_MCP_SERVER_RESULT_DIR Directory where large result files are saved (relative paths resolved from cwd)
drain_timeout_seconds integer 300 MATLAB_MCP_SERVER_DRAIN_TIMEOUT_SECONDS Max seconds to wait for running jobs during graceful shutdown
stateless_http boolean false MATLAB_MCP_SERVER_STATELESS_HTTP For streamablehttp transport: disable per-session temp directories (each request routed to default session)

Transport Notes:

  • stdio: Single-user, no authentication (suitable for Claude Desktop, local agents)
  • sse: SSE transport (deprecated as of v2.0; kept for backward compatibility)
  • streamablehttp: FastMCP 3.x streamable HTTP transport at /mcp endpoint; requires bearer token auth for production use

Pool

Controls MATLAB engine lifecycle, scaling, and health management.

Option Type Default Environment Variable Description
min_engines integer 2 MATLAB_MCP_POOL_MIN_ENGINES Minimum number of warm engines to maintain
max_engines integer 10 MATLAB_MCP_POOL_MAX_ENGINES Maximum number of engines (hard ceiling)
scale_down_idle_timeout integer 900 MATLAB_MCP_POOL_SCALE_DOWN_IDLE_TIMEOUT Seconds an engine must be idle before scale-down triggers (15 min default)
engine_start_timeout integer 120 MATLAB_MCP_POOL_ENGINE_START_TIMEOUT Seconds to wait for MATLAB engine startup; exceeded triggers error and retry
health_check_interval integer 60 MATLAB_MCP_POOL_HEALTH_CHECK_INTERVAL Seconds between background health-check cycles
proactive_warmup_threshold float 0.8 MATLAB_MCP_POOL_PROACTIVE_WARMUP_THRESHOLD Utilization ratio (0-1) above which scale-up is proactive (don't wait for queue)
queue_max_size integer 50 MATLAB_MCP_POOL_QUEUE_MAX_SIZE Maximum pending requests in acquire queue before rejecting new requests
matlab_root string null MATLAB_MCP_POOL_MATLAB_ROOT Explicit MATLAB installation path (e.g., /Applications/MATLAB_R2024a.app); if null, auto-detected

macOS Limitation:
MATLAB on macOS enforces a 4-engine limit at the OS level. The server will warn if max_engines > 4 on macOS but respects the configured value (and may timeout if you exceed 4).

Execution

Controls job execution timing, workspace isolation, and resource limits.

Option Type Default Environment Variable Description
sync_timeout integer 30 MATLAB_MCP_EXECUTION_SYNC_TIMEOUT Seconds to wait for code execution before auto-promoting to async job
max_execution_time integer 86400 MATLAB_MCP_EXECUTION_MAX_EXECUTION_TIME Hard ceiling on job execution time in seconds (24 hours default; jobs exceeding this are terminated)
workspace_isolation boolean true MATLAB_MCP_EXECUTION_WORKSPACE_ISOLATION If true, run clear all and restore default paths at session start
engine_affinity boolean false MATLAB_MCP_EXECUTION_ENGINE_AFFINITY If true, pin a session to a specific engine (disable for stateless HTTP)
temp_dir string "./temp" MATLAB_MCP_EXECUTION_TEMP_DIR Directory for temporary files (relative paths resolved from cwd)
temp_cleanup_on_disconnect boolean true MATLAB_MCP_EXECUTION_TEMP_CLEANUP_ON_DISCONNECT If true, delete session temp directory when session times out or client disconnects

sync_timeout Note:
When code execution exceeds this threshold, the server returns immediately with a job_id and status "pending". The agent can poll get_job_status or get_job_result to track progress. Increase this for environments where most code runs 30-60+ seconds.

Workspace

Configures MATLAB startup behavior and default paths.

Option Type Default Environment Variable Description
default_paths list of strings [] N/A (must use YAML) MATLAB paths added to engine startup (e.g., custom libraries, shared data directories)
startup_commands list of strings [] N/A (must use YAML) MATLAB commands executed on each engine start (e.g., "format long", license setups)

Example:

workspace:
  default_paths:
    - "/shared/custom_libs"
    - "/shared/research/data"
  startup_commands:
    - "format long"
    - "warning('off', 'MATLAB:singularMatrix')"

Toolboxes

Controls which MATLAB toolboxes are visible to agents.

Option Type Default Environment Variable Description
mode enum "all" MATLAB_MCP_TOOLBOXES_MODE Visibility mode: "all" (all installed), "whitelist" (only listed), "blacklist" (all except listed)
list list of strings [] N/A (must use YAML) Toolbox names (used with whitelist/blacklist mode)

Example — Whitelist Mode:

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

In whitelist mode, only listed toolboxes will be reported by the list_toolboxes tool.

Custom Tools

Loads user-defined MATLAB functions as first-class MCP tools.

Option Type Default Environment Variable Description
config_file string null MATLAB_MCP_CUSTOM_TOOLS_CONFIG_FILE Path to YAML file defining custom tools (relative paths resolved from cwd)

Format:
See Custom-Tools wiki page. Briefly:

# custom_tools.yaml
tools:
  - name: "analyze_signal"
    description: "FFT analysis of a signal"
    function: "signal.analyze"  # MATLAB function name or package.function
    parameters:
      signal:
        type: "array"
        description: "Input signal vector"
      window:
        type: "string"
        enum: ["hamming", "hann", "blackman"]
        default: "hamming"

Security

Controls function blocking, file upload limits, and authentication.

Option Type Default Environment Variable Description
blocked_functions_enabled boolean true MATLAB_MCP_SECURITY_BLOCKED_FUNCTIONS_ENABLED If true, enforce the blocked functions list
blocked_functions list of strings See below N/A (must use YAML) MATLAB function names to block from execution (e.g., "system", "eval", "!")
max_upload_size_mb integer 100 MATLAB_MCP_SECURITY_MAX_UPLOAD_SIZE_MB Maximum file size for upload_data tool
require_proxy_auth boolean false MATLAB_MCP_SECURITY_REQUIRE_PROXY_AUTH If true (SSE only), reject requests without X-Forwarded-User header (assumed set by reverse proxy)

Default Blocked Functions:

blocked_functions:
  - "system"
  - "unix"
  - "dos"
  - "!"
  - "eval"
  - "evalc"
  - "feval"
  - "evalin"
  - "assignin"
  - "perl"
  - "python"

The security validator uses regex-based detection with smart string-literal stripping to avoid false positives (e.g., disp('system') is allowed).

Authentication

Configures bearer token authentication for HTTP/SSE transports.

Option Type Default Environment Variable Description
auth_token string null MATLAB_MCP_AUTH_TOKEN Bearer token (opaque 64-char hex string) for authenticating HTTP requests; if null, auth is disabled

Token Generation:

matlab-mcp --generate-token
# Output: 64-char hex token + env var export snippets for POSIX/Windows/PowerShell

Usage:

export MATLAB_MCP_AUTH_TOKEN="a1b2c3d4e5f6..."
matlab-mcp --transport streamablehttp

Client connects with:

curl -H "Authorization: Bearer a1b2c3d4e5f6..." http://localhost:8765/mcp

Code Checker

Controls MATLAB code linting via checkcode().

Option Type Default Environment Variable Description
enabled boolean true MATLAB_MCP_CODE_CHECKER_ENABLED If true, check_code tool is available
auto_check_before_execute boolean false MATLAB_MCP_CODE_CHECKER_AUTO_CHECK_BEFORE_EXECUTE If true, run checkcode automatically before every execute_code (slower but catches issues early)
severity_levels list of strings ["error", "warning"] N/A (must use YAML) Which severity levels to report ("error", "warning", "info")

Output

Controls result formatting, figure conversion, and large-result handling.

Option Type Default Environment Variable Description
plotly_conversion boolean true MATLAB_MCP_OUTPUT_PLOTLY_CONVERSION If true, convert MATLAB figures to Plotly JSON automatically
static_image_format enum "png" MATLAB_MCP_OUTPUT_STATIC_IMAGE_FORMAT Format for static figure export: "png", "jpg", or "svg"
static_image_dpi integer 150 MATLAB_MCP_OUTPUT_STATIC_IMAGE_DPI DPI for raster exports (PNG/JPG); higher = larger file, better quality
thumbnail_enabled boolean true MATLAB_MCP_OUTPUT_THUMBNAIL_ENABLED If true, generate base64-encoded thumbnail for figures
thumbnail_max_width integer 400 MATLAB_MCP_OUTPUT_THUMBNAIL_MAX_WIDTH Max width in pixels for thumbnail (aspect ratio preserved)
large_result_threshold integer 10000 MATLAB_MCP_OUTPUT_LARGE_RESULT_THRESHOLD Number of array/table elements above which results are saved to file (not inline)
max_inline_text_length integer 50000 MATLAB_MCP_OUTPUT_MAX_INLINE_TEXT_LENGTH Max characters of stdout/stderr to inline; longer text saved to file

Example — High-DPI Export:

output:
  plotly_conversion: true
  static_image_dpi: 300
  thumbnail_enabled: true

Sessions

Controls session lifecycle and cleanup.

Option Type Default Environment Variable Description
max_sessions integer 50 MATLAB_MCP_SESSIONS_MAX_SESSIONS Hard ceiling on number of concurrent sessions
session_timeout integer 3600 MATLAB_MCP_SESSIONS_SESSION_TIMEOUT Seconds of inactivity before a session is cleaned up (1 hour default)
job_retention_seconds integer 86400 MATLAB_MCP_SESSIONS_JOB_RETENTION_SECONDS Seconds to retain completed job metadata before pruning (24 hours default)

Monitoring

Controls metrics collection, persistence, and the web dashboard.

Option Type Default Environment Variable Description
enabled boolean true MATLAB_MCP_MONITORING_ENABLED If true, metrics collection is active
sample_interval integer 10 MATLAB_MCP_MONITORING_SAMPLE_INTERVAL Seconds between metric samples (pool utilization, active jobs, etc.)
retention_days integer 7 MATLAB_MCP_MONITORING_RETENTION_DAYS Days to keep historical metrics in SQLite before pruning
db_path string "./monitoring/metrics.db" MATLAB_MCP_MONITORING_DB_PATH Path to SQLite metrics database (relative paths resolved from cwd)
dashboard_enabled boolean true MATLAB_MCP_MONITORING_DASHBOARD_ENABLED If true, HTTP dashboard is available at /dashboard (stdio only)
http_port integer 8766 MATLAB_MCP_MONITORING_HTTP_PORT Port for standalone HTTP dashboard (stdio transport only)

Note:
Monitoring requires optional dependencies. Install with:

pip install -e ".[monitoring]"

Includes psutil (system metrics), uvicorn (HTTP server), and Plotly/Pillow (visualizations).

Human-in-the-Loop (HITL)

Controls approval gates for code execution and file operations.

Option Type Default Environment Variable Description
enabled boolean false MATLAB_MCP_HITL_ENABLED If true, enable approval gates
protected_functions list of strings [] N/A (must use YAML) Function names that require human approval before execution (e.g., ["system", "eval"])
protect_file_ops boolean true MATLAB_MCP_HITL_PROTECT_FILE_OPS If true, require approval for upload_data and delete_file
all_execute boolean false MATLAB_MCP_HITL_ALL_EXECUTE If true, require approval for ALL execute_code calls (overrides protected_functions list)

Example — Enable HITL with Protected Functions:

hitl:
  enabled: true
  protected_functions:
    - "system"
    - "eval"
    - "feval"
  protect_file_ops: true
  all_execute: false

When enabled, agents receive FastMCP elicitation requests asking for approval. If denied, the tool returns an error without executing MATLAB code.

Example Configuration Files

Minimal (Single User, Local)

server:
  transport: stdio

pool:
  min_engines: 2
  max_engines: 4

security:
  blocked_functions_enabled: true

monitoring:
  enabled: false

Production (Multi-User HTTP + Auth)

server:
  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: 60
  workspace_isolation: true

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 500
  require_proxy_auth: true  # Use with reverse proxy

code_checker:
  enabled: true
  auto_check_before_execute: false

output:
  plotly_conversion: true
  large_result_threshold: 50000

sessions:
  max_sessions: 100
  session_timeout: 7200

monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 14
  dashboard_enabled: true
  http_port: 8766

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

Windows 10 (No Admin, HTTP)

server:
  transport: streamablehttp
  host: "127.0.0.1"
  port: 8000

pool:
  min_engines: 2
  max_engines: 4

execution:
  sync_timeout: 30

security:
  blocked_functions_enabled: true

monitoring:
  enabled: false

Environment Variable Override Examples

# Single environment variable
export MATLAB_MCP_POOL_MAX_ENGINES=20
matlab-mcp

# Multiple overrides
export MATLAB_MCP_SERVER_TRANSPORT=streamablehttp
export MATLAB_MCP_SERVER_PORT=9000
export MATLAB_MCP_AUTH_TOKEN="abc123def456..."
matlab-mcp

# Generate and set token in one step
export MATLAB_MCP_AUTH_TOKEN=$(matlab-mcp --generate-token | grep "MATLAB_MCP_AUTH_TOKEN=" | cut -d= -f2)
matlab-mcp --transport streamablehttp

Loading Configuration

Priority Order

  1. Command-line flags (e.g., --config, --transport)
  2. Environment variables (MATLAB_MCP_* prefix)
  3. config.yaml file (if found in current directory or via --config flag)
  4. Hardcoded defaults (documented in this page)

Validation

All configuration is validated by Pydantic models in src/matlab_mcp/config.py. Invalid values will produce clear error messages:

pydantic_core._pydantic_core.ValidationError: 1 validation error for PoolConfig
max_engines
  Input should be a valid integer, >= 2 [type=greater_than_equal, input_value=-1, input_type=int]

Configuration Data Flow

graph LR
    A["config.yaml<br/>YAML file"] -->|yaml.safe_load| B["Raw dict"]
    C["Environment<br/>MATLAB_MCP_*"] -->|os.environ| B
    B -->|Pydantic validate| D["AppConfig<br/>Typed models"]
    D -->|server.py| E["MatlabMCPServer<br/>state & tools"]
    style A fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e3f2fd
    style E fill:#e8f5e9
Loading
  1. Load YAML → config.yaml is parsed into a dict
  2. Apply env overrides → For each MATLAB_MCP_* env var, update the dict
  3. Validate → Pydantic models coerce types and validate constraints
  4. Use → Server passes config sections to subsystems (pool, jobs, security, etc.)

Troubleshooting Configuration

"Config file not found"

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

"Validation error: transport" Check that transport is one of: "stdio", "sse", "streamablehttp"

"Environment variable not taking effect" Check the prefix:

  • ✅ MATLAB_MCP_POOL_MAX_ENGINES=20
  • ❌ POOL_MAX_ENGINES=20 (missing MATLAB_MCP_ prefix)

"Auth token rejected" Verify token is set and being used:

echo $MATLAB_MCP_AUTH_TOKEN
# Should print the 64-char hex token

Related

Clone this wiki locally