2026.04.10 release

Michelle Hirsch · Michelle Hirsch · commit a08de4661088 · 2026-04-10T11:20:57.000-05:00
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "toolkit",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "Setup and management for the MATLAB Agentic Toolkit. Detects MATLAB, installs the MCP server, registers the Claude Code plugin, and verifies the environment.",
       "author": {
         "name": "MathWorks"
@@ -20,7 +20,7 @@
     },
     {
       "name": "matlab-core",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "MATLAB skills and MCP tools for AI coding agents. Testing, debugging, reviewing code, creating Live Scripts, building apps, and modernizing code.",
       "author": {
         "name": "MathWorks"
diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
@@ -80,7 +80,7 @@ Setup writes two things: an MCP server configuration (so your agent can talk to
 
 | Platform | MCP Configuration | Skills Delivery | How To Update Toolkit |
 |----------|------------------|-----------------|-------------------|
-| Claude Code | `~/.claude/.mcp.json` | Plugin cache | Re-run setup or reinstall plugin |
+| Claude Code | `~/.claude/settings.json` | Plugin cache | Re-run setup or reinstall plugin |
 | GitHub Copilot | `~/.vscode/settings.json` | `~/.agents/skills/` symlinks | `git pull` in toolkit repo, re-run setup |
 | OpenAI Codex | `~/.codex/config.toml` | `~/.agents/skills/` symlinks | `git pull` in toolkit repo, re-run setup |
 | Gemini CLI | `~/.gemini/settings.json` | `~/.agents/skills/` symlinks | `git pull` in toolkit repo, re-run setup |
@@ -94,7 +94,7 @@ Setup writes two things: an MCP server configuration (so your agent can talk to
 
 ### Platform-Specific Notes
 
-**Claude Code** — Setup registers the toolkit via the plugin marketplace and writes MCP config to `~/.claude/.mcp.json`. Skills are cached by the plugin system. To re-run setup, use `/matlab-setup` or ask Claude to set up the toolkit.
+**Claude Code** — Setup registers the toolkit via the plugin marketplace and uses `claude mcp add -s user` to register the MCP server globally. Skills are cached by the plugin system. To re-run setup, use `/matlab-setup` or ask Claude to set up the toolkit.
 
 **GitHub Copilot** — Setup writes global MCP config to `~/.vscode/settings.json` and creates skill symlinks in `~/.agents/skills/`. Reload VS Code after setup completes (Cmd/Ctrl + Shift + P, then "Developer: Reload Window").
 
@@ -308,6 +308,38 @@ The MCP server binary is released independently from the toolkit. To update it:
 
 ---
 
+## Per-Project Configuration
+
+Automated setup configures the toolkit **globally** — MATLAB tools and skills are available in every session regardless of which project you open. Global configuration is the easiest way to get started since it just works whenever you create or open a project.
+
+You can also configure the MCP server at the project level. This keeps your tools and skills scoped to the projects that need them, and it helps teams — when the config is committed to version control, anyone who clones the repo gets the MATLAB connection automatically (provided they have the MCP server binary installed; see [Installing the MCP Server Manually](#installing-the-mcp-server-manually)).
+
+### Template files
+
+The [`templates/`](templates/) directory contains starter configurations for each platform. Copy the appropriate template into the root folder of your project, update the paths, and commit it to version control.
+
+| Platform | Template | Project location |
+|----------|----------|-----------------|
+| GitHub Copilot | `templates/vscode-mcp.json` | `.vscode/mcp.json` |
+| Cursor | `templates/mcp.json` | `.cursor/mcp.json` |
+| Sourcegraph Amp | `templates/amp-settings.json` | `.amp/settings.json` |
+| OpenAI Codex | `templates/codex-mcp.json` | `.codex/config.json` in project root |
+
+> **Claude Code** uses `claude plugin install` with scope selection (per-project, per-user, or global) rather than a project config file. See [Adding Skills Only](#adding-skills-only).
+
+### Example: GitHub Copilot
+
+```bash
+mkdir -p .vscode
+cp /path/to/matlab-agentic-toolkit/templates/vscode-mcp.json .vscode/mcp.json
+```
+
+Then edit `.vscode/mcp.json` to replace the placeholder paths with your actual MCP server binary and MATLAB root paths.
+
+> **Note:** Per-project configs contain absolute paths to the MCP server binary and MATLAB root, which vary across machines. If your team uses different OS platforms or install locations, consider documenting the expected paths in your project README.
+
+---
+
 ## Troubleshooting
 
 | Problem | Likely Cause | Fix |
diff --git a/skills-catalog/toolkit/matlab-agentic-toolkit-setup/SKILL.md b/skills-catalog/toolkit/matlab-agentic-toolkit-setup/SKILL.md
@@ -4,7 +4,7 @@ description: Install and configure the MATLAB Agentic Toolkit — detect MATLAB,
 license: MathWorks BSD-3-Clause
 metadata:
   author: MathWorks
-  version: "1.0"
+  version: "1.1"
 ---
 
 # MATLAB Agentic Toolkit Setup
@@ -17,6 +17,38 @@ Automated onboarding for the MATLAB Agentic Toolkit. Detects MATLAB, downloads a
 
 This skill does NOT require the MATLAB MCP server — it uses shell commands for everything until the final verification step.
 
+## Welcome Message
+
+Before doing any work, print a welcome message to the user. This sets expectations for what's about to happen and why they may be asked to approve actions. Use a friendly, personal tone with "I" statements. The message should cover:
+
+```
+Welcome! My goal is to get you set up with the MATLAB Agentic Toolkit so you
+can use MATLAB tools and skills with your agent for your projects.
+
+Here's what I'll do:
+
+1. Look around your computer to find your MATLAB installation(s) and check
+   whether the MCP server is already installed. Depending on your permissions
+   settings, you may be asked to approve some of these steps — I'm just
+   reading system info, not changing anything yet.
+
+2. Come back to you with a plan showing what I found and what I'd like to
+   configure. You'll have a chance to adjust any choices before I make changes.
+
+3. Once you approve, I'll install the MCP server (if needed), configure your
+   agent to use it for your other projects, and verify the connection to MATLAB.
+
+This setup configures everything globally — once it's done, MATLAB tools and
+skills will be available in every session, regardless of which project you're
+working in. This is the easiest way to get started. If you later want to scope
+the configuration to specific projects, the Getting Started guide covers that.
+
+If you'd rather set things up manually, the Getting Started guide has
+step-by-step instructions: GETTING_STARTED.md
+```
+
+Adapt the wording naturally — don't recite it verbatim — but cover all three points. After printing the welcome message, proceed directly to Phase 1 without waiting for a response.
+
 ## When to Use
 
 - User runs `/matlab-setup` or asks to set up the MATLAB Agentic Toolkit
@@ -46,6 +78,8 @@ The goal is to ask the user **once** for all decisions, then execute without fur
 
 ## Phase 1: Discovery
 
+Print a brief status message before starting: **"Scanning your system for MATLAB installations and checking the current setup. You may be asked to approve some read-only commands — I'm just gathering information, not making any changes yet."**
+
 Run all of these checks silently — do not prompt the user during this phase. Collect all results for presentation in Phase 2.
 
 ### 1a. Detect platform
@@ -107,6 +141,12 @@ For other platforms, check if their global config files already have a `matlab`
 
 Check environment and CLI tools: `claude --version` (Claude Code), `$CURSOR_TRACE` (Cursor), `codex --version` (Codex), `amp --version` (Amp), `gemini --version` (Gemini CLI), `$VSCODE_*` (Copilot). If ambiguous, ask the user.
 
+### 1g. Check for legacy artifacts
+
+Read the platform-specific reference file and check for any items listed in its **Legacy Artifacts** section (if present). Record what was found — these will be shown in the plan and cleaned up during Phase 3.
+
+**Reference file resolution:** On re-runs (when `~/.matlab-agentic-toolkit/config.json` exists), resolve reference files from `toolkitRoot` in that config (e.g., `<toolkitRoot>/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/<filename>`), not from the skill's base directory. This avoids reading stale cached versions when the skill is loaded from a plugin cache.
+
 ---
 
 ## Phase 2: Plan
@@ -135,6 +175,7 @@ Proposed actions:
   MCP server:    Download v0.7.0 to ~/.local/bin/matlab-mcp-core-server
   Display mode:  nodesktop (MATLAB runs headless; windows still open for plots)
   Agent config:  Configure MCP server globally (available in all sessions)
+  Migration:     (none)
 
 Proceed with this plan? You can adjust any choice:
   - Pick a different MATLAB: "use 2" or provide a path
@@ -143,6 +184,8 @@ Proceed with this plan? You can adjust any choice:
   - Configure a different agent: "use Cursor" or "use Amp"
 ```
 
+The **Migration** row shows legacy artifacts found in Phase 1g. If none were found, show `(none)`. If artifacts were found, list what will be cleaned up, e.g., `Remove ~/.claude/.mcp.json (migrated to claude mcp add)`.
+
 For non-Claude platforms, clearly note "EXPERIMENTAL — untested, provided as-is" and that manual fallback will be provided if automated setup fails.
 
 For OpenAI Codex specifically, the plan must cover **both**:
@@ -170,6 +213,8 @@ Once the user confirms — move to Phase 3. If they adjust choices, update the p
 
 ## Phase 3: Execute
 
+Print a brief status message before starting: **"Great — executing the plan now. I'll be downloading, writing config files, and registering skills. You may be asked to approve some of these actions depending on your permissions settings."**
+
 Carry out the approved plan. Do NOT prompt the user during this phase — all decisions were made in Phase 2.
 
 ### 3a. Install MCP server (if needed)
@@ -188,6 +233,10 @@ Verify: `~/.local/bin/matlab-mcp-core-server --version`
 
 If download fails, provide the direct URL for manual download.
 
+### 3b-migrate. Clean up legacy artifacts
+
+If Phase 1g found any legacy artifacts, clean them up now according to the instructions in the platform reference file's **Legacy Artifacts** section. Only remove artifacts after the new configuration has been written successfully (i.e., run this after 3b-platform, not before).
+
 ### 3b-shared. Register global skills (Copilot, Codex, Gemini)
 
 For platforms that discover skills from `~/.agents/skills/` — GitHub Copilot, OpenAI Codex, and Gemini CLI — create symlinks pointing back to the toolkit repo. This only needs to run once, even if multiple platforms are configured.
@@ -251,13 +300,53 @@ Echo back:
 - File path: `~/.vscode/settings.json`
 - MATLAB entry was added/updated
 
+#### Claude Code
+
+Uses `claude mcp add` CLI to register the MCP server globally. Do NOT write `~/.claude/.mcp.json` manually — that file is not read by Claude Code.
+
+**Step 1: Add the marketplace**
+
+```bash
+claude plugin marketplace add "https://github.com/matlab/matlab-agentic-toolkit"
+```
+
+If already registered, this is a no-op.
+
+**Step 2: Install plugins**
+
+```bash
+claude plugin install matlab-core@matlab-agentic-toolkit
+claude plugin install toolkit@matlab-agentic-toolkit
+```
+
+Claude's native prompt will ask the user to choose scope. Do NOT implement your own scope selection.
+
+**Step 3: Register MCP server**
+
+```bash
+claude mcp add-json -s user matlab '{"command":"<MCP_SERVER_PATH>","args":["--matlab-root","<MATLAB_ROOT>","--matlab-display-mode","<DISPLAY_MODE>"]}'
+```
+
+This registers the server at user scope (available in all projects). If a `matlab` entry already exists, it is overwritten. MCP tools become available in the next session.
+
+**Step 4: Verify plugin installation**
+
+```bash
+claude plugin list 2>&1
+```
+
+If `claude` CLI plugin commands fail, skip plugin installation — skills can be used by reading SKILL.md files directly. The MCP registration (Step 3) works independently via `claude mcp add`, which is a core CLI command.
+
+Echo back the `claude mcp add-json` command that was run and confirm it succeeded.
+
+See `reference/claude-code-setup-guidance.md` for legacy artifact cleanup and additional troubleshooting details.
+
 #### Other platforms
 
 **Read** the platform-specific reference file (located in the `reference/` directory next to this skill file) and follow its instructions exactly. Use the toolkit root to resolve the path: `<TOOLKIT_ROOT>/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/<filename>`.
 
 | Platform | Reference file |
 |----------|---------------|
-| Claude Code | `reference/claude-code-setup-guidance.md` |
 | Cursor | `reference/cursor-setup-guidance.md` |
 | OpenAI Codex | `reference/codex-setup-guidance.md` |
 | Sourcegraph Amp | `reference/amp-setup-guidance.md` |
@@ -286,14 +375,19 @@ mkdir -p ~/.matlab-agentic-toolkit
   "mcpServerVersion": "<VERSION>",
   "displayMode": "<DISPLAY_MODE>",
   "configuredPlatforms": ["<PLATFORM>"],
+  "setupSkillVersion": "<SKILL_VERSION>",
   "lastSetup": "<ISO_8601_TIMESTAMP>"
 }
 ```
 
+The `setupSkillVersion` field records the skill `metadata.version` from the YAML front matter of this file. This allows future runs to detect when the skill has been updated and whether migration steps may apply.
+
 ---
 
 ## Phase 4: Verify
 
+Print a brief status message: **"Setup is done — verifying the connection to MATLAB."**
+
 Verification depends on the agent platform.
 
 ### Claude Code
diff --git a/skills-catalog/toolkit/matlab-agentic-toolkit-setup/manifest.yaml b/skills-catalog/toolkit/matlab-agentic-toolkit-setup/manifest.yaml
@@ -2,7 +2,7 @@
 schema_version: 1
 license: MathWorks BSD-3-Clause
 scope: cross-product
-version: "2.0"
+version: "2.1"
 matlab-release: ">=R2020b"
 requires-tools: []
 requires-skills: []
diff --git a/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/claude-code-setup-guidance.md b/skills-catalog/toolkit/matlab-agentic-toolkit-setup/reference/claude-code-setup-guidance.md
@@ -6,11 +6,11 @@ This reference file contains Claude Code-specific instructions for Phase 3b of t
 
 ## Overview
 
-Claude Code uses a plugin system with a marketplace. The `matlab-core` plugin delivers MATLAB skills but does **not** ship MCP server configuration (MCP config is system-specific and can't be meaningfully defaulted). The setup skill writes `~/.claude/.mcp.json` with absolute paths for the binary and MATLAB root.
+Claude Code uses a plugin system with a marketplace. The `matlab-core` plugin delivers MATLAB skills but does **not** ship MCP server configuration (MCP config is system-specific and can't be meaningfully defaulted). The setup skill registers the MCP server using the `claude mcp add` CLI command, which writes to the correct location automatically.
 
 ## Global Config Path
 
-MCP server config: `~/.claude/.mcp.json` (user-level, written by setup skill).
+MCP server config is managed by the `claude mcp add -s user` command, which writes to `~/.claude/settings.json` under the `mcpServers` key. Do NOT write MCP config files manually — always use the CLI.
 
 ## Phase 3b: Register Plugin
 
@@ -31,22 +31,19 @@ claude plugin install toolkit@matlab-agentic-toolkit
 
 Claude's native prompt will ask the user to choose scope for each plugin. Do NOT implement your own scope selection — let Claude Code handle it.
 
-### Step 3: Write MCP server config
+### Step 3: Register MCP server
 
-Write `~/.claude/.mcp.json` with the detected binary path and MATLAB root:
+Use the `claude mcp add` CLI to register the MATLAB MCP server at user scope (available in all projects):
 
-```json
-{
-  "mcpServers": {
-    "matlab": {
-      "command": "<MCP_SERVER_PATH>",
-      "args": ["--matlab-root", "<MATLAB_ROOT>", "--matlab-display-mode", "<DISPLAY_MODE>"]
-    }
-  }
-}
+```bash
+claude mcp add-json -s user matlab '{"command":"<MCP_SERVER_PATH>","args":["--matlab-root","<MATLAB_ROOT>","--matlab-display-mode","<DISPLAY_MODE>"]}'
 ```
 
-Replace `<MCP_SERVER_PATH>`, `<MATLAB_ROOT>`, and `<DISPLAY_MODE>` with the values from the setup plan. The MCP tools become available in the next session (or immediately if the session is restarted).
+Replace `<MCP_SERVER_PATH>`, `<MATLAB_ROOT>`, and `<DISPLAY_MODE>` with the values from the setup plan.
+
+**Important:** This command must run at the system terminal (via the Bash tool), not as an inline Claude Code command. If a `matlab` entry already exists, the command will overwrite it.
+
+The MCP tools become available in the next session (or immediately if the session is restarted).
 
 ### Step 4: Verify plugin installation
 
@@ -62,7 +59,49 @@ If `claude` CLI commands fail (e.g., not available in the user's Claude Code ver
 
 1. Report the error clearly
 2. Skip plugin installation — skills can be used by reading SKILL.md files directly from the repo
-3. The MCP config (Step 3) still works independently of the plugin system
+3. The MCP server registration (Step 3) still works independently of the plugin system — `claude mcp add` is a core CLI command available in all versions that support MCP
+
+## Legacy Artifacts
+
+Check for these artifacts from previous setup approaches. If found during Phase 1g, record them for the plan and clean them up during Phase 3b-migrate.
+
+### `~/.claude/.mcp.json` with `matlab` entry
+
+Earlier versions of the setup skill wrote MCP config directly to `~/.claude/.mcp.json`. This file is no longer used — MCP servers are now registered via `claude mcp add -s user`, which writes to `~/.claude/settings.json`.
+
+**Detection (Phase 1g):**
+
+```bash
+cat ~/.claude/.mcp.json 2>/dev/null | grep -l matlab
+```
+
+If the file exists and contains a `matlab` entry, flag it as a legacy artifact.
+
+**Cleanup (Phase 3b-migrate):**
+
+1. Confirm that the new MCP config has been written successfully (Step 3 of Phase 3b completed).
+2. Remove the `matlab` entry from `~/.claude/.mcp.json`. If `matlab` was the only entry, delete the file entirely. If other entries exist, remove only the `matlab` key and preserve the rest.
+
+```bash
+# Check if matlab is the only server entry
+python3 -c "
+import json, os, sys
+p = os.path.expanduser('~/.claude/.mcp.json')
+with open(p) as f:
+    data = json.load(f)
+servers = data.get('mcpServers', {})
+if 'matlab' in servers:
+    del servers['matlab']
+if not servers:
+    os.remove(p)
+    print('Removed ~/.claude/.mcp.json (matlab was the only entry)')
+else:
+    data['mcpServers'] = servers
+    with open(p, 'w') as f:
+        json.dump(data, f, indent=2)
+    print('Removed matlab entry from ~/.claude/.mcp.json (preserved other entries)')
+"
+```
 
 ## Verification
 
