[joslat]

What

Squad's coordinator guidance, help text and MCP docs now point users at MCP config files their host actually loads, instead of a project-level .copilot/mcp-config.json, which Copilot CLI ignores.

Why

Closes #2330

Copilot CLI reads .mcp.json (cwd up to the repo root), .github/mcp.json and ~/.copilot/mcp-config.json (docs). Squad moved squad_state to .mcp.json for exactly that reason, but the coordinator's MCP guide still called .copilot/mcp-config.json the team-shared location, and its fallback told users to "Add it to .copilot/mcp-config.json". A server added there never loads.

How

Coordinator templates

• mcp-config.md (templates/, .squad-templates/, packages/squad-cli/templates/, packages/squad-sdk/templates/). The location list now names:
  • .mcp.json next to squad_state, plus .github/mcp.json, with a note that Copilot CLI doesn't read the project .copilot/mcp-config.json;
  • .vscode/mcp.json and its servers key;
  • ~/.copilot/mcp-config.json, which Copilot CLI and VS Code both read;
  • --additional-mcp-config, which is how squad loop and squad watch load .mcp.json;
  • the files the --client hosts use (Kiro, Cursor, OpenCode, Codex, and agy mcp add for Antigravity).
• The Trello fallback line in the 4 squad.agent.md templates and in .github/agents/squad.agent.md: "Add it to .mcp.json next to squad_state."

CLI

• The squad state-mcp --help text says the command is launched from the squad_state entry in .mcp.json (or the host's own config for --client hosts).

Docs

• features/mcp.md:
  • The config table names the right files for Copilot CLI and VS Code.
  • The CLI steps say how to share a server through .mcp.json, and the Windows command opens $HOME\.copilot\mcp-config.json.
  • The VS Code steps use .vscode/mcp.json with servers and MCP: List Servers instead of a copilot.mcp.servers setting and a reload command that don't exist. Both are checked against the VS Code MCP docs.
  • "GitHub MCP (Already Included)" loses the "pre-configured" claim; the only thing init writes is an EXAMPLE-github entry in the ignored file.
  • Troubleshooting starts with "is the server in a file your host reads?"
• concepts/portability.md, features/enterprise-platforms.md, features/notifications.md: the same location fix.

Tests

• test/mcp-config-locations.test.ts checks that all 4 guide mirrors name .mcp.json as the repository-level location, and that all 5 coordinator copies use the new fallback line.

Not in this PR (listed in the issue): squad init still writes the sample .copilot/mcp-config.json, reference/config.md calls it opt-in, and features/mcp-frontmatter.md describes the old init behavior. Fixing those changes what init does, so they're better as a separate decision.

Testing

• npx vitest run test/mcp-config-locations.test.ts: 9 passed. With the template changes reverted, all 9 fail.
• The init, upgrade, template-sync, template-routing, MCP root, copilot-invocation, host-feature-matrix and clients tests: 644 passed, 35 expected fail, 6 skipped, the same as on dev.
• npm run lint: clean.
• markdownlint-cli2 over the docs (185 files) and cspell on the changed pages: 0 issues.
• Links into features/mcp.md (#step-by-step-cli-setup, #mcp-configuration-files) still resolve; I didn't rename those headings.

---

⚠️ Quick Check

• If SDK/CLI source files changed: changeset added (.changeset/mcp-config-locations.md, cli + sdk patch)

PR Readiness Checklist

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev (9d7dff8)
• Verified diff contains only intended changes (16 files: 9 templates, 1 CLI source, 4 docs pages, 1 test, 1 changeset)
• PR is not in draft mode
• Commit history is clean

Build & Test

• npm run lint passes
• Relevant tests pass
• No conflicts with the other open PRs (fix(sdk): make governed memory class names case-insensitive #2315, fix(cli): squad memory opens the same governed store as squad_state #2317, fix(sdk): keep memory search working when the host-injected adapter has no client #2319, fix(templates): give Scribe one definition #2322, docs(memory): correct history compaction size and mechanism #2324, docs(plugins): say which spawn paths inject plugin context #2327, fix(clients): let the Claude coordinator see every MCP server in the session #2329)

Docs

• Docs pages updated (4)

---

Breaking Changes

None.

Waivers

None.

[github-actions]

🟠 Impact Analysis — PR #2331

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	16
Files added	2
Files modified	14
Files deleted	0
Modules touched	7

🎯 Risk Factors

• 16 files changed (6-20 → MEDIUM)
• 7 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (1 file)

• .github/agents/squad.agent.md

docs (4 files)

• docs/src/content/docs/concepts/portability.md
• docs/src/content/docs/features/enterprise-platforms.md
• docs/src/content/docs/features/mcp.md
• docs/src/content/docs/features/notifications.md

root (3 files)

• .changeset/mcp-config-locations.md
• templates/mcp-config.md
• templates/squad.agent.md.template

squad-cli (3 files)

• packages/squad-cli/src/cli/commands/state-mcp.ts
• packages/squad-cli/templates/mcp-config.md
• packages/squad-cli/templates/squad.agent.md.template

squad-sdk (2 files)

• packages/squad-sdk/templates/mcp-config.md
• packages/squad-sdk/templates/squad.agent.md.template

templates (2 files)

• .squad-templates/mcp-config.md
• .squad-templates/squad.agent.md

tests (1 file)

• test/mcp-config-locations.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit c6043ef

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	16 check(s) still running

Files Changed (16 files, +129 −66)

File	+/−
.changeset/mcp-config-locations.md	+6 −0
.github/agents/squad.agent.md	+1 −1
.squad-templates/mcp-config.md	+6 −5
.squad-templates/squad.agent.md	+1 −1
docs/src/content/docs/concepts/portability.md	+2 −2
docs/src/content/docs/features/enterprise-platforms.md	+1 −1
docs/src/content/docs/features/mcp.md	+39 −35
docs/src/content/docs/features/notifications.md	+1 −1
packages/squad-cli/src/cli/commands/state-mcp.ts	+4 −2
packages/squad-cli/templates/mcp-config.md	+6 −5
packages/squad-cli/templates/squad.agent.md.template	+1 −1
packages/squad-sdk/templates/mcp-config.md	+6 −5
packages/squad-sdk/templates/squad.agent.md.template	+1 −1
templates/mcp-config.md	+6 −5
templates/squad.agent.md.template	+1 −1
test/mcp-config-locations.test.ts	+47 −0

Total: +129 −66

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[tamirdresher]

Thanks Jose! I verified all the places where our templates and docs still pointed at .copilot/mcp-config.json ( emplates/mcp-config.md, emplates/squad.agent.md.template:487, packages/squad-cli/src/cli/commands/state-mcp.ts:315, and docs/src/content/docs/features/mcp.md), plus the .vscode/mcp.json servers key and the $HOME.copilot\mcp-config.json path on Windows. The merge-tree against dev is clean and I approved the CI runs. We are in a release freeze for 2.0.0-preview.2 and will merge this right after the release ships.

[tamirdresher]

On a broader note, thank you for this entire batch of issues and PRs today. The seams you uncovered across Squad 2.0 on non Copilot hosts, governed memory, and squad_state are the exact integration edges we want surfaced before the next preview, and every single report came with a tight repro and root cause. We would love for you to keep going.

[joslat]

On a broader note, thank you for this entire batch of issues and PRs today. The seams you uncovered across Squad 2.0 on non Copilot hosts, governed memory, and squad_state are the exact integration edges we want surfaced before the next preview, and every single report came with a tight repro and root cause. We would love for you to keep going.

Thanks @tamirdresher! you are the motivation master! I think at the moment those 9-10 issues and PRs are the most critical ones ;) and then it's time to play a bit with integrating what we discussed :) - thanks for the trust!