[FEATURE] Support workspace-level (.mcp.json) and global (-g) MCP configurations for Copilot CLI

[Skolim007]

[FEATURE] Support workspace-level (.mcp.json) and global (-g) MCP configurations for Copilot CLI

Is your feature request related to a problem? Please describe.

Currently, managing MCP servers for the GitHub Copilot CLI is limited because APM's copilot integration target is hard-coded to global scope.

Specifically:

• Running apm integration install copilot always writes the configuration globally to ~/.copilot/mcp-config.json, even when run without -g / --global inside an APM project workspace.
• The APM CLI's Copilot integration does not support project-scoped installations.

Since the GitHub Copilot CLI itself supports project-scoped MCP configurations loaded from .mcp.json or .github/mcp.json at the workspace root, forcing all installations to be global causes environment pollution. This leads to configuration bloat, potential tool argument conflicts between different workspaces, and prevents workspace-specific tools from being checked into version control.

The official Copilot CLI documentation is not fully clear here but as on the main MCP config section it does nto vocer taht option (https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/overview#add-an-mcp-server), though it is officially documented as supproted behaviour here (https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-loading-priority)

Warning message from Copilot CLI that currently this config is not supported.

Working (manually created) project-level .mcp.json config

Describe the solution you'd like

Extend APM's Copilot integration to support both project-local and user-global installation scopes:

1. Install-Write Path (CopilotClientAdapter):
   • By default (project scope), write the configuration locally to <project_root>/.mcp.json.
   • Only write to the user-global ~/.copilot/mcp-config.json when the --global / -g flag is explicitly provided.
2. Runtime-Read Path (CopilotRuntime):
   • Discover and read MCP configurations following the Copilot CLI's official loading priority:
     1. Current working directory .mcp.json
     2. Current working directory .github/mcp.json
     3. User-global fallback ~/.copilot/mcp-config.json
   • Ensure the parser supports the workspace-scoped "mcpServers" root key (used in .mcp.json) in addition to the global "servers" key.

Describe alternatives you've considered

• Manually maintaining local configuration files: Copying and pasting MCP configurations manually to .mcp.json when working in a specific project. This is error-prone and bypasses APM's dependency resolution, updating, and installation workflows.
• Injecting all project configurations into global config: Keeping the current global-only behavior. This is undesirable because it exposes all workspace tools to Copilot in every directory, increasing startup overhead and causing command/context pollution.

Additional context

• Official Reference: GitHub Copilot CLI's MCP server loading priority documentation.
• mcp.json migration: Official docs how to migrate form VS Code format to .mcp.json https://gh.io/copilotcli-mcpmigrate
• Parity: Other client adapters in APM (like Cursor and Windsurf) already support project-local scoping. Implementing this will achieve feature parity for the Copilot integration.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
theme/security
area/mcp-config
area/mcp-trust
type/feature
status/accepted

Milestone

null -- no open patch or minor milestone confirmed in this sweep.

Suggested next action

Implement project-local scope support in CopilotClientAdapter (default write to .mcp.json) and add the official Copilot CLI read-priority chain to CopilotRuntime, using the existing Cursor/Windsurf adapters as implementation reference.

Suggested issue comment

Thanks for the detailed write-up, the official docs references, and
the screenshots -- this is a high-quality feature request.

Your analysis is correct. APM's Copilot integration is currently
hard-coded to global scope (`~/.copilot/mcp-config.json`), while the
official Copilot CLI supports project-local configs (`.mcp.json`,
`.github/mcp.json`). Our Cursor and Windsurf adapters already support
project-local scoping, so this is a parity gap.

The feature is accepted with the following scope:

1. **Write path (`CopilotClientAdapter`)**: Default to writing
   `.mcp.json` at the project root when run without `-g`/`--global`.
   Write to `~/.copilot/mcp-config.json` only when `-g`/`--global`
   is explicitly provided. This matches the existing APM install-
   scope convention.

2. **Read path (`CopilotRuntime`)**: Implement the official loading
   priority (`.mcp.json` -> `.github/mcp.json` -> `~/.copilot/mcp-
   config.json`). Handle the `mcpServers` root key (workspace format)
   alongside the existing `servers` key (global format).

One security constraint the implementing PR must address: project-
local `.mcp.json` files discovered on disk should only be loaded when
they were placed there by APM (i.e., belong to an APM-managed package
graph), not from arbitrary cloned repositories. Please document this
trust boundary in the PR.

The Cursor and Windsurf adapter implementations are the closest
reference for the code path. If you would like to take a first crack
at a PR, that would be very welcome.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

High-value DX request. apm integration install copilot writing global config when run inside a project violates the install-local-by-default convention established by npm, pip, and APM's own Cursor/Windsurf adapters. The proposed read-priority chain mirrors the official Copilot CLI priority, eliminating cognitive overhead. The screenshot evidence (warning from Copilot CLI about unsupported global config) confirms real user impact. The -g/--global flag convention is already established in APM. This feature parity will meaningfully reduce friction for multi-workspace users who currently must maintain .mcp.json manually or accept config pollution across all directories.

Supply Chain Security Expert -- Risk-Surface Reviewer

Project-local .mcp.json files define which MCP servers load into the Copilot CLI. A poisoned .mcp.json in a cloned repository could load malicious MCP servers if APM's CopilotRuntime blindly reads any .mcp.json in the working directory. The implementing PR must address this trust boundary: only read/write .mcp.json files that APM placed there (i.e., inside APM-managed package graphs), not from arbitrary directories. area/mcp-trust and area/mcp-config are both relevant. theme/security applies alongside theme/portability as a secondary mega-theme. The mcpServers vs servers key difference must be handled without silent data loss or schema confusion.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author Skolim007 has NONE association -- external contributor. The issue is exceptionally well-written: references official Copilot CLI docs, includes screenshots of the warning, notes parity with existing adapters, and lists alternatives considered. This is a technically sophisticated contributor. A reply that: (1) explicitly validates their analysis, (2) confirms the parity gap with Cursor/Windsurf, (3) scopes the feature clearly, and (4) invites a draft PR will maximize the chance of converting this reporter into a contributor. The suggested comment does all four.

Python Architect -- Architecture Reviewer

Two contained code paths: (1) CopilotClientAdapter write path -- flip the default from global to project-local path, add --global/-g flag handling; (2) CopilotRuntime read path -- implement the three-file priority chain and unify the mcpServers/servers key parser. The Cursor and Windsurf adapter implementations provide a concrete implementation pattern. Key design question settled by the existing APM convention: scope default is project-local when --global is absent. Migration: existing global configs continue to work (Copilot CLI still reads ~/.copilot/mcp-config.json as fallback). No breaking change. The MCP trust boundary (noted by the Security Expert) is the one design constraint the implementing PR must document explicitly; it does not block acceptance.

Doc Writer -- Documentation Reviewer

New project-local scope behavior for the Copilot integration is user-facing and requires documentation. The implementing PR should update docs/src/content/docs/reference/cli-commands.md (new --global/-g behavior for apm integration install copilot) and any Copilot integration guide pages. The trust boundary for project-local configs should also be documented in docs/src/content/docs/enterprise/security.md or the MCP config guide. The area/docs-site label was omitted from the final set to stay within the 6-label limit; the implementing PR should be flagged for docs updates during review.

APM CEO -- Triage Arbiter

The feature request is well-grounded (official Copilot CLI docs, parity with Cursor/Windsurf), submitted by a technically sophisticated external contributor, and addresses real friction for multi-workspace users. The Security Expert's MCP trust concern is real but addressable in the implementing PR's security review -- it does not require a separate design gate. Decision: accept. Primary theme: theme/portability (feature parity with other adapters); secondary: theme/security (MCP config trust surface). The suggested reply invites the author to open a draft PR, which is the optimal conversion path for this caliber of contributor.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config", "area/mcp-trust"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Implement project-local scope in CopilotClientAdapter and add the official Copilot CLI read-priority chain to CopilotRuntime, using Cursor/Windsurf adapters as reference.",
  "comment_markdown": "Thanks for the detailed write-up, the official docs references, and the screenshots -- this is a high-quality feature request.\n\nYour analysis is correct. APM's Copilot integration is currently hard-coded to global scope (`~/.copilot/mcp-config.json`), while the official Copilot CLI supports project-local configs (`.mcp.json`, `.github/mcp.json`). Our Cursor and Windsurf adapters already support project-local scoping, so this is a parity gap.\n\nThe feature is accepted with the following scope:\n\n1. **Write path (`CopilotClientAdapter`)**: Default to writing `.mcp.json` at the project root when run without `-g`/`--global`. Write to `~/.copilot/mcp-config.json` only when `-g`/`--global` is explicitly provided.\n\n2. **Read path (`CopilotRuntime`)**: Implement the official loading priority (`.mcp.json` -> `.github/mcp.json` -> `~/.copilot/mcp-config.json`). Handle the `mcpServers` root key (workspace format) alongside the existing `servers` key.\n\nOne security constraint the implementing PR must address: project-local `.mcp.json` files should only be loaded when placed there by APM, not from arbitrary cloned repositories. Please document this trust boundary in the PR.\n\nThe Cursor and Windsurf adapter implementations are the closest reference. If you would like to take a first crack at a PR, that would be very welcome."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 151.1 AIC · ⌖ 20 AIC · ⊞ 9.2K · ◷