Skip to content

agent_resolver fetches capabilities with a plain GET; the spec and JS SDK call get_adcp_capabilities over the agent's protocol #1276

Closed

Description

@bokelley

Problem

adcp.signing.agent_resolver._fetch_capabilities resolves a signer's capabilities with a plain GET <agent_url> (Accept: application/json) and parses the body as JSON. The spec's key-discovery flow (security.mdx, "Discovering an agent's signing keys via brand_json_url", step 1) fetches get_adcp_capabilities from the agent at its protocol endpoint. The JS SDK follows that: resolveAgent calls get_adcp_capabilities through its MCP or A2A client and explicitly never does a raw GET on the agent URL ("the agent URL is the protocol endpoint, not a JSON capabilities document").

The two SDKs therefore need different things from the same agent URL. An agent that only speaks MCP/A2A at its URL (the spec's model) fails Python's resolver with capabilities_unreachable or capabilities_invalid. An agent that only serves JSON on GET fails the JS resolver. We hit this publishing our own buyer-agent identity and now serve both, but most agents won't know to.

Proposal

Fetch capabilities over the agent's protocol, matching the JS SDK. Call get_adcp_capabilities through the MCP client (default) or the A2A client, chosen by a protocol argument like JS resolveAgent(url, { protocol }).

If a JSON GET needs to stay for compatibility, use it only as a fallback after the protocol call fails, and document it as an SDK extension rather than the spec's path.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (spec/JS-SDK parity divergence in capability fetch transport)
    Bucket(s): signing (signing label absent — gap noted)
    Status: ready-for-human
    Milestone: omitted

    What the experts said:

    • ad-tech-protocol-expert: Whether the AdCP spec requires a protocol call for cold/unauthenticated discovery bootstrapping (vs. allowing HTTP GET) needs a direct cite from security.mdx — neither the issue nor the code supplies one. The existing HTTP GET with SSRF guards is architecturally correct for the threat model; the JS SDK likely operates on an already-established trusted session, not a cold attacker-shaped URL. Recommends a separate async_resolve_agent_via_mcp path requiring a pre-authenticated client handle, not changing the default GET path. Classifies the spec-compliance claim as needs-more-info rather than confirmed bug.
    • security-reviewer: Two blockers against the proposed change as described. (1) MCP/A2A clients carry their own transport stack — routing through one silently removes the IP-pin SSRF guard (build_async_ip_pinned_transport) that is the module's primary defense against redirecting to cloud-metadata or internal services. (2) MCP tool responses can carry structured text content; an attacker controlling the server can inject prompt fragments that reach downstream consumers if any call site ever passes the capabilities body into an LLM prompt. A GET-then-MCP fallback also creates a degradation attack surface. All three concerns require human security sign-off.

    My take: The SSRF-guarded HTTP GET design is deliberate and documented; the module's docstring explicitly names why ADCPClient is excluded ("attacker-shaped URL"). The proposed default-to-MCP change raises two security blockers and the spec-compliance rationale needs a concrete cite. A safe path forward is: (a) confirm via adcontextprotocol/adcp spec whether protocol invocation is required for cold discovery, and (b) if yes, add a separate opt-in async_resolve_agent_via_mcp(url, *, mcp_client) overload that requires a caller-supplied, already-authenticated MCP client with the SSRF transport injected — rather than changing async_resolve_agent's default.

    For @bokelley:

    • Can you link the exact security.mdx paragraph that requires a protocol call for unauthenticated capability discovery (vs. permitting HTTP GET)?
    • Should this be tracked cross-repo in adcontextprotocol/adcp to clarify the spec text, before the Python SDK changes transport?

    Triaged by Claude Code. Session: https://claude.ai/code/session_01NVXk1uSjUs7txZKZXVKe21


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions