# Configuration and Troubleshooting
This page shows you how to configure the Simulink® Agentic Toolkit. For an overview of the Simulink Agentic Toolkit, see the [README](README.md).

## Requirements

- **MATLAB R2023a or later** with **Simulink**
- A supported **AI coding agent** 
- **Simulink Test** *(optional)* — required only for the `model_test` tool
- **System Composer** *(optional)* — enables architecture modeling and component analysis
- **Requirements Toolbox** *(optional)* — enables requirements traceability; used in building-architecture-models skill
- **Simscape** *(optional)* — enables physical modeling domain support
- **Stateflow** *(optional)* — enables state machine and chart analysis


### Automated Setup Configuration

If you use automated setup using the 'setupAgenticToolkit' function, it writes two things: an MCP server configuration (so your agent can talk to MATLAB) and skill registrations (so your agent has Simulink expertise). The details vary by platform.

| Platform | MCP Configuration | Skills Delivery | How To Update Toolkit |
|----------|------------------|-----------------|-------------------|
| Claude Code | `~/.claude.json` (mcpServers) | `claude plugin` system | `setupAgenticToolkit("update")` |
| GitHub Copilot | VS Code user-profile `mcp.json` | `~/.agents/skills/` symlinks | `setupAgenticToolkit("update")` |
| OpenAI Codex | `~/.codex/config.toml` | `~/.agents/skills/` symlinks | `setupAgenticToolkit("update")` |
| Gemini CLI | `~/.gemini/settings.json` | `~/.agents/skills/` symlinks | `setupAgenticToolkit("update")` |
| Sourcegraph Amp | `~/.config/amp/settings.json` | `amp.skills.path` direct ref | `setupAgenticToolkit("update")` |

**How skill delivery works:** Claude Code uses the native `claude plugin` system — setup registers a marketplace and installs plugins automatically. Other platforms discover skills from `~/.agents/skills/` via symbolic links that setup creates pointing to the installed toolkit. When you re-run install, the linked skills update automatically. If new skills are added, re-run configure to create the additional links.

### Platform-Specific Notes

**Claude Code** — Setup writes MCP configuration to `~/.claude.json` and registers skills via the `claude plugin` system (marketplace + plugin install). If the `claude` CLI is not on PATH, setup falls back to skill symlinks in `~/.claude/skills/`.

**GitHub Copilot** — Setup writes global MCP config to the VS Code user-profile `mcp.json` (`~/Library/Application Support/Code/User/mcp.json` on macOS, `~/.config/Code/User/mcp.json` on Linux, `%APPDATA%\Code\User\mcp.json` on Windows) and creates skill symlinks in `~/.agents/skills/`. Reload VS Code after setup completes (Cmd/Ctrl + Shift + P, then "Developer: Reload Window").

**OpenAI Codex** — Setup writes `~/.codex/config.toml`. Skills are installed as global symlinks in `~/.agents/skills/`. After setup, you may want to tune two settings in the `[mcp_servers.matlab]` section of `~/.codex/config.toml`:
- `tool_timeout_sec = 600` — increases the tool timeout from the default (which is too short for many MATLAB operations like test suites and simulations). Increase further for very long-running tasks.
- `env_vars = ['WINDIR']` — **Windows only.** Required for Simulink to work, since Codex strips environment variables from MCP server subprocesses by default.

**Gemini CLI** — Setup writes global config to `~/.gemini/settings.json` and creates skill symlinks in `~/.agents/skills/`. Start a new Gemini session after setup.

**Sourcegraph Amp** — Setup writes to `~/.config/amp/settings.json` using the `amp.` prefix for all keys. Skills load directly from the toolkit via `amp.skills.path` (no symlinks needed). If you have `amp.mcpPermissions` rules that block MCP servers, setup will detect this and ask before making changes.


## Manual Setup Configuration

If you prefer to manage your own MCP server installation and agent configuration, you can set up the toolkit manually following the instructions in the [MATLAB MCP Server](https://github.com/matlab/matlab-mcp-core-server) repository to install the MCP server binary and configure it with your coding agent. For an overview of manual set up, see the [README](README.md).



## Update Simulink Agentic Toolkit

Run the update action in MATLAB to download the latest toolkit and MCP server:

```matlab
setupAgenticToolkit("update")
```

After updating:

1. **Re-run `satk_initialize`** in MATLAB to pick up any tool changes
2. **Restart your agent session** to load updated skills


## Other Setup Actions

The `setupAgenticToolkit` function supports several actions:

| Action | Command | Description |
|--------|---------|-------------|
| Install | `setupAgenticToolkit("install")` | Download MCP server and toolkit files, then configure |
| Configure | `setupAgenticToolkit("configure")` | Set up an agent with MCP and skills |
| Update | `setupAgenticToolkit("update")` | Download latest MCP server and toolkit files |
| Uninstall | `setupAgenticToolkit("uninstall")` | Remove installed toolkits and agent configurations |
| Status | `setupAgenticToolkit("status")` | Show current installation and configuration status |

All actions support `Prompt=false` for non-interactive use.

```matlab
setupAgenticToolkit("install", Toolkit=["matlab", "simulink"], Prompt=false)
setupAgenticToolkit("configure", Agents="claude-code", Scope="global", Prompt=false)
```

 If your organization uses a CLI wrapper, pass `AgentCLI="claude-code=/path/to/wrapper"` during configure.

### Custom Agent CLI Commands

If your organization uses a wrapper or alias for agent CLI binaries, use the `AgentCLI` parameter:

```matlab
setupAgenticToolkit("configure", AgentCLI="claude-code=/usr/local/bin/my-claude-wrapper")
```

The format is `"agent-id=command"`. This override is saved to `config.json` and automatically used for all subsequent actions (configure, uninstall). You only need to specify it once.

> **Note:** Currently only Claude Code uses a CLI during setup (for plugin registration via `claude plugin`). All other agents are configured via file writes and symlinks, so they do not need `AgentCLI`. If the Claude CLI is not found, setup falls back to symlinks automatically.

### Remove Agent Configurations

To remove agent configurations without uninstalling toolkits, run:

```matlab
setupAgenticToolkit("uninstall")
```

Then select **Agent configurations only** from the interactive prompt. This removes MCP config entries and skill registrations while keeping installed toolkits and the MCP server intact. Useful when switching agents or cleaning up stale configurations.


## Troubleshooting
| Problem | Likely Cause | Fix |
|---------|-------------|-----|
| Add-On Manager fails when opening mltbx (`ERR_CERT_AUTHORITY_INVALID` or "Unable to open the requested feature") | CEF/display issue — often caused by corporate proxies, antivirus software, or headless environments | Install programmatically instead: `matlab.addons.toolbox.installToolbox("agenticToolkitInstaller.mltbx")` |
| Agent doesn't list Simulink skills | Skills not registered | Re-run `setupAgenticToolkit("configure")` |
| MCP tools fail with "Undefined function" | `satk_initialize` not run in current MATLAB session | Run `satk_initialize` in MATLAB |
| MCP server can't connect to MATLAB | Connector not running or stale connection | Run `satk_initialize` again (it calls `shareMATLABSession` automatically) |
| macOS blocks the MCP server binary | Gatekeeper quarantine | Right-click → Open, or run: `xattr -d com.apple.quarantine ~/.matlab/agentic-toolkits/bin/matlab-mcp-server` |
| "rmiml.selectionLinkHelper" error | Path corruption from other toolboxes | Run `restoredefaultpath` in MATLAB, then re-run `satk_initialize` |
| `model_test` fails or is unavailable | Simulink Test not installed | Install Simulink Test, or use the other 7 tools which work without it |
| Codex tool calls time out | Default tool timeout too short for MATLAB | Add `tool_timeout_sec = 600` (or higher) to `[mcp_servers.matlab]` in `~/.codex/config.toml` |
| Simulink fails in Codex on Windows | Missing `WINDIR` environment variable | Add `env_vars = ['WINDIR']` to `[mcp_servers.matlab]` in `~/.codex/config.toml` |


## Report Bugs

If you encounter a bug, use the **filing-bug-reports** skill to generate a report before opening a GitHub issue. Ask your agent:

```
File a bug report for this issue
```

The skill automatically captures environment details, reproduction steps, and error output. **Run the skill in the same session where the bug occurred**, because it uses conversation context to reconstruct what happened. Then [open a bug report](https://github.com/matlab/simulink-agentic-toolkit/issues/new?template=bug_report.yml) and paste the generated report.


Copyright 2025-2026 The MathWorks, Inc.

---
