Tenant discovery: `.well-known/adcp-agents.json` for multi-agent topology enumeration

[bokelley]

Summary

A publisher (or any AdCP operator) running a multi-agent topology — sales agent at /sales, signals at /signals, governance at /governance, creative at /creative, etc. — has no standard way to advertise which tenants are live, what each tenant's URL is, and which specialisms each tenant claims. Buyers and conformance runners (e.g., adcp-client PR #1355 which adds per-specialism routing) have to learn the topology out-of-band: a Notion page, a CSV, or hardcoded lists in the runner.

The prod test-agent demonstrates the problem precisely: six tenants live at https://test-agent.adcontextprotocol.org/{sales,signals,governance,creative,creative-builder,brand}/mcp, but the only way to learn that list today is to read adcontextprotocol/adcp:server/src/training-agent/index.ts TENANT_IDS. There's no machine-readable manifest.

Proposal

Define a new well-known endpoint:

GET /.well-known/adcp-agents.json

Returns a manifest of tenants served from this origin:

{
  "version": "1.0",
  "agents": [
    {
      "key": "sales",
      "url": "https://example.com/sales/mcp",
      "transport": "mcp",
      "specialisms": ["sales-non-guaranteed", "sales-guaranteed"],
      "auth_hint": "shared_bearer"
    },
    {
      "key": "signals",
      "url": "https://example.com/signals/mcp",
      "transport": "mcp",
      "specialisms": ["signal-marketplace", "signal-owned"],
      "auth_hint": "shared_bearer"
    }
  ]
}

auth_hint is optional and informational only — shared_bearer, per_tenant_bearer, oauth, etc. The actual auth is negotiated out-of-band; this just helps tooling render hints to the operator.

The endpoint MUST be readable without authentication (parity with .well-known/agent-card.json). For privacy, operators MAY return only the public/test tenants and gate production tenants behind authenticated discovery on a different path.

Why

• Buyers: machine-readable enumeration replaces the "find the publisher's tenant list in their docs" hop.
• Conformance runners: adcp storyboard run --agents-map can be replaced with adcp storyboard run --discover https://publisher.example for the common case.
• AAO Verified: certification can verify a publisher's declared topology against its actual surface in one fetch instead of N tenant-card probes.

Relation to existing well-known endpoints

• /.well-known/agent-card.json — single-agent manifest (per A2A / AdCP today). For multi-tenant operators this card is either missing or describes one (arbitrary?) tenant. The new endpoint complements it.
• /.well-known/oauth-authorization-server — RFC 8414 OAuth metadata. Orthogonal.
• /.well-known/brand.json — brand identity. Orthogonal.

Found by

PR review of adcp-client#1355 — flagged by the adtech-product-expert reviewer as the upstream bottleneck for multi-agent adoption: "buyers don't get tenant URLs from publishers as a structured artifact. They get a Notion page or a CSV. A discover-tenants primitive would do more for adoption than this PR."

Out of scope (file as follow-ups)

• Per-tenant signed manifests (TLS chain trust is sufficient for v1).
• Capability-aware filtering at the manifest level (operator advertises full list; runner fetches each tenant's get_adcp_agent_capabilities for the per-specialism detail).
• Versioning beyond a top-level version field.

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol, registry / discovery
Status: ready-for-human
Milestone: 3.1.0 (#2)

What the experts said:

• adtech-product-expert: Concept validated — _training_agent_tenants in server/src/training-agent/index.ts already proves the need in production. Two blockers on the proposed shape: (1) a standalone adcp-agents.json file doesn't inherit the authoritative_location redirect pattern from adagents.json, which SSP-operated multi-publisher deployments depend on — they control the agent subdomain, not the publisher apex; (2) auth_hint as an informational free-form string will be branched on by runners/buyers and will silently fail when auth rotates — swap for RFC 9728 oauth_protected_resource_url (which AdCP already references) or remove the field entirely.

My take: The need is real and 3.1.0 is the right window. One structural question must be answered before schema is written: new standalone file, or extend adagents.json?

@bokelley, your call — Option A or Option B:

Option A — New /.well-known/adcp-agents.json (as proposed, with auth_hint removed):

{
  "version": "1.0",
  "agents": [
    {
      "key": "sales",
      "url": "https://example.com/sales/mcp",
      "transport": "mcp",
      "specialisms": ["sales-non-guaranteed", "sales-guaranteed"]
    }
  ]
}

Clean dedicated endpoint; simpler discovery URL for tooling. Requires adding an authoritative_location-equivalent redirect pattern for SSP-hosted publishers (not in the proposal today).

Option B — Extend adagents.json inline variant with tenants[] (expert recommendation):

{
  "authorized_agents": [...],
  "tenants": [
    {
      "key": "sales",
      "url": "https://example.com/sales/mcp",
      "transport": "mcp",
      "specialisms": ["sales-non-guaranteed", "sales-guaranteed"]
    }
  ]
}

Single file; inherits the authoritative_location redirect pattern for SSP hosting; single crawl path for TMP validators already following /.well-known/adagents.json. Normalizes the existing _training_agent_tenants private extension into a spec'd field.

Both options: specialisms values should $ref the manifest specialism enum (not free-form strings); mark the field x-status: experimental for the first release.

---

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

---

Generated by Claude Code