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 registryOverlay 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
- Registry-first: The overlay augments registry metadata, never replaces it.
name must resolve in a registry.
- Optional: Simple string form stays the default. Object form is opt-in.
- Minimal: Only override what you need. Everything else comes from the registry.
- 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
Related
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.ymlto express preferences and overrides on top of registry metadata — not replacing it:Overlay dimensions
Based on the MCP Registry schema (2025-12-11):
transportstdio/streamable-http/sseenvname,isRequired,isSecret). It can't know your actualAPI_KEY.args--workspace ./srcor--port 3001.versionregistryMCP_REGISTRY_URLis global. A package may need deps from different registries (GitHub subregistry vs official).packagenpm,pypi,oci). Related to transport preference.headerstools["*"]. Some projects may want to whitelist specific tools for security/scope.Design principles
namemust resolve in a registry.command,url, or transport details inline. That's the registry's job. This is about preferences and values.Depends on
Related