GHCP CLI Config

Configure GitHub Copilot CLI (the copilot command) for the workflows this catalog assumes — six MCP servers, sane settings.json defaults, the work-iq plugin family for Microsoft staff, sensible autoApprove guardrails, and a fresh-machine bootstrap the agent can run end-to-end.

Provenance. Distilled from the live ~/.copilot/ of an active GBB engineer working across Threadlight, Foundry, and Citadel. All real API keys have been replaced with <your-…-key> placeholders. All real folder names in trustedFolders have been replaced with generic placeholders. The m-*.json managed files are deliberately NOT documented as user-editable — Copilot CLI rewrites them and your edits will be lost.

When to use

Invoke this skill when:

• Setting up Copilot CLI on a fresh machine for the first time
• Adding a new MCP server (add ms learn mcp, add azure mcp, …)
• A teammate asks "what should my mcp-config.json look like?"
• You want to enable sessionSync to roam sessions across machines
• You need to whitelist trustedFolders so the agent stops asking on every cd into a working repo
• You're enabling Microsoft staff plugins (work-iq, m365-agents-toolkit)

When NOT to use

• Authoring a new skill → use skill-creator
• Per-tenant Azure isolation → use azure-tenant-isolation (sets AZURE_CONFIG_DIR per shell — the Azure MCP server below honors it)
• Cursor / Claude Code / Zed config → different runtimes, different files; this skill only covers GHCP CLI

File map (where everything lives)

~/.copilot/
├── settings.json              ← USER-EDITABLE. Top-level prefs (model, sync, trusted folders, plugins).
├── mcp-config.json            ← USER-EDITABLE. MCP server registry.
├── permissions-config.json    ← AUTO-MANAGED. Per-folder "Yes, always" approvals — never edit by hand.
├── m-settings.json            ← MANAGED. Auto-rewritten by the runtime. Do NOT edit.
├── m-mcp-servers.json         ← MANAGED. Auto-rewritten. Do NOT edit.
├── m-preferences.json         ← MANAGED. Do NOT edit.
├── skills/<skill-name>/       ← USER-SCOPE skills (this catalog's recommended install location).
├── installed-plugins/         ← Plugin cache (filled by `copilot plugin install …`).
├── session-state/<session-id>/← Per-session workspace (plan.md, checkpoints, files).
└── session-store.db           ← SQLite cross-session history (queryable).

The two files this skill writes are settings.json and mcp-config.json. Everything else is either auto-managed by the runtime or per-skill / per-session state.

Quick start (5 minutes, no API keys needed)

The minimum viable setup uses the three no-auth MCP servers (mslearn, Azure, Playwright). Drop this into ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "mslearn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp",
      "tools": ["*"],
      "headers": {}
    },
    "Azure": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@azure/mcp@latest", "server", "start"],
      "tools": ["*"]
    },
    "Playwright": {
      "type": "local",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@0.0.42", "--isolated", "--headless"],
      "tools": ["*"]
    }
  }
}

The full version (with context7 / tavily / mem0 and placeholder keys) is in references/mcp-config.full.json.

Restart copilot after editing mcp-config.json. Verify with /mcp inside the session — the three servers should appear.

cmd /c on Windows is intentional for Playwright. npx.cmd isn't always on PATH the way the runtime expects; wrapping in cmd /c makes the launch reliable across PowerShell hosts. On macOS / Linux drop the cmd /c prefix and call npx directly.

Recommended MCP servers (the GBB six)

Per-server snippets

mslearn (no auth)

"mslearn": {
  "type": "http",
  "url": "https://learn.microsoft.com/api/mcp",
  "tools": ["*"],
  "headers": {}
}

When working on Foundry / Azure / M365, invoke mslearn BEFORE falling back to web fetches. The signal-to-noise is higher and the agent gets the canonical doc URL for citation.

Azure (no auth — uses az login token cache)

"Azure": {
  "type": "local",
  "command": "npx",
  "args": ["-y", "@azure/mcp@latest", "server", "start"],
  "tools": ["*"]
}

This server reads the same token cache as az CLI. If you use AZURE_CONFIG_DIR per terminal (per azure-tenant-isolation), the Copilot CLI process must inherit that env var — set it before launching copilot, not inside the session.

Playwright (no auth, headless + isolated)

"Playwright": {
  "type": "local",
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@playwright/mcp@0.0.42", "--isolated", "--headless"],
  "tools": ["*"]
}

--isolated = ephemeral browser profile per session (no cookies kept). --headless = no visible browser window. Drop both flags if you want to watch the agent click through.

context7 (API key required)

"context7": {
  "type": "http",
  "url": "https://mcp.context7.com/mcp",
  "tools": ["*"],
  "headers": { "CONTEXT7_API_KEY": "<your-context7-api-key>" }
}

Get a free key at https://context7.com/. Use it when the agent needs library API surface that isn't well-covered by mslearn (anything non-Microsoft: react-query, playwright-python, pandas, etc.).

tavily (API key required)

"tavily": {
  "type": "http",
  "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-tavily-api-key>",
  "tools": ["*"],
  "headers": {}
}

Free key at https://tavily.com/. Two tools: tavily_search (ranked results) and tavily_extract (full-page extraction with cleanup).

mem0 (API key + Python install required)

"mem0": {
  "type": "local",
  "command": "python",
  "args": ["-m", "mem0_mcp_server.server"],
  "tools": ["*"],
  "env": {
    "MEM0_API_KEY": "<your-mem0-api-key>",
    "MEM0_DEFAULT_USER_ID": "default"
  }
}

Install once: pip install mem0-mcp-server. Free key at https://mem0.ai/. Use sparingly — broad memory across all sessions can leak project context between unrelated work. The built-in m_remember / SQL session-store.db covers most needs.

settings.json baseline

Live at ~/.copilot/settings.json. The keys most worth setting:

{
  "model": "claude-opus-4.7",
  "renderMarkdown": true,
  "showReasoning": false,

  "allowedUrls": [
    "https://raw.githubusercontent.com",
    "https://docs.github.com"
  ],

  "sessionSync": [
    { "origin": "*", "level": "user" }
  ],

  "trustedFolders": [
    "<absolute-path-to-your-repos-root>",
    "<absolute-path-to-another-trusted-folder>"
  ],

  "extraKnownMarketplaces": {
    "copilot-plugins": {
      "source": { "source": "github", "repo": "github/copilot-plugins" }
    }
  },

  "telemetryEnabled": true,
  "sessionRetentionDays": 90,
  "preventSleepEnabled": true
}

Full example: references/settings.example.json.

Key-by-key

Microsoft staff: enable the work-iq marketplace

Add to extraKnownMarketplaces and install three plugins:

"extraKnownMarketplaces": {
  "copilot-plugins": {
    "source": { "source": "github", "repo": "github/copilot-plugins" }
  },
  "work-iq": {
    "source": { "source": "github", "repo": "microsoft/work-iq" }
  }
}

copilot plugin install workiq@work-iq
copilot plugin install microsoft-365-agents-toolkit@work-iq
copilot plugin install workiq-productivity@work-iq

Then in settings.json:

"enabledPlugins": {
  "workiq@work-iq": true,
  "microsoft-365-agents-toolkit@work-iq": true,
  "workiq-productivity@work-iq": true
}

The work-iq family includes the M365 Agents Toolkit plugin.

Permissions & autoApprove

Copilot CLI tracks two layers of approval state:

1. m-settings.json → permissions (managed, but configurable via the UI): autoApproveReadOnly (safe to enable) and a per-server autoApprove map (be selective).
2. permissions-config.json (per-folder, auto-managed): every time you answer "Yes, always for this folder" to a tool prompt, the approval lands here. Don't edit this file — it's append-only state.

Safe defaults

Inspecting your current state

# Windows
Get-Content $env:USERPROFILE\.copilot\m-settings.json |
  python -c "import json,sys; d=json.load(sys.stdin); p=d.get('permissions',{}); print('autoApproveReadOnly:', p.get('autoApproveReadOnly')); print('servers:'); [print(' ', s, v) for s,v in p.get('servers',{}).items()]"

# macOS / Linux
jq '.permissions | {autoApproveReadOnly, servers}' ~/.copilot/m-settings.json

Sync strategy

Session sync (cross-machine session history)

sessionSync: [{"origin": "*", "level": "user"}] in settings.json mirrors session state to your GitHub account. On a second machine where you're logged in as the same user, sessions reappear in /sessions.

• level: "user" = sync everything you do (recommended for laptops + a workstation owned by the same person).
• level: "repo" = sync only sessions in repos that explicitly opt in via .copilot/config.json in the repo root. Tighter blast radius.
• origin: "*" = match any GitHub host (use a specific origin if your org runs GHEC + GHES side by side).

User-scope vs project-scope skills

Skills install to one of two locations:

When you edit a skill in this catalog (awesome-gbb) and want the runtime to pick it up immediately, mirror the change to user scope:

# Windows — keep in lock-step with the repo source of truth
robocopy `
  C:\path\to\awesome-gbb\skills\<skill> `
  $env:USERPROFILE\.copilot\skills\<skill> `
  /MIR /XD .git /NFL /NDL /NJH /NJS

# Verify SHA256 parity
Get-FileHash `
  C:\path\to\awesome-gbb\skills\<skill>\SKILL.md, `
  $env:USERPROFILE\.copilot\skills\<skill>\SKILL.md `
  -Algorithm SHA256

This is the same pattern documented in awesome-gbb/AGENTS.md § 6. Source-of-truth lives in the repo; user scope is a runtime mirror.

Bootstrap procedure (agent-executable)

When invoked with "set up my fresh machine" or equivalent, follow this procedure. Each step is an explicit checkpoint — confirm with the user before moving to the next.

Step 1 — Detect existing state

"=== Copilot CLI version ==="; copilot --version
"=== ~/.copilot/ contents ==="
Get-ChildItem $env:USERPROFILE\.copilot -Force | Select-Object Mode,Name | Format-Table -AutoSize
"=== existing mcp-config.json (if any) ==="
$mcp = "$env:USERPROFILE\.copilot\mcp-config.json"
if (Test-Path $mcp) { Get-Content $mcp -Raw } else { "(none)" }
"=== existing settings.json (if any) ==="
$s = "$env:USERPROFILE\.copilot\settings.json"
if (Test-Path $s) { Get-Content $s -Raw } else { "(none)" }

If copilot --version fails, stop and direct the user to install GHCP CLI first (gh extension install github/gh-copilot then gh copilot install per current install docs — link the user to https://docs.github.com/copilot/github-copilot-in-the-cli).

Step 2 — Back up current config

$ts = Get-Date -Format "yyyyMMdd-HHmmss"
$bak = "$env:USERPROFILE\.copilot\backup-$ts"
New-Item -ItemType Directory -Path $bak -Force | Out-Null
foreach ($f in 'settings.json','mcp-config.json') {
  $src = "$env:USERPROFILE\.copilot\$f"
  if (Test-Path $src) { Copy-Item $src $bak\ -Force }
}
"Backed up to: $bak"

Step 3 — Choose MCP server tier

Ask the user: "no-key trio (mslearn + Azure + Playwright) or full six (adds context7, tavily, mem0 — needs API keys)?"

Present references/mcp-config.example.json for the trio, references/mcp-config.full.json for the six. Merge into existing mcp-config.json (don't overwrite servers the user already has).

Step 4 — Apply settings.json baseline

Read references/settings.example.json. Merge into existing settings.json keeping the user's existing values where they exist. Specifically:

• trustedFolders → ask the user which folders to trust; do NOT carry over the example placeholder strings.
• model → ask only if the user doesn't already have one set.
• extraKnownMarketplaces.work-iq → ask the user "Are you Microsoft staff?" before adding.

Step 5 — Install plugins (Microsoft staff only)

If user confirmed Microsoft staff in Step 4:

copilot plugin install workiq@work-iq
copilot plugin install microsoft-365-agents-toolkit@work-iq
copilot plugin install workiq-productivity@work-iq

The work-iq family includes the M365 Agents Toolkit plugin — install via copilot plugin install microsoft-365-agents-toolkit@work-iq.

Step 6 — Verify

"=== settings.json after merge ==="; Get-Content $env:USERPROFILE\.copilot\settings.json
"=== mcp-config.json after merge ==="; Get-Content $env:USERPROFILE\.copilot\mcp-config.json
"=== plugins installed ==="; copilot plugin list 2>$null
"=== diff vs backup ==="; Compare-Object `
  (Get-Content "$bak\settings.json" -ErrorAction SilentlyContinue) `
  (Get-Content "$env:USERPROFILE\.copilot\settings.json")

Restart any running copilot session so the new MCP servers load. Inside the new session run /mcp and confirm all expected servers appear (status: ✅ connected).

Step 7 — Recommended skills

Suggest the user install (or sync to user scope) the GBB-recommended skill set per the README:

gh skill install aiappsgbb/awesome-gbb threadlight-design --scope user
gh skill install aiappsgbb/awesome-gbb threadlight-deploy --scope user
gh skill install aiappsgbb/awesome-gbb foundry-hosted-agents --scope user
gh skill install aiappsgbb/awesome-gbb foundry-observability --scope user
gh skill install aiappsgbb/awesome-gbb azure-tenant-isolation --scope user
gh skill install aiappsgbb/awesome-gbb gbb-humanizer --scope user

Troubleshooting

See Also

References

• references/mcp-config.example.json — minimal no-key trio
• references/mcp-config.full.json — full six with placeholder keys
• references/settings.example.json — baseline settings.json
• GitHub Copilot CLI docs: https://docs.github.com/copilot/github-copilot-in-the-cli
• Microsoft Learn MCP API: https://learn.microsoft.com/api/mcp
• Azure MCP server: https://github.com/Azure/azure-mcp
• Playwright MCP: https://github.com/microsoft/playwright-mcp
• Context7: https://context7.com/
• Tavily: https://tavily.com/
• mem0: https://mem0.ai/

GBB changelog