feat(mcp): per-dependency `targets` scoping for `dependencies.mcp` entries

[lkshrk]

Problem

Global MCP installs have exactly one reconciliation domain: every apm install -g --only mcp reconciles the whole MCP surface across every target it has previously touched. --target is per-invocation only, so:

• Sequential per-target invocations delete each other's servers (pass 1 --target claude with server A, pass 2 --target codex with server B → A is removed as stale).
• Per-server-per-agent scoping is inexpressible at global scope. A fleet where server X should reach only Claude Code and server Y only Codex cannot be modeled — a union-target invocation deploys every server (including auth headers) to every target.

Verified on apm-cli 0.28.0.

Current behavior

The documented per-dependency targets field works for package (apm:) dependencies, but on dependencies.mcp entries the key is not part of the model — it is swept into the harness-specific extra passthrough (with an unknown-key warning) and flattened verbatim into the deployed config (e.g. it appears as a bogus targets property inside the ~/.claude.json server object), with no scoping effect.

Request

Honor targets: on dependencies.mcp entries with the same semantics as package dependencies: effective reach = install targets ∩ per-dependency targets, omitted = all install targets, and reconciliation/stale-pruning computed per target from the intersection rather than the whole surface.

Related

• feat(mcp): support env-backed HTTP headers for Codex remotes #1761 (env-backed HTTP headers for Codex remotes) — same motivation: per-target differences in what should reach each harness.
• [BUG] apm install -g --mcp is rejected outright: "MCP servers are project-scoped" #2548 — the imperative -g --mcp path; the declarative manifest path this request builds on is the working one.

Context: building fleet tooling that generates ~/.apm/apm.yml per host from a shared config; per-agent MCP scoping is currently the one thing forcing servers to stay outside APM.

[github-actions]

Triage Panel Verdict -- #2606

Title: feat(mcp): per-dependency targets scoping for dependencies.mcp entries
Author: @lkshrk
Type: Feature request (well-specified, bounded scope)

---

Panel synthesis

DevX UX Expert

The request is for targets: on dependencies.mcp entries to mirror the behavior already supported on apm: package dependencies. This is a critical consistency gap: users who adopt APM's declarative manifest model for MCP legitimately expect the same scoping semantics across all dependency kinds. The current behavior -- silently discarding targets: and deploying every MCP server to every harness -- is a confusing and invisible trap. The fix is bounded: honor targets: in the MCP dependency model and thread it through reconciliation/stale-pruning, mirroring the existing apm: package path. High DevX value; the author's real-world fleet context makes the motivation concrete.

Supply Chain Security Expert

Per-target MCP scoping has direct security implications. MCP servers frequently carry auth headers (Bearer tokens, API keys scoped to a specific harness). Today those credentials reach every configured target uniformly; there is no way to constrain a credential-bearing server to only the harness that needs it. Honoring targets: on dependencies.mcp closes this credential-broadcast exposure. The author's reference to #1761 (env-backed HTTP headers for Codex remotes) underscores the security motivation. This issue warrants area/mcp-trust and theme/security in addition to area/mcp-config.

APM CEO Arbiter

Clean, well-scoped feature request from a fleet-tooling user who demonstrably understands the APM model. The implementation path is clear: extend DependencyMCP to propagate targets through reconciliation, mirroring the existing package-dependency code path. Related issues #1761 and #2548 confirm an emerging multi-harness/fleet pattern. This is the kind of bounded, high-clarity feature that belongs in the next minor release. Decision: ACCEPT.

---

Decision

Dimension	Value
Type	type/feature
Theme	theme/security, theme/governance
Area	area/mcp-config, area/mcp-trust
Priority	priority/high
Milestone	0.29.0
Status	status/triaged

Suggested next action: Design the DependencyMCP.targets field propagation through the reconciliation engine, ensuring effective-reach = install targets ∩ per-dependency targets, with stale-pruning computed per-target from the intersection. Cross-reference #1761 and #2548 for related prior art.

---

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 · 62.2 AIC · ⌖ 8.46 AIC · ⊞ 9.2K · ◷