[FEATURE] Private MCP servers sourced from GitHub repos + consumer token-env trust policy

[danielmeppiel]

Summary

Split out from #20 as a focused, design-needing residual. Two related security/trust items that did NOT ship with the v0.8.0 extended-MCP work:

1. Private MCP servers sourced from GitHub repos ("repo-as-registry")

In the #20 thread, both the maintainer and @Vivalio aligned on a middle ground between "public GitHub MCP Registry" and "stand up a full private MCP registry (e.g. Azure API Center)": source private MCP server definitions from a GitHub repo, the same way APM packages are sourced (honoring GITHUB_HOST / GHE).

At HEAD the model supports registry: <custom-url> (wired by PR #1443) and registry: false (self-defined, shipped inside a package). Neither is the requested first-class "pull a private MCP server definition from a GitHub repo" flow.

2. Consumer-side token-env allow-list policy

Triage design question (Apr 2026): a package declaring env/headers that route a credential (e.g. GITHUB_TOKEN) to a third-party MCP endpoint is a credential-exfiltration surface. Today this is partially gated by --trust-transitive-mcp (transitive servers), but there is no per-token consumer allow-list schema letting a consumer restrict which env vars/secrets a package's MCP servers may receive.

Why grouped

Both are theme/security / area/mcp-trust design items that share the same trust-boundary model (where does a server definition come from, and which credentials may flow to it). Settling them together avoids two overlapping designs.

Suggested design deliverable

A short design doc settling: (a) GitHub-repo MCP sourcing resolution + host/auth reuse, and (b) the consumer token-env allow-list policy hook (likely in apm-policy.yml).

Context

Parent: #20. The extended-config schema, transports, headers, tool filtering, custom registry URL, multi-runtime generation, transitive trust, and the optional-input over-prompt bug (PR #1734) have all shipped. These two trust items are the remaining design-gated residuals.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/security
theme/governance
area/mcp-config
area/mcp-trust
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a design doc (link back here) settling: (a) the yaml key and lockfile contract for GitHub-repo MCP server sourcing, (b) the apm-policy.yml schema for the consumer token-env allow-list, and (c) the trust evaluation order between a package's declared env/headers and consumer-defined credential restrictions.

Suggested issue comment

The two items are correctly grouped: both share the same trust-boundary model and settling them together avoids overlapping designs that conflict at the policy layer.

Design spec must settle:

1. GitHub-repo MCP sourcing: What yaml key in apm.yml declares a GitHub-repo MCP source (e.g. registry: github:owner/repo@ref)? How does APM resolve and lock this to a commit SHA in apm.lock.yaml? Which auth path (AuthResolver + GITHUB_HOST) applies? The lockfile contract for pinned MCP server definitions needs to be explicit before code lands -- without commit-SHA pinning, a compromised source repo becomes an arbitrary substitution vector.

2. Consumer token-env allow-list: What schema key in apm-policy.yml restricts which env vars a package's MCP server may receive? How does the policy evaluator integrate with the MCP config generation path in src/apm_cli/install/mcp/? The --trust-transitive-mcp flag is per-install; the policy hook should be declarative and auditable. Default behavior must be fail-closed (deny unless explicitly allowed).

A short design doc (markdown, linked back here) settling the two schema contracts is the requested deliverable. Once the design is approved, the implementation scope and lockfile format changes will be clear.

See the current security model at https://github.com/microsoft/apm/blob/main/docs/src/content/docs/enterprise/security.md and the policy reference at https://github.com/microsoft/apm/blob/main/docs/src/content/docs/enterprise/policy-reference.md for the starting context.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Both items address real enterprise user needs. (1) Private MCP server sourcing from GitHub repos is the natural extension of APM's git-first model: teams with internal MCP definitions need a resolution path that does not require running a full MCP registry server. The proposed middle ground is the right ergonomic choice -- it matches how APM packages are already sourced. (2) The consumer token-env allow-list is a necessary safety guardrail: today a package can route a credential to a third-party MCP endpoint without the consumer's explicit knowledge. The design constraint is to keep the policy hook simple and auditable (one yaml block in apm-policy.yml, not per-install flags that a user might skip).

Supply Chain Security Expert -- Risk-Surface Reviewer

Both items touch P/G/S surfaces directly. (1) GitHub-repo MCP sourcing introduces a new resolution path that must maintain commit-SHA pinning (identity) and lockfile provenance (integrity). If the definition source is not pinned, a compromised repo becomes a substitution attack vector. AuthResolver must be used for the GitHub fetch; no ad-hoc token handling. (2) The consumer token-env allow-list is the mitigation for the credential-exfiltration surface already partially gated by --trust-transitive-mcp. Without a per-token allow-list, a package declaring env: GITHUB_TOKEN pointing to a third-party MCP endpoint is a silent credential leak. The design must specify fail-closed behavior: default deny unless explicitly allowed in apm-policy.yml. Both theme/security and theme/governance apply: security is the threat model; governance is the declarative policy mechanism that enforces it.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with deep project engagement; tone tuning for new contributors is not needed.

Python Architect -- Architecture Reviewer

Both items require schema and interface decisions before code lands. (1) GitHub-repo MCP sourcing needs a new yaml key in apm.yml, a new lockfile field in apm.lock.yaml, and a new resolution path (likely extending the registry resolver in src/apm_cli/core/). The lockfile change is a non-trivial cross-cutting impact touching multiple modules. (2) The consumer token-env allow-list needs a new policy schema element in apm-policy.yml and integration with the MCP config generation path in src/apm_cli/install/mcp/. The policy evaluator likely needs a new hook point in the config generation pipeline. status/needs-design is correctly applied: the design decisions (lockfile format, policy schema, trust evaluation order) must be settled before any PR can land safely.

Doc Writer -- Documentation Reviewer

Once the design is settled, implementing PRs must update: docs/src/content/docs/enterprise/security.md (updated security model section on MCP trust), docs/src/content/docs/enterprise/governance.md (new allow-list policy primitive), and docs/src/content/docs/enterprise/policy-reference.md (schema additions). The packages/apm-guide/.apm/skills/apm-usage/governance.md resource must also be updated (Rule 4). These are post-design obligations; flagging them now avoids an incomplete implementing PR. The implementing PR should include area/docs-site in its label set as a reminder.

APM CEO -- Triage Arbiter

The grouping is correct: both items are design-gated security/governance primitives that must be designed coherently to avoid conflicting policy surfaces. status/needs-design with a concrete design deliverable description is the right triage outcome. Adding theme/governance alongside theme/security is appropriate: the allow-list is a governance primitive (declarative policy), not just a security feature (threat mitigation). No milestone is assigned (design-gated items carry null milestone per the triage rubric); a milestone will be assigned when the design is approved and the implementation scope is clear. Priority labels are not applied on needs-design outcomes per the label-set construction rules.

{
  "decision": "needs-design",
  "decision_detail": "Two design decisions must be settled before implementation: (1) the yaml key and lockfile contract for GitHub-repo MCP server sourcing, and (2) the apm-policy.yml schema for the consumer token-env allow-list with fail-closed default behavior.",
  "theme": "theme/security",
  "areas": ["area/mcp-config", "area/mcp-trust"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design doc settling: (a) yaml key and lockfile contract for GitHub-repo MCP server sourcing, (b) apm-policy.yml schema for the consumer token-env allow-list, and (c) trust evaluation order between package env declarations and consumer policy restrictions.",
  "comment_markdown": "The two items are correctly grouped: both share the same trust-boundary model. Design spec must settle: GitHub-repo MCP sourcing (yaml key, lockfile contract, auth path) and consumer token-env allow-list (policy schema, fail-closed default, integration with MCP config generation path). Link the design doc back here once drafted."
}

---

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 · sonnet46 3M · ◷