feat: migrate .copilot/mcp-config.json -> .mcp.json (Copilot CLI auto-load path)

.changeset/mcp-frontmatter-init.md

@@ -3,4 +3,4 @@
 "@bradygaster/squad-sdk": minor
 ---
 
-Add `squad init --mcp-frontmatter` to write MCP server config into the Squad agent frontmatter instead of `.copilot/mcp-config.json` for compatible agent harnesses.
+Add `squad init --mcp-frontmatter` to write MCP server config into the Squad agent frontmatter instead of `.mcp.json` (repo root) for compatible agent harnesses.

.changeset/mcp-json-migration.md

@@ -0,0 +1,23 @@
+---
+"@bradygaster/squad-cli": minor
+"@bradygaster/squad-sdk": minor
+---
+
+Migrate per-repo MCP server config from `.copilot/mcp-config.json` to `.mcp.json` at the repo root.
+
+`.mcp.json` is the workspace-level MCP config path that GitHub Copilot CLI auto-loads (see `copilot mcp --help`, verified on Copilot CLI 1.0.58+). The legacy `.copilot/mcp-config.json` location was never auto-loaded — users had to pass `--additional-mcp-config .copilot/mcp-config.json` on every invocation, and most teams never noticed their MCP servers weren't actually loading. Closes the loop on [github/copilot-cli#3642](https://github.com/github/copilot-cli/issues/3642).
+
+**What changes:**
+
+- `squad init` (both `squad init` SDK flow and the legacy `index.cjs` entry) now writes the sample MCP config to `.mcp.json` at the repo root instead of `.copilot/mcp-config.json`.
+- `squad init --mcp-frontmatter` still writes into the agent frontmatter and does not touch either file.
+- Templates, internal docs, and user-facing docs (`features/mcp.md`, `concepts/portability.md`, `reference/config.md`, `features/enterprise-platforms.md`, `features/notifications.md`) now lead with `.mcp.json` and explain `~/.copilot/mcp-config.json` as the user-level fallback.
+- The JSON schema (`{ mcpServers: { ... } }`) is unchanged — only the file path moves.
+
+**Migration (Phase 2 — automatic):**
+
+`squad upgrade` now folds any pre-existing `.copilot/mcp-config.json` into `.mcp.json` at the repo root and reports the count migrated. Conflict policy: when the same server name is defined in both files with different `command`/`args`/`env`, the workspace `.mcp.json` wins and a warning is printed so the user can reconcile. The legacy file is preserved (not deleted) for one deprecation cycle so users can verify the merge — delete it manually once you have confirmed the new file works.
+
+During the same window, `squad init` dual-writes the `squad_state` pin into both `.mcp.json` (always) and a pre-existing `.copilot/mcp-config.json` (only if already present). Fresh inits never create the legacy file — the migration is one-way. The user-level `~/.copilot/mcp-config.json` path is unaffected.
+
+If you prefer to migrate by hand, the recipe in `docs/features/mcp.md` still applies — `squad upgrade` just does it for you.

.github/agents/squad.agent.md

@@ -449,7 +449,7 @@ When spawning agents, include an `MCP TOOLS AVAILABLE` block in the prompt (see
 Never crash or halt because an MCP tool is missing. MCP tools are enhancements, not dependencies.
 
 1. **CLI fallback** — GitHub MCP missing → use `gh` CLI. Azure MCP missing → use `az` CLI.
-2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.copilot/mcp-config.json`."
+2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.mcp.json` at the repo root (the path Copilot CLI auto-loads)."
 3. **Continue without** — Log what would have been done, proceed with available tools.
 
 ### Eager Execution Philosophy

.squad-templates/mcp-config.md

@@ -5,10 +5,12 @@ MCP (Model Context Protocol) servers extend Squad with tools for external servic
 ## Config File Locations
 
 Users configure MCP servers at these locations (checked in priority order):
-1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
-2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
-3. **User-level:** `~/.copilot/mcp-config.json` (personal)
-4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+1. **Repository-level (auto-loaded):** `.mcp.json` at the repo root — team-shared, committed; this is the workspace path Copilot CLI auto-loads (see `copilot mcp --help`).
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces).
+3. **User-level:** `~/.copilot/mcp-config.json` (personal, user-wide).
+4. **CLI override:** `--additional-mcp-config <path>` (session-specific).
+
+> **Migration note:** Older Squad versions wrote the per-repo config to `.copilot/mcp-config.json`. That path was not auto-loaded by Copilot CLI and required `--additional-mcp-config`. New `squad init` writes `.mcp.json` instead. If your repo still has a `.copilot/mcp-config.json`, it is preserved as-is — see `docs/features/mcp.md` for a manual merge recipe until `squad upgrade` ships a guided merge.
 
 ## Sample Config — Trello
 

.squad-templates/squad.agent.md

@@ -449,7 +449,7 @@ When spawning agents, include an `MCP TOOLS AVAILABLE` block in the prompt (see
 Never crash or halt because an MCP tool is missing. MCP tools are enhancements, not dependencies.
 
 1. **CLI fallback** — GitHub MCP missing → use `gh` CLI. Azure MCP missing → use `az` CLI.
-2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.copilot/mcp-config.json`."
+2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.mcp.json` at the repo root (the path Copilot CLI auto-loads)."
 3. **Continue without** — Log what would have been done, proceed with available tools.
 
 ### Eager Execution Philosophy

docs/src/content/docs/concepts/portability.md

@@ -226,7 +226,7 @@ MCP (Model Context Protocol) servers extend Squad with external services. Agents
 
 | Platform | Config File |
 |----------|------------|
-| **Copilot CLI** | `.copilot/mcp-config.json` |
+| **Copilot CLI** | `.mcp.json` (project, repo root) |
 | **VS Code** | `.vscode/settings.json` (under `copilot.mcp.servers`) |
 
 ### Example: GitHub MCP

docs/src/content/docs/features/enterprise-platforms.md

@@ -104,7 +104,7 @@ Squad uses the Azure CLI for ADO authentication — **no Personal Access Tokens
 
 For GitHub repositories, Squad uses the `gh` CLI for authentication. When working across multiple GitHub accounts (e.g., personal GitHub and Enterprise Managed Users), use `gh auth switch` to toggle between accounts. See [Cross-organization authentication](../scenarios/cross-org-auth) for detailed multi-account setup.
 
-Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. Add it to `.copilot/mcp-config.json`:
+Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. Add it to `.mcp.json` at the repo root (the path Copilot CLI auto-loads):
 
 ```json
 {

docs/src/content/docs/features/mcp.md

@@ -25,14 +25,17 @@ MCP bridges Squad agents and external services. Agents use MCP tools to send not
 
 ## MCP Configuration Files
 
-There are two places to configure MCP, depending on your platform:
+There are two scopes to configure MCP, depending on whether the servers are shared with your team or personal to you:
 
-| Platform | Config File | How to Edit | Startup |
-|----------|------------|-----------|---------|
-| **Copilot CLI** | `.copilot/mcp-config.json` | Text editor | Add to shell initialization (`~/.bashrc`, `~/.zshrc`, etc.) |
-| **VS Code** | `.vscode/settings.json` | VS Code Settings GUI or JSON editor | Built-in; restarts Copilot extension |
+| Scope | Config File | How to Edit | Loaded By |
+|-------|-------------|-------------|-----------|
+| **Project (team-shared)** | `.mcp.json` (at repo root) | Text editor; commit to the repo | Auto-loaded by Copilot CLI (`copilot mcp --help`); also discovered by VS Code workspaces. **This is what `squad init` writes.** |
+| **User (personal)** | `~/.copilot/mcp-config.json` | Text editor | Loaded by Copilot CLI globally for your account |
+| **VS Code workspace** | `.vscode/mcp.json` or `.vscode/settings.json` | VS Code Settings GUI or JSON editor | Built-in; restarts Copilot extension |
 
-This guide covers both. Pick the one that matches your workflow.
+This guide covers all three. Pick the one that matches your workflow.
+
+> **Migration note:** Squad ≤ 0.9.x wrote the per-repo config to `.copilot/mcp-config.json`. That path is **not** auto-loaded by Copilot CLI (it required the `--additional-mcp-config` flag). Newer `squad init` writes `.mcp.json` instead. If your repo already has both files, see the "Migrating from `.copilot/mcp-config.json`" section below.
 
 ---
 
@@ -169,7 +172,7 @@ Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows) and select **"Copilot: R
 
 Most Squad installs come with GitHub MCP pre-configured. Here's what it looks like:
 
-### CLI: `.copilot/mcp-config.json`
+### CLI: `.mcp.json` (project) or `~/.copilot/mcp-config.json` (user)
 
 ```json
 {
@@ -349,6 +352,21 @@ Agents don't need special setup to discover tools. Here's the flow:
    copilot
    ```
 
+### Migrating from `.copilot/mcp-config.json`
+
+Squad ≤ 0.9.x wrote the per-repo MCP config to `.copilot/mcp-config.json`. That path was **not** auto-loaded by Copilot CLI — users had to pass `--additional-mcp-config .copilot/mcp-config.json` on every invocation, and a lot of teams never noticed their MCP servers weren't actually loading. See [github/copilot-cli#3642](https://github.com/github/copilot-cli/issues/3642).
+
+Newer `squad init` writes `.mcp.json` at the repo root — the path Copilot CLI auto-loads per `copilot mcp --help`.
+
+**If your repo already has `.copilot/mcp-config.json`:**
+
+1. Open both files (the old `.copilot/mcp-config.json` and the new `.mcp.json` that `squad init` wrote).
+2. Copy any custom `mcpServers.*` entries from `.copilot/mcp-config.json` into `.mcp.json` — merge them under the existing `mcpServers` key.
+3. Delete `.copilot/mcp-config.json` once you've verified the merged `.mcp.json` works (`copilot mcp` should list the merged servers).
+4. Commit `.mcp.json`. You can stop passing `--additional-mcp-config`.
+
+A `squad upgrade` guided merge will ship in a follow-up release; until then, the migration is manual.
+
 ### Tools Not Appearing in Agent Responses
 
 **Symptom:** Agent says "I don't have access to GitHub tools" even though you configured MCP.
@@ -357,7 +375,9 @@ Agents don't need special setup to discover tools. Here's the flow:
 
 1. **Verify config syntax:**
    ```bash
-   # CLI
+   # Project (auto-loaded by Copilot CLI)
+   cat ./.mcp.json | jq .
+   # User-level (also valid)
    cat ~/.copilot/mcp-config.json | jq .
    # Should be valid JSON; if not, `jq` will error
    ```

docs/src/content/docs/features/notifications.md

@@ -375,7 +375,7 @@ For advanced use cases, you can also:
 
 ## Sample MCP Configs
 
-Below are complete, copy-pasteable `.copilot/mcp-config.json` examples for each notification platform. Pick the one that matches your setup and copy the entire `mcpServers` block into your config file.
+Below are complete, copy-pasteable `.mcp.json` (project, at repo root) examples for each notification platform. Pick the one that matches your setup and copy the entire `mcpServers` block into your config file (use `~/.copilot/mcp-config.json` instead if you want it user-level rather than committed to the repo).
 
 ### Teams Webhook (Simplest)
 

docs/src/content/docs/reference/config.md

@@ -112,7 +112,7 @@ These are created only when you opt in during init.
 
 - **`.squad/templates/`** — SDK templates, overwritten on upgrade
 - **`.github/workflows/*.yml`** — CI/CD workflows (opt-in: `--include-workflows`)
-- **`.copilot/mcp-config.json`** — MCP server config (opt-in: `--include-mcp-config`)
+- **`.mcp.json`** — MCP server config at repo root (opt-in: `--include-mcp-config`); auto-loaded by Copilot CLI
 
 > ⚠️ **Hard rule:** Squad NEVER writes temp files, logs, or memory to your repo root. All team state lives in `.squad/` only. Your project tree stays clean.
 

index.cjs

@@ -1768,34 +1768,10 @@ Reusable patterns and heuristics learned through work. NOT transcripts — each
   console.log(`${DIM}identity/wisdom.md already exists — skipping${RESET}`);
 }
 
-// Create sample MCP config (skip if .copilot/mcp-config.json already exists)
-if (!isUpgrade) {
-  const mcpDir = path.join(dest, '.copilot');
-  const mcpConfigPath = path.join(mcpDir, 'mcp-config.json');
-  if (!fs.existsSync(mcpConfigPath)) {
-    try {
-      fs.mkdirSync(mcpDir, { recursive: true });
-      const mcpSample = {
-        mcpServers: {
-          "EXAMPLE-trello": {
-            command: "npx",
-            args: ["-y", "@trello/mcp-server"],
-            env: {
-              TRELLO_API_KEY: "${TRELLO_API_KEY}",
-              TRELLO_TOKEN: "${TRELLO_TOKEN}"
-            }
-          }
-        }
-      };
-      fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpSample, null, 2) + '\n');
-      console.log(`${GREEN}✓${RESET} .copilot/mcp-config.json (MCP sample — rename EXAMPLE-trello to enable)`);
-    } catch (err) {
-      // Non-fatal — MCP config is optional
-    }
-  } else {
-    console.log(`${DIM}mcp-config.json already exists — skipping${RESET}`);
-  }
-}
+// MCP sample config is now written by the squad-sdk init flow (packages/squad-sdk/src/config/init.ts)
+// to `.mcp.json` at the repo root — the workspace path that Copilot CLI auto-loads
+// (see `copilot mcp --help`). Legacy `.copilot/mcp-config.json` is no longer written
+// here. See github/copilot-cli#3642 and the `mcp-json-migration` changeset.
 
 // Copy default ceremonies config
 const ceremoniesDest = path.join(squadInfo.path, 'ceremonies.md');

packages/squad-cli/src/cli/commands/state-mcp.ts

@@ -201,8 +201,9 @@ export function printStateMcpHelp(): void {
     'Usage: squad state-mcp',
     '',
     'This command is intended to be launched by GitHub Copilot CLI through',
-    '.copilot/mcp-config.json. It exposes squad_decide and state.* tools',
-    'backed by the configured Squad state backend.',
+    '.mcp.json (repo root) — the workspace MCP config path that the CLI',
+    'auto-loads. It exposes squad_decide and state.* tools backed by the',
+    'configured Squad state backend.',
     '',
   ].join('\n'));
 }

packages/squad-cli/src/cli/core/init.ts

@@ -111,7 +111,7 @@ export interface RunInitOptions {
   isGlobal?: boolean;
   /** State backend to configure at init time (local, orphan, two-layer) */
   stateBackend?: string;
-  /** If true, write MCP server config into squad.agent.md frontmatter instead of .copilot/mcp-config.json */
+  /** If true, write MCP server config into squad.agent.md frontmatter instead of .mcp.json (repo root) */
   mcpFrontmatter?: boolean;
 }
 

packages/squad-cli/src/cli/core/upgrade.ts

@@ -6,7 +6,7 @@
 
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { FSStorageProvider } from '@bradygaster/squad-sdk';
+import { FSStorageProvider, migrateMcpConfig } from '@bradygaster/squad-sdk';
 import { success, warn, info, dim, bold } from './output.js';
 import { fatal } from './errors.js';
 import { detectSquadDir } from './detect-squad-dir.js';
@@ -741,6 +741,36 @@ export async function runUpgrade(dest: string, options: UpgradeOptions = {}): Pr
     fatal('No squad found — run init first.');
   }
 
+  // -------------------------------------------------------------------------
+  // Phase 2: fold legacy `.copilot/mcp-config.json` into `.mcp.json` so
+  // Copilot CLI 1.0.58+ actually discovers the user's MCP servers (the
+  // legacy path was never auto-loaded — see github/copilot-cli#3642).
+  // Runs BEFORE template/migration work so downstream steps see the merged
+  // server set. Idempotent — re-runs after success are no-ops.
+  // -------------------------------------------------------------------------
+  try {
+    const migrateResult = migrateMcpConfig(dest);
+    if (migrateResult.status === 'migrated') {
+      success(
+        `📋 Migrated ${migrateResult.migrated} MCP server(s) from ` +
+        `.copilot/mcp-config.json → .mcp.json. ` +
+        `Legacy file preserved; you may delete it once verified.`,
+      );
+      filesUpdated.push('.mcp.json (merged from .copilot/mcp-config.json)');
+    }
+    for (const warningLine of migrateResult.warnings) {
+      warn(warningLine);
+    }
+    if (migrateResult.status === 'malformed-target') {
+      warn(migrateResult.error ?? 'Could not merge .copilot/mcp-config.json — .mcp.json is malformed.');
+    } else if (migrateResult.status === 'malformed-legacy') {
+      warn(migrateResult.error ?? 'Could not parse .copilot/mcp-config.json — skipping MCP merge.');
+    }
+  } catch (err) {
+    // Never block an upgrade on a merge failure — surface and continue.
+    warn(`MCP config merge failed: ${(err as Error).message}`);
+  }
+
   const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
   const oldVersion = readInstalledVersion(agentDest) ?? '0.0.0';
   const squadConfig = readSquadConfig(squadDirInfo.path);

packages/squad-cli/templates/mcp-config.md

@@ -5,10 +5,12 @@ MCP (Model Context Protocol) servers extend Squad with tools for external servic
 ## Config File Locations
 
 Users configure MCP servers at these locations (checked in priority order):
-1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
-2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
-3. **User-level:** `~/.copilot/mcp-config.json` (personal)
-4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+1. **Repository-level (auto-loaded):** `.mcp.json` at the repo root — team-shared, committed; this is the workspace path Copilot CLI auto-loads (see `copilot mcp --help`).
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces).
+3. **User-level:** `~/.copilot/mcp-config.json` (personal, user-wide).
+4. **CLI override:** `--additional-mcp-config <path>` (session-specific).
+
+> **Migration note:** Older Squad versions wrote the per-repo config to `.copilot/mcp-config.json`. That path was not auto-loaded by Copilot CLI and required `--additional-mcp-config`. New `squad init` writes `.mcp.json` instead. If your repo still has a `.copilot/mcp-config.json`, it is preserved as-is — see `docs/features/mcp.md` for a manual merge recipe until `squad upgrade` ships a guided merge.
 
 ## Sample Config — Trello
 

packages/squad-cli/templates/squad.agent.md.template

@@ -449,7 +449,7 @@ When spawning agents, include an `MCP TOOLS AVAILABLE` block in the prompt (see
 Never crash or halt because an MCP tool is missing. MCP tools are enhancements, not dependencies.
 
 1. **CLI fallback** — GitHub MCP missing → use `gh` CLI. Azure MCP missing → use `az` CLI.
-2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.copilot/mcp-config.json`."
+2. **Inform the user** — "Trello integration requires the Trello MCP server. Add it to `.mcp.json` at the repo root (the path Copilot CLI auto-loads)."
 3. **Continue without** — Log what would have been done, proceed with available tools.
 
 ### Eager Execution Philosophy