Skip to content

Python: [Bug]: declarative MCP approvalMode in specify mode fails to load #9864

Open

Description

Observed Behavior

McpTool parses its approvalMode with the base McpServerApprovalMode, which only accepts kind. Two shapes fail:

  1. The dict form with the specify mode and its tool lists raises TypeError, crashing the load of any spec that uses an MCP tool in specify mode.
  2. The string form "specify" (and {kind: specify} without lists) parses into the base class instead of McpServerToolSpecifyApprovalMode, and the agent loader dispatches require_approval by checking for the specify subclass, so the approval configuration is silently dropped and default approval rules apply.

Expected Behavior

Every documented approval mode parses into its own subclass with its full state on both the dict and simplified string forms, so the loader can wire require_approval from the tool lists.

Steps to Reproduce

  1. Build McpTool.from_dict with approvalMode: {kind: specify, alwaysRequireApprovalTools: [...], neverRequireApprovalTools: [...]}.
  2. Observe the TypeError.
  3. Build the same tool with approvalMode: "specify" and check type(tool.approvalMode).

Minimal Reproduction

from agent_framework_declarative._models import McpTool

tool = McpTool.from_dict({
    "kind": "mcp", "name": "srv",
    "approvalMode": {
        "kind": "specify",
        "alwaysRequireApprovalTools": ["alpha"],
        "neverRequireApprovalTools": ["beta"],
    },
})
# TypeError: McpServerApprovalMode.__init__() got an unexpected keyword argument 'alwaysRequireApprovalTools'

tool = McpTool.from_dict({"kind": "mcp", "name": "srv", "approvalMode": "specify"})
# type(tool.approvalMode) is McpServerApprovalMode (base), not McpServerToolSpecifyApprovalMode

Error Messages and Stack Traces

TypeError: McpServerApprovalMode.__init__() got an unexpected keyword argument 'alwaysRequireApprovalTools'

Package Versions

agent-framework-declarative: 1.4.0 (main @ 4d28d0a)

Python Version

Python 3.12.13

Operating System

macOS

Regression

Unknown

Additional Context

The always and never modes work only because the base class happens to hold all their state. agent_schema_dispatch already builds the specify subclass correctly when the approval mode is loaded as a top level component, so the tool parsing could dispatch by kind the same way. I have a fix ready once the team agrees with the direction.

Acknowledgements

  • I searched existing issues and did not find a duplicate.
  • I personally verified this behavior and the reproduction details are authentic.
  • I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Activity

  1. eavanvalkenburg commented on Oct 30, 2026

    @eavanvalkenburg
    Member

    please use the defined issue templates and wait for the team to review before opening a PR Manohar Paturi (@ManoharPaturi)

  2. changed the title [-]Declarative: MCP approvalMode in specify mode fails to load with tool lists[/-] [+]Python: [Bug]: declarative MCP approvalMode in specify mode fails to load[/+] on Oct 31, 2026
  3. eavanvalkenburg commented on Nov 9, 2026

    @eavanvalkenburg
    Member

    /plan Plan the confirmed declarative MCP approval-mode parsing bug on current main before readiness. A list-bearing specify dictionary raises TypeError in McpServerApprovalMode.init. Independent exact-source probes also show that a supported explicit specify-mode object serializes with its subclass type marker but fails to reload through McpTool with a type-mismatch ValueError; existing serialized base-mode always payloads do round-trip and must remain usable. Reuse the existing approval classes and loader require_approval mapping, preserving both tool lists and current always/never behavior. Cover raw dictionaries, simplified strings, preconstructed modes, legacy base-mode type markers, subclass round-trips, nested agent loading, and exact loader kwargs. An empty specify string/dictionary has no tool lists, so do not claim independent policy loss from that form alone. Separate the supported-mode repair from the new unknown-kind rejection proposed by already closed #9865; do not silently introduce a validation/compatibility policy change. Determine the smallest correct production scope and serialization contract before calling this a minor fix. Keep triage, do not add ready-for-implementation, and defer assignment. The author is willing, but this is planning, not implementation approval or permission to reopen the closed PR.

  4. github-actions commented on Nov 9, 2026

    @github-actions
    Contributor

    Summary

    McpTool always parses approvalMode with the base class McpServerApprovalMode, which only accepts kind (_models.py lines 737-814). I checked this by reading the source only. I did not run any code.

    The issue is real on current main, and it has three parts:

    1. List-bearing specify dictionary. {kind: specify, alwaysRequireApprovalTools: [...], ...} is passed to the base class. The base __init__ has no list parameters, so it raises TypeError. This is a confirmed crash.
    2. Explicit specify subclass round-trip. McpServerToolSpecifyApprovalMode is a supported class. Its to_dict() writes type: mcp_server_tool_specify_approval_mode, and the base class's from_dict() expects mcp_server_approval_mode. SerializationMixin.from_dict therefore raises ValueError: Type mismatch. This agrees with your probes. The same logic also applies to the always/never subclasses, which I did not probe (see questions below).
    3. Bare specify (string or {kind: specify}). This becomes a base-class object. The loader (_loader.py ~808-825) checks kind == "always", then "never", then isinstance(..., McpServerToolSpecifyApprovalMode). The base-class object fails that last check, so no require_approval is set. But there are no tool lists in this form, so this is not independent policy loss. It is a wrong type and a latent trap for anything that later adds lists.

    Always and never work today only because the base class holds all of their state. The loader branches on kind for those two.

    The top-level path already dispatches by kind. agent_schema_dispatch maps always, never and specify to their subclasses (lines ~1124-1128), and tests cover that at test_declarative_loader.py ~269-300. The nested McpTool path does not use it.

    Recommendation

    Code change: warranted, but small and confined to the declarative package. Keep it labelled triage, with no ready-for-implementation label and no assignment yet. I would not call it a "minor fix" until the points under "Serialization contract" below are settled. There is no workaround short of constructing McpServerToolSpecifyApprovalMode objects in Python and never reloading them.

    Smallest production scope

    • One file: _models.py, inside the McpTool.__init__ approval-mode normalisation.
    • No loader change: _loader.py already maps the specify subclass to require_approval correctly. Once the right subclass arrives, it works.
    • No core change: the type-mismatch check in SerializationMixin is deliberate and should stay.
    • Reuse the existing classes: do not add new approval classes.

    Serialization contract (the real decision)

    The marker is derived from the class name, so each class has its own type:

    • Base: mcp_server_approval_mode
    • Specify: mcp_server_tool_specify_approval_mode
    • Always and never: their own markers

    For loading, I propose the following rules. Maintainers should confirm them.

    • Dispatch on kind. always, never and specify go to their subclasses, as the top-level dispatch does.
    • Accept both families of type marker. Legacy base-class markers must keep loading, so existing serialized base-mode payloads continue to work. Subclass markers must also load. This is the part that needs a careful look: from_dict rejects a marker that does not match the target class, so the code must pick the target class before calling it, or strip or normalise type.
    • Do not change to_dict() output for existing objects unless maintainers choose to.
    • Preserve both tool lists (alwaysRequireApprovalTools and neverRequireApprovalTools) through load and save.
    • Keep always/never behaviour as it is today. The loader still emits "always" and "never". If the kind-dispatched classes round-trip correctly, nothing observable changes.

    Keep separate: unknown-kind rejection (Closes #9865)

    Today an unknown kind loads into the base class without error. Rejecting it would be a new compatibility and validation policy, not a repair of a supported mode. I suggest the repair keeps the existing fallback for unrecognised kinds (still the base class, so there is no behaviour change). Whether to reject them should be a separate, explicit decision, possibly with a deprecation step. It is not authorised by this plan.

    Proposed plan

    This is a proposal only. No changes have been made.

    1. Decide the contract. Maintainers confirm the rules above, especially which type markers load and what is written on output.

    2. Change McpTool normalisation in _models.py. Replace the two McpServerApprovalMode.from_dict(...) calls with kind-based selection of the existing classes. Leave pre-built McpServerApprovalMode instances untouched. Handle both the string form and the dict form, and tolerate legacy base-class type markers.

    3. Tests in test_declarative_models.py and test_declarative_loader.py:

      • Raw dict with lists: asserts the subclass type and both lists.
      • Strings "always", "never" and "specify": the first two behave as before, and "specify" gives the specify subclass with no lists.
      • Empty-list and {kind: specify} forms: assert no require_approval, with no policy-loss claim.
      • Pre-built base and subclass objects are kept as given.
      • Legacy base-class type markers still load (always and never).
      • to_dict() followed by loading again, for the specify subclass and for existing base always payloads.
      • Nested agent loading: AgentFactory from YAML with a specify block.
      • Exact loader kwargs: require_approval == {"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}. Also check always, never and the two single-list cases.
      • An unknown kind keeps its current behaviour (a pin test, so the policy decision stays separate).
    4. Done when the issue's two snippets load, specify tool lists survive a save and reload, existing always/never tests pass unchanged, and the declarative test suite is green.

    Questions before readiness

    1. Should the specify, always and never subclasses write their own type marker (today's behaviour), or should McpTool serialise the kind form only? This decides whether old and new readers can exchange payloads.
    2. Should an explicit non-specify subclass marker (for example an always subclass on a reloaded McpTool) also be covered, or only specify? By the same logic it should fail to reload today, but I did not verify it.
    3. Is it acceptable to leave unknown-kind handling untouched here and track rejection as its own issue?

    The author is willing, but this is planning only. Please wait for maintainer agreement on the contract before any implementation work.

    Generated by Issue Planning for #9864 · copilot · auto · ~41 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷

  5. ManoharPaturi commented on Nov 10, 2026

    @ManoharPaturi
    ContributorAuthor

    Eduard van Valkenburg (@eavanvalkenburg) should i start working on this ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUsage: [Issues], Target: All issues that still need to be triaged

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions