[FEATURE] MCP dependency config overlays in apm.yml

[danielmeppiel]

Problem

APM currently treats MCP dependencies as opaque registry strings (- github/github-mcp-server). The registry provides server metadata (transport, packages, env var names, args), and APM's adapters generate client configs from this.

However, there's no way for a package author or consumer to express project-specific preferences over what the registry provides. APM makes decisions for you (e.g., always prefer remote over local, use first package, hardcode tools: ["*"]).

Proposed: Config overlay format

Allow apm.yml to express preferences and overrides on top of registry metadata — not replacing it:

dependencies:
  mcp:
    # Simple string — pure registry, no overrides (current behavior)
    - io.github.mleoca/ucn

    # Object form — registry name + overrides
    - name: github/github-mcp-server
      transport: stdio                     # prefer local/stdio over remote/HTTP
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      args:
        toolsets: "repos,issues"           # override/add runtime arguments

    - name: some-org/some-server
      version: "1.2.0"                    # pin specific version instead of latest
      registry: https://registry.modelcontextprotocol.io   # resolve from specific registry

Overlay dimensions

Based on the MCP Registry schema (2025-12-11):

Override	What it does	Why
transport	Prefer stdio / streamable-http / sse	APM hardcodes remote-first priority. Codex rejects HTTP entirely. Users should choose.
env	Provide project-specific env var values	Registry declares which env vars a server needs (name, isRequired, isSecret). It can't know your actual API_KEY.
args	Override/extend runtime or package arguments	Registry defines defaults, but a project may need --workspace ./src or --port 3001.
version	Pin a specific server version	Registry returns latest. Some projects need reproducibility.
registry	Resolve from a specific registry URL	MCP_REGISTRY_URL is global. A package may need deps from different registries (GitHub subregistry vs official).
package	Select which package type to use	When a server has both npm and docker packages, let the user pick (npm, pypi, oci). Related to transport preference.
headers	Custom HTTP headers for remote endpoints	Auth tokens, custom routing headers for remote/streamable-http servers.
tools	Restrict which tools are exposed	Currently hardcoded to ["*"]. Some projects may want to whitelist specific tools for security/scope.

Design principles

1. Registry-first: The overlay augments registry metadata, never replaces it. name must resolve in a registry.
2. Optional: Simple string form stays the default. Object form is opt-in.
3. Minimal: Only override what you need. Everything else comes from the registry.
4. No inline server definitions: This is NOT about defining command, url, or transport details inline. That's the registry's job. This is about preferences and values.

Depends on

• [BUG] MCP dependencies from transitive packages are not propagated to the consumer project #121 — Fix transitive MCP dep propagation (string deps silently dropped)

Related

• [FEATURE] Support stdio MCP servers in inline dependency declarations #122 — Closed as won't-fix. Proposed full inline stdio definitions; this replaces that approach with registry overlays.
• [Discussion] Design inline MCP dependency format vs MCP Registry alignment #131 — Discussion on inline MCP format vs registry alignment

[danielmeppiel]

@sergio-sisternes-epam this one may be interesting for you, thoughts?

[sergio-sisternes-epam]

@danielmeppiel

The overlay format makes sense, and the design principles are solid. My main concern is with principle 4: "No inline server definitions. That's the registry's job."

The problem:
In corporate/enterprise environments, private MCP servers are becoming a core use case — internal APIs, compliance tools, knowledge bases, observability. None of these will be on the public registry, and running a subregistry is non-trivial overhead that most teams won't have on day one. If APM can only distribute MCP servers that exist in a registry, we create an entry barrier that slows adoption exactly where the demand is growing fastest.

Today, if a platform team wraps a private MCP server in an APM skill package, consuming teams still have to manually configure mcp.json. That breaks the transitivity story we just fixed in #121/#123.

Proposal:
registry: false as an explicit escape hatch

Same object format, same dependencies.mcp section — just an explicit marker that says "this server isn't registry-resolved, I'm providing the transport details":

dependencies:
  mcp:
    - github/github-mcp-server                    # registry string (unchanged)

    - name: github/github-mcp-server              # registry + overlay (this issue)
      transport: stdio

    - name: acme-knowledge-base                    # private server, no registry
      registry: false
      transport: http
      url: "${ACME_KB_MCP_URL}"
      env:
        ACME_KB_TOKEN: "${ACME_KB_TOKEN}"

Why this works:

• Explicit intent — no ambiguity between "registry is down" and "this is a private server". No typo masking.
• Auditable — grep "registry: false" across the dependency tree shows all self-defined servers. Security teams can review.
• Natural migration path — once the org has a private registry, change registry: false to registry: https://mcp.internal.acme.com. Remove it entirely when published publicly. The rest of the YAML stays identical.
• Fits the existing format — no new sections, no parallel schema. It's one more overlay dimension.
• Transitive trust: self-defined servers (registry: false) should only propagate from direct dependencies. If a transitive package declares one, APM warns and asks the consumer to re-declare it. This keeps the security model clean without needing an allowlist mechanism.

Validation:
When registry: false, apm compile enforces required fields — transport always, url for HTTP transports and command for stdio. Missing fields are compile errors.

I'd scope this as part of #132 since the schema and adapter code overlap significantly.

[danielmeppiel]

@sergio-sisternes-epam I am convinced now. It's true that we are far away from MCP Registries being commonplace. I like the registry: false attribute as a way to making it mandatory to intentionally flag these configurations as not supported by the registry, because I have the feeling that once MCP Registries take off, that is going to be the preferred, safest solution. When that happens, registry:false can be leveraged to flag configurations that need to be migrated to a registry.

Agree to scope it together with the overlaying. And you're right, this sounds like a key enabler at the stage where we are at.

[sergio-sisternes-epam]

Post-integration feedback: transitive MCP re-declaration is too friction-heavy

After E2E testing the transitive trust rule with real packages (agent-library → apm-tests), the requirement to manually re-declare every self-defined (registry: false) MCP server from transitive dependencies is frustrating in practice. A package graph with 3–4 levels of dependencies can surface multiple private MCP servers that the consumer must copy verbatim into their own apm.yml just to keep them from being silently dropped.

Proposal: Add a --trust-transitive-mcp flag to apm install (and apm compile) that skips the transitive trust validation and allows self-defined MCP servers from upstream packages to flow through without re-declaration.

Behavior	Without flag (default)	With --trust-transitive-mcp
Registry MCP servers	Installed	Installed
Self-defined MCP from direct deps	Installed	Installed
Self-defined MCP from transitive deps	Skipped with warning	Installed

The default remains secure (consumers must explicitly trust private MCP endpoints they didn't declare), but the flag removes the friction for teams that control their full dependency chain and trust upstream packages.

Will implement this as a follow-up to the current PR.