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 can be configured via config.yaml or environment variable overrides.

Configuration Methods

Method 1: YAML File

The server reads config.yaml from the current working directory by default:

matlab-mcp                           # Uses ./config.yaml
matlab-mcp --config ./my_config.yaml # Uses specified file

A default config.yaml is created on first run if none exists.

Method 2: Environment Variables

Every setting can be overridden via environment variables using the pattern:

MATLAB_MCP_<SECTION>_<SETTING_NAME>

Examples:

# Server settings
export MATLAB_MCP_SERVER_HOST=127.0.0.1
export MATLAB_MCP_SERVER_PORT=8765
export MATLAB_MCP_SERVER_TRANSPORT=streamablehttp

# Engine pool settings
export MATLAB_MCP_POOL_MIN_ENGINES=4
export MATLAB_MCP_POOL_MAX_ENGINES=16

# Execution timeouts
export MATLAB_MCP_EXECUTION_SYNC_TIMEOUT=60

# Authentication (HITL gates)
export MATLAB_MCP_HITL_ENABLED=true
export MATLAB_MCP_HITL_ALL_EXECUTE=true

# Bearer token authentication (HTTP transport)
export MATLAB_MCP_AUTH_TOKEN=my-secret-token-here

Variable naming: Section names are separated from setting names by underscores. For multi-word section names (e.g., code_checker), use the full name: MATLAB_MCP_CODE_CHECKER_ENABLED.

Configuration Options by Category

Server

Controls transport, binding, logging, and result storage.

Key Type Default Description
name string "matlab-mcp-server" Server identifier reported to MCP clients
transport "stdio" | "sse" | "streamablehttp" "stdio" Communication protocol: stdio (single-user, no network), sse (deprecated, multi-user via HTTP SSE), streamablehttp (multi-user via HTTP/2 streaming)
host string "127.0.0.1" Bind address for HTTP transports (SSE, streamablehttp). Use 127.0.0.1 to avoid Windows Firewall prompts on non-admin setups; use 0.0.0.0 for remote access (requires firewall exception)
port integer 8765 Bind port for HTTP transports
stateless_http boolean false When true with streamablehttp transport, do not maintain per-client session state; each request is independent
log_level "debug" | "info" | "warning" | "error" "info" Logging verbosity
log_file string (path) "./logs/server.log" Path to log file (created if directory exists)
result_dir string (path) "./results" Directory where result files are saved for large outputs
drain_timeout_seconds integer 300 Seconds to wait for active jobs during shutdown before force-terminating

Transport notes:

  • stdio (default): Communicates with a single MCP client via stdin/stdout. No network interface exposed. Best for single-user scenarios (Claude Desktop, Codex CLI on same machine).
  • sse (deprecated): HTTP Server-Sent Events. Supports multi-user via reverse proxy, but no built-in authentication. Will be removed in v3.0. See Agent-Onboarding for migration guide.
  • streamablehttp (recommended): FastMCP 3.2+ streaming HTTP transport. Supports multi-user with built-in bearer token authentication and session routing. Endpoint is /mcp.

Pool

Controls MATLAB engine lifecycle, pooling strategy, and health monitoring.

Key Type Default Description
min_engines integer 2 Minimum number of engines always kept warm (available). Set to 0 with --inspect flag for testing without MATLAB
max_engines integer 10 Hard ceiling on total engines (includes warm + active). Capped at 4 on macOS (MATLAB limit). Set min_engines ≤ max_engines
scale_down_idle_timeout integer 900 Seconds an engine can be idle before the pool scales it down (returns to OS). Set to 0 to disable scale-down. Typical: 900 (15 min)
engine_start_timeout integer 120 Seconds to wait for a new engine to start before timing out. Increase if your system is slow or MATLAB path lookup is expensive
health_check_interval integer 60 Seconds between periodic health pings. Set to 0 to disable. Lower values (e.g., 30) catch dead engines faster but add CPU overhead
proactive_warmup_threshold float 0.8 When pool utilization exceeds this ratio (0–1), the pool proactively spins up engines toward max_engines. Set to 1.0 to disable proactive warmup
queue_max_size integer 50 Maximum number of pending execution requests queued when all engines are busy. Excess requests are rejected with "queue full" error
matlab_root string or null null Explicit MATLAB installation path. When null, auto-detect via system MATLAB. Only set if auto-detection fails

macOS note: MATLAB on macOS enforces a 4-engine hard limit via licensing. The pool will log a warning if max_engines > 4 but will still allow configuration (respecting the actual MATLAB limit at runtime).

Execution

Controls job execution timeouts, workspace isolation, and temporary file handling.

Key Type Default Description
sync_timeout integer 30 Seconds before code execution is auto-promoted to async job. When exceeded, the tool returns immediately with job_id for polling. Increase for long-running analysis or data processing
max_execution_time integer 86400 Hard ceiling per job (seconds, default 24 hours). Prevents runaway jobs from consuming resources indefinitely
workspace_isolation boolean true When true, each session gets a fresh MATLAB workspace (clear all on new session). When false, workspace persists across clients (risky in multi-user setups)
engine_affinity boolean false When true, pin a session to the same engine for all jobs (enables persistent session state). When false, jobs use any available engine (load balancing, safer)
temp_dir string (path) "./temp" Base directory for per-session temporary files (scripts, uploaded data, figures). Per-session subdirectories are created automatically
temp_cleanup_on_disconnect boolean true When true, delete session temp directory and all files when client disconnects. When false, keep temp files for manual inspection/recovery

Example: Set sync_timeout: 120 for a server running long-running simulations; set to 5 for an interactive UI that must be responsive.

Workspace

Customizes MATLAB startup behavior for each engine.

Key Type Default Description
default_paths list of strings [] Paths to add to MATLAB path on engine startup (e.g., ["/shared/custom_libs", "/shared/data"])
startup_commands list of strings [] MATLAB commands to run on engine startup (e.g., ["format long", "setenv('TZ','UTC')"])

Example:

workspace:
  default_paths:
    - "/opt/custom_toolbox"
    - "/mnt/shared/data"
  startup_commands:
    - "format long"
    - "more off"
    - "set(0, 'DefaultFigureVisible', 'off')"

Toolboxes

Filters which MATLAB toolboxes are reported to agents via list_toolboxes tool.

Key Type Default Description
mode "whitelist" | "blacklist" | "all" "all" Filtering mode: whitelist (only listed toolboxes reported), blacklist (all except listed), all (report all)
list list of strings [] Toolbox names to whitelist/blacklist (e.g., ["Signal Processing Toolbox", "Image Processing Toolbox"])
Mode Behavior
"whitelist" Only toolboxes in list are reported to agents. Use for restricted environments or to guide agent toward supported toolboxes
"blacklist" All toolboxes EXCEPT those in list are reported. Use to hide deprecated or unavailable toolboxes
"all" All installed toolboxes reported; list is ignored

Example:

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

Custom Tools

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

Key Type Default Description
config_file string (path) "./custom_tools.yaml" Path to YAML file defining custom tools (see Custom Tools for schema)

Example custom_tools.yaml:

tools:
  - name: "signal_analysis"
    function: "my_signal_analysis"
    description: "Analyze a time-series signal"
    parameters:
      - name: "signal_data"
        type: "array"
        description: "1D time series"

Security

Controls code execution restrictions and file upload limits.

Key Type Default Description
blocked_functions_enabled boolean true Master switch for blocking dangerous MATLAB functions. When false, all functions are allowed (use with caution)
blocked_functions list of strings ["system", "unix", "dos", "!", "eval", "feval", "evalc", "evalin", "assignin", "perl", "python"] List of MATLAB functions/constructs to block. Checked via regex after stripping comments/strings to avoid false positives
max_upload_size_mb integer 100 Maximum file size for upload_data tool (MB). Prevents DoS via huge file uploads
require_proxy_auth boolean false When true on SSE transport, require clients to authenticate via HTTP Proxy-Authorization header. Set true for production multi-user deployments

Blocked functions examples:

  • "system" — blocks system('ls'), system cmd arg1 arg2, etc.
  • "!" — blocks shell escapes like ! ls -la
  • "eval" — blocks eval(), evalc(), evalin(), feval() (all variants)
  • "perl", "python" — blocks calling external interpreters

The validator automatically ignores matches inside MATLAB comments (%) and string literals ('...', "..."), so disp('system') will not trigger a false block.

Code Checker

Configures optional MATLAB static analysis (checkcode tool).

Key Type Default Description
enabled boolean true Enable the check_code tool for MATLAB linting
auto_check_before_execute boolean false When true, automatically lint code before execution (may slow down interactive use). When false, agents can opt-in via the check_code tool
severity_levels list of strings ["error", "warning"] Which severity levels to report: ["error"] (strict), ["error", "warning"] (default), ["error", "warning", "info"] (verbose)

Output

Controls result formatting, figure conversion, and display limits.

Key Type Default Description
plotly_conversion boolean true Automatically convert MATLAB figures to interactive Plotly JSON for agent display
static_image_format "png" | "jpg" | "svg" "png" Fallback format for figures when Plotly conversion unavailable. PNG is best for general use, SVG for vector graphics
static_image_dpi integer 150 DPI for rasterized figures. Increase to 300 for print-quality images (larger files)
thumbnail_enabled boolean true Generate base64-encoded thumbnail images for quick display in agent UIs
thumbnail_max_width integer 400 Thumbnail max width (pixels). Height scales proportionally
large_result_threshold integer 10000 Number of elements: results with more than this many elements are saved to disk instead of inline. Use 10000 for typical scenarios, increase to 100000 for high-volume data processing
max_inline_text_length integer 50000 Characters: text output longer than this is saved to file instead of inlined in the response

Rationale: Inline results are fast but consume message size. Large results saved to disk can be read by agents separately via read_data tool.

Sessions

Manages client session lifecycle, isolation, and job retention.

Key Type Default Description
max_sessions integer 50 Maximum concurrent sessions. New sessions are rejected when limit is reached. Increase for high-concurrency deployments
session_timeout integer 3600 Seconds of inactivity before a session is cleaned up (default 1 hour). Reduce for ephemeral sessions, increase for long-running analysis
job_retention_seconds integer 86400 Seconds to retain completed job metadata after completion (default 24 hours). Agents can still query get_job_result for this window

Session isolation: Each session gets its own temporary directory (temp_dir/session_<id>/). When the session times out or disconnects, the directory is deleted if temp_cleanup_on_disconnect: true.

Monitoring

Enables metrics collection, persistent storage, and web dashboard.

Key Type Default Description
enabled boolean true Master switch for metrics collection. When false, the get_server_metrics, get_server_health, get_error_log tools are disabled
sample_interval integer 10 Seconds between periodic metric samples (pool util, job counts, execution times). Lower values (e.g., 5) increase accuracy but add CPU/I/O overhead
retention_days integer 7 Days to keep historical metrics in the SQLite database. Older samples are pruned automatically (cron-like every sample interval)
db_path string (path) "./monitoring/metrics.db" SQLite database file for metric persistence. Directory created if it doesn't exist
dashboard_enabled boolean true When true with stdio transport, serve a web dashboard at http://127.0.0.1:8766/dashboard. When false, monitoring data is still collected but no web UI
http_port integer 8766 Port for the monitoring dashboard (stdio transport only). For HTTP/SSE transports, the dashboard is served alongside the MCP endpoint

Dependencies: Monitoring requires optional packages (psutil, aiosqlite). Install with:

pip install -e ".[monitoring]"

HITL (Human-in-the-Loop Approval)

Configures approval gates for sensitive operations (execute code, file operations).

Key Type Default Description
enabled boolean false Master switch. When false, no approval prompts appear; all operations proceed immediately. When true, operations matching the gate conditions pause and prompt for approval
protected_functions list of strings [] MATLAB function names that require approval (e.g., ["eval", "system", "mkdir"]). Only checked when enabled: true. Empty list means no function-level protection (use all_execute: true instead)
protect_file_ops boolean false When true, file upload (upload_data) and delete (delete_file) operations require approval
all_execute boolean false When true, ALL code execution (via execute_code tool) requires approval, regardless of function names. Useful for human-supervised autonomous agents

Approval flow:

  1. Agent calls a gated tool (e.g., execute_code with a protected function).
  2. Server sends an elicitation request to the human via MCP (appears as a prompt in the agent UI).
  3. Human approves, declines, or cancels.
  4. Server continues (approved) or rejects (declined/cancelled) the operation.

Example:

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

With this config:

  • Calling execute_code("eval(...)") requires approval.
  • Calling execute_code("disp('hello')") does NOT require approval.
  • Calling upload_data(...) or delete_file(...) requires approval.

Authentication (HTTP Transport)

Configures bearer token authentication for HTTP/SSE transports (not used in stdio).

Key Type Default Description
Token source Environment variable MATLAB_MCP_AUTH_TOKEN Bearer token value. Set this env var; token is read at server startup. Must be a string (typically 32–64 random characters). No config file setting — always use env var for security

Usage:

# Generate a random token
export MATLAB_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))")

# Or use the CLI to generate one
matlab-mcp --generate-token
# Outputs: MATLAB_MCP_AUTH_TOKEN=abc123def456...

# Start server with HTTP transport + auth
export MATLAB_MCP_TRANSPORT=streamablehttp
matlab-mcp

For MCP clients:

When connecting to the HTTP endpoint, include the Authorization: Bearer <token> header:

curl -H "Authorization: Bearer abc123def456..." http://127.0.0.1:8765/mcp

See Agent-Onboarding for agent-specific configuration examples (Claude Code, Codex CLI, Cursor).

Health check bypass: The /health endpoint does NOT require authentication (for load balancer probing and diagnostics).

Example Configurations

Minimal Config (Single-User, Local)

server:
  transport: "stdio"
  log_level: "info"

pool:
  min_engines: 1
  max_engines: 2

execution:
  sync_timeout: 30

monitoring:
  enabled: false

Use case: Local development, single user, no network, no auth needed.

Production Multi-User (HTTP + Auth)

server:
  transport: "streamablehttp"
  host: "0.0.0.0"  # Or 127.0.0.1 if behind a reverse proxy
  port: 8765
  log_level: "warning"

pool:
  min_engines: 4
  max_engines: 16
  health_check_interval: 30

execution:
  sync_timeout: 60
  max_execution_time: 3600  # 1h limit per job
  temp_cleanup_on_disconnect: true

security:
  blocked_functions_enabled: true
  max_upload_size_mb: 500

monitoring:
  enabled: true
  sample_interval: 5
  retention_days: 30
  db_path: "/var/lib/matlab_mcp/metrics.db"

hitl:
  enabled: true
  all_execute: false  # Approvals only for protected functions
  protected_functions: ["eval", "system", "assignin"]
  protect_file_ops: true

Deploy with:

export MATLAB_MCP_AUTH_TOKEN=<generated-token>
matlab-mcp --config /etc/matlab_mcp/config.yaml

Use case: Multi-user SaaS, network-exposed, strict audit trail (all executions logged and approved).

High-Performance (Large Pool, Long Timeouts)

pool:
  min_engines: 8
  max_engines: 32
  scale_down_idle_timeout: 1800  # 30 min
  health_check_interval: 120
  proactive_warmup_threshold: 0.6

execution:
  sync_timeout: 300  # 5 min for long-running jobs
  max_execution_time: 86400  # 24h

output:
  large_result_threshold: 1000000  # 1M elements before saving to disk

Use case: Batch processing, scientific computing, analysis workflows.

Troubleshooting Configuration

"MATLAB Engine failed to start"

  • Check: pool.matlab_root — is MATLAB installed? Run matlab -batch "disp(matlabroot)" to find the path.
  • Fix: Set matlab_root: "/path/to/matlab" in config, or ensure matlab is in your PATH.

"Queue full; rejected"

  • Check: pool.queue_max_size and pool.max_engines.
  • Fix: Increase max_engines or queue_max_size. Or reduce client concurrency.

"Sync timeout; promoted to async"

  • Check: execution.sync_timeout — too aggressive?
  • Fix: Increase for long-running code. Or enable hitl.all_execute: true to gate expensive operations.

"Bearer token invalid" (HTTP transport)

  • Check: MATLAB_MCP_AUTH_TOKEN env var is set and matches client header.
  • Fix: Regenerate via matlab-mcp --generate-token and update client configs.

Large monitoring database

  • Check: monitoring.retention_days — too high?
  • Fix: Reduce to 3 or 7. Or disable monitoring: monitoring.enabled: false.

Clone this wiki locally