fix(templates): point users at MCP config files their host reads (#2331)

The coordinator's MCP guide listed a project-level .copilot/mcp-config.json
as the team-shared location, and the coordinator told users to "Add it to
.copilot/mcp-config.json". Copilot CLI doesn't read that file; it reads
.mcp.json, .github/mcp.json and ~/.copilot/mcp-config.json.

- mcp-config.md (4 mirrors): name .mcp.json next to squad_state,
  .github/mcp.json, .vscode/mcp.json (servers key),
  ~/.copilot/mcp-config.json, --additional-mcp-config and the --client hosts
- squad.agent.md templates + .github/agents/squad.agent.md: fallback line
- squad state-mcp --help: launched from the .mcp.json entry
- docs: mcp.md (CLI and VS Code locations, Windows path, troubleshooting),
  portability.md, enterprise-platforms.md, notifications.md
- test pinning the guide and the fallback line

Closes #2330

Co-authored-by: Tamir Dresher <tamir.dresher@gmail.com>

Author: joslat

.changeset/mcp-config-locations.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Point users at MCP config files their host actually reads. The coordinator's MCP guide (`.squad/templates/mcp-config.md`) listed a project-level `.copilot/mcp-config.json` as the team-shared location and the coordinator told users to "Add it to `.copilot/mcp-config.json`", but Copilot CLI doesn't read that file. The guide now names the repo-root `.mcp.json` (next to `squad_state`), `.github/mcp.json`, `.vscode/mcp.json` (with its `servers` key), `~/.copilot/mcp-config.json`, and the files used by `--client` hosts. The `squad state-mcp --help` text and the MCP docs pages are corrected the same way.

.github/agents/squad.agent.md

@@ -484,7 +484,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` next to `squad_state`." (Other hosts: see `.squad/templates/mcp-config.md`.)
 3. **Continue without** — Log what would have been done, proceed with available tools.
 
 ### Accountable Ownership

.squad-templates/mcp-config.md

@@ -4,11 +4,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)
+Squad registers its own `squad_state` server in the repo-root `.mcp.json`. Users add other servers next to it, in the file their host reads:
+1. **Repository-level:** `.mcp.json` at the repo root (team-shared, committed). Copilot CLI and Claude Code read it; Copilot CLI also reads `.github/mcp.json`. Copilot CLI loads project-level servers once the folder is trusted, and does not read a project-level `.copilot/mcp-config.json`.
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces; the top-level key is `servers`, not `mcpServers`)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal; Copilot CLI loads it in every project, and VS Code reads it as its Copilot global config)
+4. **CLI override:** `--additional-mcp-config @<file>` flag (session-specific; `squad loop` and `squad watch` execute mode pass `@.mcp.json` this way)
+5. **Other hosts** (`squad init --client ...`): Kiro `.kiro/settings/mcp.json`, Cursor `.cursor/mcp.json`, OpenCode `opencode.json` (`mcp`), Codex `.codex/config.toml` (`[mcp_servers.<name>]`). For Antigravity use `agy mcp add`, because Squad regenerates `.agents/agents/squad.md`.
 
 ## Sample Config — Trello
 

.squad-templates/squad.agent.md

@@ -484,7 +484,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` next to `squad_state`." (Other hosts: see `.squad/templates/mcp-config.md`.)
 3. **Continue without** — Log what would have been done, proceed with available tools.
 
 ### Accountable Ownership

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

@@ -170,8 +170,8 @@ MCP (Model Context Protocol) servers extend Squad with external services. Agents
 
 | Platform | Config File |
 |----------|------------|
-| **Copilot CLI** | `.copilot/mcp-config.json` |
-| **VS Code** | `.vscode/settings.json` (under `copilot.mcp.servers`) |
+| **Copilot CLI** | `.mcp.json` at the repo root (shared) or `~/.copilot/mcp-config.json` (personal). Not a project-level `.copilot/mcp-config.json`. |
+| **VS Code** | `.vscode/mcp.json` (top-level key `servers`) or `~/.copilot/mcp-config.json` |
 
 ### Example: GitHub MCP
 ```json

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

@@ -106,7 +106,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, next to `squad_state` (or to `~/.copilot/mcp-config.json` to keep it personal):
 
 ```json
 {

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

@@ -22,19 +22,23 @@ 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:
+Where you add a server depends on your host:
 
 | 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 |
+| **Copilot CLI** | `.mcp.json` at the repo root (shared with your team; Squad's `squad_state` server already lives there) or `~/.copilot/mcp-config.json` (personal, every project) | Text editor | Add to shell initialization (`~/.bashrc`, `~/.zshrc`, etc.) |
+| **VS Code** | `.vscode/mcp.json` (top-level key `servers`) or `~/.copilot/mcp-config.json` | Text editor, or **MCP: Add Server** from the Command Palette | Built-in; start or restart from **MCP: List Servers** |
 
-This guide covers both. Pick the one that matches your workflow.
+Copilot CLI doesn't read a `.copilot/mcp-config.json` inside the project (`squad init` writes a sample one there), so a server added to it never loads. Hosts added with `squad init --client` have their own MCP config (Claude Code shares `.mcp.json`), and Squad adds `squad_state` to it for you.
+
+This guide covers Copilot CLI and VS Code. Pick the one that matches your workflow.
 
 ---
 
 ## Step-by-Step: CLI Setup
 
+These steps use your personal config, `~/.copilot/mcp-config.json`. To share a server with your team, add the same `mcpServers` entry to `.mcp.json` at the repo root instead, next to `squad_state`, and commit it. Copilot CLI loads project servers once you trust the folder.
+
 ### Step 1: Create the `.copilot` directory and config file
 
 Open your terminal:
@@ -53,7 +57,7 @@ Open `~/.copilot/mcp-config.json` in your editor:
 nano ~/.copilot/mcp-config.json
 
 # Windows (PowerShell)
-notepad $PROFILE\..\mcp-config.json
+notepad $HOME\.copilot\mcp-config.json
 ```
 
 Paste this base structure:
@@ -115,38 +119,34 @@ If configured correctly, you'll see your GitHub server and its available tools (
 
 ## Step-by-Step: VS Code Setup
 
-### Step 1: Open VS Code Settings
-
-- **macOS:** Code → Preferences → Settings
-- **Windows:** File → Preferences → Settings
-
-Or use the keyboard shortcut: `Cmd+,` (macOS) or `Ctrl+,` (Windows).
+### Step 1: Open the workspace MCP config
 
-### Step 2: Search for "MCP"
+Create `.vscode/mcp.json` in your project, or run **MCP: Add Server** from the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows) and follow the prompts.
 
-In the settings search box, type `MCP` to find Copilot extension settings.
+### Step 2: Add an MCP server
 
-### Step 3: Add an MCP server
-
-Look for the **"Copilot MCP Servers"** section (or similar — naming varies by Copilot version).
-
-Click **"Edit in settings.json"** to see the raw configuration:
+VS Code uses a top-level `servers` key, not `mcpServers`:
 
 ```json
-"copilot.mcp.servers": {
-  "github": {
-    "command": "node",
-    "args": ["/absolute/path/to/github-mcp.js"],
-    "env": {
-      "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+{
+  "servers": {
+    "github": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/github-mcp.js"],
+      "env": {
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+      }
     }
   }
 }
 ```
 
 The `${env:GITHUB_TOKEN}` syntax reads from your shell environment. Replace `/absolute/path/to/github-mcp.js` with the actual path to your MCP server script.
 
-### Step 4: Add environment variables
+To keep a server personal instead, VS Code also reads `~/.copilot/mcp-config.json`, the same file Copilot CLI uses (with `mcpServers`).
+
+### Step 3: Add environment variables
 
 Open your VS Code integrated terminal (`` Ctrl+` `` or `` Cmd+` ``):
 
@@ -156,17 +156,17 @@ export GITHUB_TOKEN=$(gh auth token)
 
 This sets the token for the current terminal session. To make it permanent, add it to your shell profile (see CLI Step 3 above).
 
-### Step 5: Reload VS Code
+### Step 4: Start the server
 
-Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows) and select **"Copilot: Reload Copilot Servers"**.
+Run **MCP: List Servers** from the Command Palette, select the server, and choose **Start Server** (or **Restart Server** after you change its config). VS Code can also start servers on its own when you send a chat message.
 
 ---
 
-## Example: GitHub MCP (Already Included)
+## Example: GitHub MCP
 
-Most Squad installs come with GitHub MCP pre-configured. Here's what it looks like:
+Here's what a GitHub MCP entry looks like:
 
-### CLI: `.copilot/mcp-config.json`
+### Copilot CLI: `.mcp.json` or `~/.copilot/mcp-config.json`
 
 ```json
 {
@@ -184,12 +184,13 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li
 
 Replace `/absolute/path/to/github-mcp.js` with the actual path to your GitHub MCP server script.
 
-### VS Code: `.vscode/settings.json`
+### VS Code: `.vscode/mcp.json`
 
 ```json
 {
-  "copilot.mcp.servers": {
+  "servers": {
     "github": {
+      "type": "stdio",
       "command": "node",
       "args": ["/absolute/path/to/github-mcp.js"],
       "env": {
@@ -352,20 +353,23 @@ Agents don't need special setup to discover tools. Here's the flow:
 
 **Fix:**
 
-1. **Verify config syntax:**
+1. **Verify the server is in a file your host reads:** for Copilot CLI that's `.mcp.json` at the repo root, `.github/mcp.json`, or `~/.copilot/mcp-config.json`. A server in the project's `.copilot/mcp-config.json` is never loaded; move it to `.mcp.json`.
+
+2. **Verify config syntax:**
    ```bash
    # CLI
+   cat .mcp.json | jq .
    cat ~/.copilot/mcp-config.json | jq .
    # Should be valid JSON; if not, `jq` will error
    ```
 
-2. **Restart Copilot to reload config:**
+3. **Restart Copilot to reload config:**
    ```bash
    copilot quit
    copilot
    ```
 
-3. **Test the MCP server directly:**
+4. **Test the MCP server directly:**
    ```bash
    node /absolute/path/to/mcp-server.js
    ```

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

@@ -372,7 +372,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 config examples for each notification platform. Pick the one that matches your setup and copy the entire `mcpServers` block into `.mcp.json` at the repo root (next to `squad_state`) or into `~/.copilot/mcp-config.json`. For VS Code's `.vscode/mcp.json`, put the entries under `servers` instead.
 
 ### Teams Webhook (Simplest)
 

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

@@ -312,8 +312,10 @@ export function printStateMcpHelp(): void {
     '',
     'Usage: squad state-mcp [--experimental-backend]',
     '',
-    'This command is intended to be launched by GitHub Copilot CLI through',
-    '.copilot/mcp-config.json. It exposes squad_decide, squad_state_* and',
+    'This command is intended to be launched by your MCP host from the',
+    'squad_state entry Squad writes to the repo-root .mcp.json (--client',
+    'hosts get it in their own MCP config file). It exposes squad_decide,',
+    'squad_state_* and',
     'squad_state_upstreams (declared upstream inheritance, read from local',
     'snapshots only) backed by the configured Squad state backend. Pass',
     '--experimental-backend',

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

@@ -4,11 +4,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)
+Squad registers its own `squad_state` server in the repo-root `.mcp.json`. Users add other servers next to it, in the file their host reads:
+1. **Repository-level:** `.mcp.json` at the repo root (team-shared, committed). Copilot CLI and Claude Code read it; Copilot CLI also reads `.github/mcp.json`. Copilot CLI loads project-level servers once the folder is trusted, and does not read a project-level `.copilot/mcp-config.json`.
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces; the top-level key is `servers`, not `mcpServers`)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal; Copilot CLI loads it in every project, and VS Code reads it as its Copilot global config)
+4. **CLI override:** `--additional-mcp-config @<file>` flag (session-specific; `squad loop` and `squad watch` execute mode pass `@.mcp.json` this way)
+5. **Other hosts** (`squad init --client ...`): Kiro `.kiro/settings/mcp.json`, Cursor `.cursor/mcp.json`, OpenCode `opencode.json` (`mcp`), Codex `.codex/config.toml` (`[mcp_servers.<name>]`). For Antigravity use `agy mcp add`, because Squad regenerates `.agents/agents/squad.md`.
 
 ## Sample Config — Trello