MCP model silently drops harness-specific keys (e.g. Claude Code `oauth`) — no passthrough for remote-MCP OAuth client config

[hinderberg]

Summary

apm's MCP dependency model carries only a fixed field set and silently discards any other keys on render. There is no way to express harness-specific MCP config that apm doesn't model, notably Claude Code's remote-MCP oauth block (clientId / callbackPort). For a remote MCP server that requires a pre-registered OAuth client because it does not support Dynamic Client Registration (RFC 7591), this makes the server unusable when configured through apm.

Environment

• Reproduced on apm 0.15.0; confirmed still present in source on v0.17.0 (latest).
• Target: Claude Code (.mcp.json).

What happens

MCPDependency (src/apm_cli/models/dependency/mcp.py) models only:
name, transport, env, args, version, registry, package, headers, tools, url, command.

• from_dict: "Unknown keys are silently ignored for forward compatibility."
• to_dict: serializes only that whitelist.

So this apm.yml:

dependencies:
  mcp:
    - name: slack
      registry: false
      transport: http
      url: https://mcp.slack.com/mcp
      oauth:
        clientId: "<pre-registered-client-id>"
        callbackPort: 3118

produces a generated .mcp.json slack entry with no oauth key. No warning is emitted; apm install reports success.

Why it matters (concrete failure)

Claude Code's .mcp.json supports an oauth block to pin a pre-registered OAuth client. Slack's remote MCP (https://mcp.slack.com/mcp) does not support Dynamic Client Registration, so without a pre-registered clientId Claude Code's OAuth fails with:

SDK auth failed: Incompatible auth server: does not support dynamic client registration

Because apm cannot carry the oauth block, a Slack MCP configured via apm cannot authenticate. The same applies to any remote MCP needing harness-specific auth config apm doesn't model.

Two distinct problems

1. No passthrough for harness-specific MCP fields. The universal model is a lowest-common-denominator with no escape hatch (e.g. a per-harness claude: / extra: map) to round-trip fields verbatim into the target manifest.
2. Silent drop. Unknown keys are discarded with no warning, so a user who supplies the correct field name gets no signal it was ignored. It fails closed and silently.

Note: apm pack already strips credential-shaped keys from the Claude .mcp.json manifest, which suggests apm knows .mcp.json carries richer config than the model represents. It currently treats the surplus as something to drop, never to preserve.

Proposed fixes

• Add a passthrough / per-harness override for MCP entries that round-trips into the generated manifest (an oauth field, or a generic extra / claude block).
• At minimum, emit a warning when from_dict discards unknown keys instead of dropping them silently.

Workaround

Re-inject the field into the generated .mcp.json after apm install via a post-install hook, since apm regenerates the file from apm.yml on every run.

[github-actions]

Triage decision

accept

(Note: status/accepted and status/shepherding were already applied by a maintainer and are authoritative. Adding theme/security, area/mcp-config, area/docs-site, type/feature, priority/high, and status/triaged as new classification dimensions.)

Proposed labels

theme/security
area/mcp-config
area/docs-site
type/feature
status/accepted
priority/high

Milestone

null

Suggested next action

Land the unknown-key warning as a quick-win PR first, then open a design discussion for the per-harness passthrough mechanism (claude: block or generic extra: map) before implementing the full passthrough.

Suggested issue comment

Thanks for the precise analysis, @hinderberg -- citing RFC 7591 Dynamic Client Registration and tracing the exact code paths in MCPDependency.from_dict and to_dict makes this immediately actionable.

Two parts to resolve here, as you identified:

Part 1 (quick win): Emit a warning when from_dict discards unknown keys. The current "silently ignored for forward compatibility" behavior means a user who supplies the correct key name (oauth) gets no feedback that it was dropped. A [!] Unknown MCP key(s) ignored: oauth warning on install would surface the issue immediately and unblock users who can then use the post-install hook workaround with confidence.

Part 2 (design needed): A passthrough mechanism so that harness-specific fields round-trip from apm.yml into the generated target manifest. The options are a generic extra: block (target-agnostic) or a per-harness override (e.g., claude: map for Claude Code-specific config). The design needs to consider: (a) how apm pack handles passthrough fields (credential-shaped keys like clientId are currently stripped), and (b) whether the passthrough should be scoped to specific targets or apply universally.

The oauth block is a concrete, high-impact case -- Slack MCP requires it and cannot be configured through APM without it. This is accepted as a high-priority feature.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Silent drop of unknown keys is a critical UX failure: apm install reports success, but the generated manifest is silently wrong. The warning fix (Part 1) immediately improves this. The passthrough mechanism (Part 2) resolves it fully. Both align with the "failure mode is the product" mental model.

Supply Chain Security Expert -- Risk-Surface Reviewer

The oauth block contains clientId -- credential-adjacent config. The passthrough design must ensure: (1) apm pack does not accidentally publish user-specific clientId values, and (2) the passthrough round-trips correctly without modification by APM's security model. A generic extra: map risks carrying arbitrary credential-shaped data. A per-harness claude: block is more auditable. theme/security applies because this touches auth configuration at the MCP trust boundary.

OSS Growth Hacker -- Contributor-Tone Reviewer

hinderberg (NONE association) is technically sophisticated -- citing RFC 7591 and tracing source file paths. Tone is peer-level. The two-part sequencing (warning PR first, then design discussion) gives a clear path forward and keeps the contributor engaged. Acknowledging the Slack MCP use case by name signals that the practical impact is understood.

Python Architect -- Architecture Reviewer

Part 1 (warning) is a one-line change in from_dict. Part 2 (passthrough) requires design: a per-harness claude: {...} block in MCPDependency is cleaner than a generic extra: map -- APM already has target-aware rendering and to_dict could check the target and merge the harness block. The apm pack stripping logic also needs updating to distinguish credential fields from passthrough config.

Doc Writer -- Documentation Reviewer

Once the passthrough mechanism is implemented, the MCP config reference and the Claude Code target docs must document the new field. area/docs-site rides as a secondary label to remind the implementing PR. The warning change (Part 1) needs a changelog entry but no doc update.

APM CEO -- Triage Arbiter

Making Slack MCP work through APM is a high-visibility adoption signal -- Slack is one of the most commonly installed MCPs. The silent drop is a trust issue: users cannot rely on APM faithfully representing their config. theme/security applies because the auth config (OAuth client registration) is in scope. The two-part sequencing is the right strategic approach: ship incremental value without waiting for the full design.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/security",
  "areas": ["area/mcp-config", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Land the unknown-key warning as a quick-win PR, then open a design discussion for the per-harness passthrough mechanism before implementing full passthrough."
}

---

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 6.5M · ◷