[FEATURE] Extended MCP Server Configuration in apm.yml

[Vivalio]

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

APM currently supports simple MCP server references in apm.yml:

dependencies:
  mcp:
    - github
    - nx-mcp

However, this doesn't align with the MCP specification which requires additional configuration for enterprise deployments:

• Authorization (spec): Bearer tokens, custom headers, authentication methods
• Connection types: HTTP vs stdio transports with different parameters
• Input parameters: Runtime prompts for credentials and configuration
• Environment variables: Server-specific environment configuration

This forces users to maintain MCP configuration separately (e.g., .vscode/mcp.json), creating duplication and preventing APM packages from fully encapsulating their MCP requirements.

Describe the solution you'd like

Extend apm.yml to support MCP specification-compliant configuration:

dependencies:
  mcp:
    # Simple form (backward compatible)
    - nx-mcp
    
    # Extended form (new)
    - name: github-enterprise
      type: http
      url: https://copilot-api.company.ghe.com/mcp
      auth:
        type: bearer
        token_env: GITHUB_MCP_PAT
      inputs:
        - id: github_mcp_pat
          type: promptString
          description: "GitHub Enterprise PAT"
          password: true

Key capabilities needed:

1. HTTP and stdio transport configuration
2. Authorization headers and tokens per MCP spec
3. Input parameter definitions
4. Environment variable mapping
5. Export to runtime-specific formats: apm mcp export --runtime vscode

This would enable APM packages to fully specify MCP dependencies and allow users to generate runtime configs from a single source.

Describe alternatives you've considered

1. Status quo: Keep MCP config separate - but this prevents portability and creates maintenance burden
2. Template generation: apm mcp init --template enterprise - doesn't solve package portability
3. External config files: Reference .apm/mcp-config.json - adds file management overhead

All alternatives require manual per-project setup, whereas inline configuration in apm.yml enables true package-based distribution.

Additional context

Enterprise scenario: Platform teams need to distribute standardized MCP configurations (GitHub Enterprise endpoints, internal tools) across multiple repositories. Currently requires maintaining configs in multiple places (APM, VS Code, scaffolding tools).

MCP Spec alignment:

• Authorization
• Capability negotiation
• VS Code implementation: .vscode/mcp.json format

Backward compatibility: Simple string references would continue working; extended config is opt-in.

Impact: Enables APM packages to fully specify MCP requirements per the MCP specification, improving enterprise adoption and reducing configuration management overhead.

[danielmeppiel]

@Vivalio I agree with the need and pain.

Currently, APM supports installing MCP servers listed in apm.yml from a MCP spec-compliant registry. The default registry being used is the GitHub MCP Registry, but this can be overridden with an environment variable.

When running apm install, for each MCP server being installed, required environment and runtime variables are sourced from the MCP registry spec. Example for github-mcp-server here: https://api.mcp.github.com/v0/servers/search?q=github-mcp-server

Today, APM will prompt the user to provide the required values. Ideally though, if they're provided via the apm.yml file as local environment variables to get the values from, they could be taken from there.

Would that solve the problem from your point of view?

[Vivalio]

Thanks for the fast reply @danielmeppiel.

So the MCP servers we specify are spec compliant. However there is a mix of public and private MCP servers.

Some more context is, we are evaluating APM as a distribution tool for copilot setup accross the whole org. This will reduce our lean on NX generators/plugins. However different teams will have different setups etc, so APMs logic seems very attractive to solve that.

If i am understanding you correctly, it sounds like a workaround could be to point directly at a private mcp registry? However i suppose our cons for that are that we have to maintain something else again, or we have a mix of public and private mcp servers that we need to somehow support pulling.

At the moment, we use the GITHUB_HOST env, to pull private APM packages fine, but have not found a clean solution to the MCP config issue.

I think the prompt for required properties is definately a help, but im not sure that would solve our issue on optional variables. For example, the github official MCP server. We want to point that to our github enterprise with data residency account (ghe domain), but the URL i believe is optional for that mcp server, also there is the required token that is injected into that config only when the optional URL is set.

I know the documntation for APM mentioned a csv for host domains, however this seemed more like a place to pull from not a configuration varience feature.

The environment variable suggestion for the apm.yml file could work, however im unsure if that might cuase issues with more complex configuration like arg arrays etc?

Hope this helps, happy to explain further.

[danielmeppiel]

@Vivalio happy to help and get this scenario to work, I have simply not prioritized it so far, was waiting on the MCP Registries to come alive.

• Mix of public and private MCP servers: agree, I expect this to be commonplace. I was thinking larger teams and enterprises would prefer setting up a private MCP registry for proper and secure distribution and management of private MCP servers. Some vendors are starting to offer that capability as a product, such as Azure API Center for private MCP registries. Agree it can be overkill in some scenarios, so I am wondering if sourcing private MCP servers from a GitHub repo would be a good middle ground, same as for APM packages?

• Managing required/optional variables for MCP servers: prompting is a quick solution (and actually it already looks for environment variables with the same name as the MCP variable coming from the registry to skip prompting and work in headless automation mode). But that does not work today with optional variables indeed. I think we have a quick win here if we allow making them "required" from apm.yml and use the same mechanism (look up for an env var in the host to source the value from). This is to avoid hardcoding secrets in apm.yml but I am open to other ideas.

• arg arrays issue: I am not sure I visualize the problem? Ultimately, the host running apm will be able with the above mechanism to dictate what the value should be for each MCP variable?

[Vivalio]

Hey @danielmeppiel Sorry for the late reply.
I think that is a great idea. I like the Repo suggestion as MCP registries. I noticed there is some logic in the APM code about resolving github hosts too so i imagine it might be a good idea to support private and GHE accounts for these repos too. I do like the ide of the private MCP repo but (only my opinion) i think a lot of orgs are in an evaluate phase at the moment and might not want to jump to a full MCP enterprise solution of sorts. So in short i think your repo middle ground is a great idea.

If adding a required field in the apm.yml re-uses the logic you already have then that is certainly a quick win. I wonder do you imagine there could be any complications with some types of configuration fields? Such as, if a url is provided then an auth token is required, but without a url its not required? Im not sure if any quirks like that could cause an issue but just wanted to check.

Feel free to ignore the arg array comment, I could have been getting a little confused at the time of reading youe initial response.

Thank you so much for the timely replies also.

[TechWatching]

I just came across this issue as I wanted to install some public mcp servers that are not in GitHub MCP Registry. I understand the vision with the use of private MCP registry. Yet in my case I just want to create a package that I will share publicly, so I need to be able to specify the configuration of the MCP Servers I want to install (ideally in the same format I currently use when I manually install a mcp server in vscode for instance).

I am not sure to have understood everything you discussed about prompting optional/recommended fields. When I use GitHub MCP Server, I sometimes change the tools available directly by specifying the X-MCP-Tools header. Is it something that is or will be possible?

[danielmeppiel]

Labeling needs-design — MCP server configuration may be delivered via other means (e.g. a future plugin system, external tooling, or native IDE config). We should settle the delivery model before committing to an apm.yml schema for this.

[sergio-sisternes-epam]

Status update — March 2026

Since this issue was opened, APM has shipped most of the capabilities requested here. Quick rundown:

What's landed:

• Extended apm.yml format — object notation with name, transport, env, args, headers, tools, url, command, version, registry, package fields. Simple string form still works (backward compatible).
• All transports — stdio, http, sse, streamable-http via transport field.
• Auth & headers — arbitrary headers dict, env dict for token injection (${{ secrets.* }} syntax), plus Copilot adapter auto-injects Authorization: Bearer for GitHub MCP Server.
• Environment variable mapping — prompted at install time, auto-resolved from host env vars.
• Multi-runtime config generation — VS Code (.vscode/mcp.json), Copilot CLI (~/.copilot/mcp-config.json), and Codex (TOML) all generated during apm install.
• Self-defined servers — registry: false for fully custom MCP servers without any registry dependency.
• Tool filtering — tools: ["repos", "issues"] to restrict exposed tools.
• Transitive MCP dependencies — collected from package tree with --trust-transitive-mcp for security.
• Formal schema — documented in docs/manifest-schema.md (Section 4.2).

@TechWatching — your scenario (public APM package with MCP servers not in the GitHub Registry) is now supported. You can declare self-defined MCP servers in your package's apm.yml using registry: false with the same fields you'd use in .vscode/mcp.json (command, args, env, transport, headers, etc.). When consumers install your package with --trust-transitive-mcp, those servers are picked up and configured automatically. Without the flag, consumers are warned and can re-declare the server in their own apm.yml for explicit control. Note: this is available on main today and will ship as part of v0.8.0.

The core ask — extended MCP config in apm.yml with transport, auth, env vars, headers, and multi-runtime export — will be addressed with the release of v0.8.0. Tracking remaining items below:

• Custom registry URLs — registry: "https://..." parsed but not fully wired at install time
• Conditional input logic — e.g., "if URL is set → require auth token"
• Standalone apm mcp export --runtime vscode command (currently config generation is tied to apm install)
• Private MCP servers sourced from GitHub repos (discussed earlier in the thread)

[rcollette]

I just tried installing context7 and I am prompted for an authorization token, which is not mandatory. I deleted the environment configuration from the local .vscode/mcp.json and on subsequent installs, that configuration is overridden.

There needs to be a way to specify some some inputs/variables as being optional and not set when no value is provided.