# 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:

```bash
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:

```bash
# 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:**

```yaml
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:**

```yaml
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`:

```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:

```bash
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:**

```yaml
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:**

```bash
# 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:

```bash
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)

```yaml
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)

```yaml
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:**

```bash
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)

```yaml
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`.