ADR-001: Discovery Mechanism

Status: Accepted Date: 2026-03-20

Context

An agent visiting a website or calling an API needs to find the trstd verification endpoint. The discovery mechanism determines how agents locate trust data for any given service. This is the first interaction point — if discovery fails, the protocol is invisible.

The mechanism must work across different hosting environments: dedicated servers, shared hosting, CDNs, static sites, and API-only services.

Agents operating are becoming more MCP-compliant. Shopping agents, price comparison tools, and purchasing assistants use MCP to interact with services. An MCP-based discovery mechanism reaches the audience that needs trust signals most.

Decision

Current: HTML `<link>` Tag (Direct HTTP)

The current discovery mechanism is an HTML <link> tag pointing directly to the HTTP verify endpoint:

<link rel="trstd-protocol"
      href="https://trust-authority.example.org/v1/entities/{entityId}/trust-signals"
      type="application/json"
      title="Trust Verification">

Service providers embed this tag in the <head> of their HTML pages. Agents that know the #trstd <protocol> scan for <link rel="trstd-protocol">, extract the verify endpoint URL (which already contains the entityId as its final path segment), append ?url=...&context=..., and make a single HTTP GET. No MCP server, no tool discovery roundtrips, no additional infrastructure.

Agents MUST build the url parameter from the actual page URL they are visiting — not from any value in the link tag.

The link tag provides a minimal discovery surface: the verify endpoint URL and an entityId. It does not expose extension parameters, provider metadata, or entity matching. The pre-computed entityId per page replaces client-side entity matching.

Why a direct link tag instead of MCP today:

The choice follows from one premise: the current spec targets agents that already know the #trstd <protocol>. An agent that knows the protocol knows the API contract. It does not need tool discovery — it needs one page-specific value: the entityId. A link tag delivers that in a single HTML element. The agent appends the page URL, makes one HTTP GET, and receives signed trust signals.

MCP adds value only when the agent does not know the protocol and must discover the tool generically. But no finalized standard exists for how an agent visiting a web page discovers an MCP server on that page. The proposals (SEP-1649, SEP-1960, IETF mcp: URI scheme) are unmerged. A custom rel value like rel="mcp-server" would be equally invisible to agents as rel="trstd-protocol" — both require protocol-specific knowledge. Since protocol awareness is required either way, the simpler mechanism wins: one tag, one HTTP call, no MCP server infrastructure, no additional roundtrips.

MCP and WebMCP become the planned story for reaching protocol-unaware agents once standard discovery mechanisms exist.

Planned: MCP, WebMCP, and Well-Known Manifest (Deferred)

A future revision adds discovery paths for agents that do not know the #trstd <protocol>:

MCP server — the trust authority operates an MCP server exposing a check_trust tool. Agents that support MCP discover the tool via list_tools and invoke it. Requires a standard MCP discovery mechanism (currently no finalized standard exists).
WebMCP — service providers register check_trust via the W3C WebMCP imperative API (navigator.modelContext.registerTool) or declarative <form> elements. Any WebMCP-compliant agent discovers the tool without trstd-specific knowledge.
Well-known manifest — a self-describing manifest at /.well-known/trstd.json (RFC 8615) adds provider metadata, multi-entity matching, extension parameters, and a VerifyEndpoint capability for HTTP agents alongside an McpServer capability. When introduced, agents check .well-known first and fall back to the <link> tag.

See the MCP Discovery concept for the MCP design rationale and the roadmap for status.

Manifest format (planned)

The /.well-known/trstd.json file is a self-describing manifest that combines provider identity, entity scoping, and capability descriptions. It is deferred — see the roadmap. All JSON object keys use camelCase.

{
  "$schema": "https://cdn.example.org/schemas/trstd-protocol/v1/manifest.json",
  "@context": "https://cdn.example.org/schemas/trstd-protocol/v1",
  "@type": "VerificationProvider",
  "version": "1.0.0",
  "name": "Trusted Shops SE",
  "description": "Website verification discovery endpoint for Trusted Shops SE",
  "entities": [
    {
      "entityId": "09b765de-08ed-4b95-bd38-35d6d9ed9c19",
      "host": "www.example.org",
      "pathPrefixes": ["/"]
    },
    {
      "entityId": "d6f2fdf4-f829-4ce6-a1cc-e2bd957709db",
      "host": "www.example.org",
      "pathPrefixes": ["/de"]
    }
  ],
  "capabilities": [
    {
      "id": "verify",
      "type": "VerifyEndpoint",
      "endpoint": "https://trust-authority.example.org/v1/entities/{entityId}/trust-signals",
      "method": "GET",
      "description": "Retrieve trust signals for an entity",
      "extensionParameters": [
        {
          "name": "locale",
          "in": "query",
          "type": "string",
          "description": "Preferred locale for localized signal data (BCP 47)",
          "required": false
        }
      ]
    },
    {
      "id": "mcp",
      "type": "McpServer",
      "endpoint": "https://trust-authority.example.org/v1/mcp",
      "method": "POST",
      "description": "MCP server for trust verification tools"
    }
  ]
}

Provider metadata

$schema — URL to the JSON Schema for manifest validation
@context — JSON-LD context URL for semantic interoperability
@type — Fixed string "VerificationProvider"
version — Protocol version this manifest targets
name — Display name of the trust authority
description — Brief description of this verification provider

Entities

Each entity represents a company, person, or organization whose trustworthiness the authority attests to, scoped to a hostname and path prefixes. Websites with multiple storefronts, regional variants, or separate services use multiple entities. No two entities with the same host may share an identical pathPrefixes entry — duplicates make the manifest invalid.

entityId — Opaque identifier for this entity (issued by the trust authority; format is authority-defined)
host — The hostname this entity applies to (agents MUST validate this matches the serving domain)
pathPrefixes — Array of URL path prefixes this entity covers; agents match the longest prefix

Capabilities

Each capability describes an API endpoint the trust authority supports. The verify capability is required. The mcp capability is optional and points to the trust authority's MCP server for tool-calling agents. Additional capability types may be added in a future revision.

id — Capability identifier (e.g., "verify")
type — Capability type (e.g., "VerifyEndpoint")
endpoint — The full URL of the API endpoint
method — HTTP method. The verify capability MUST use GET. The mcp capability MUST use POST. Future capability types MAY use other methods.
description — Human-readable description
extensionParameters — Optional array of provider-specific parameters beyond those defined by the spec. Extension parameters MUST NOT be required — agents that do not understand an extension parameter must still be able to call the endpoint

Entity matching algorithm

When an agent visits a URL, it matches entities as follows:

Filter entities where host matches the URL's hostname exactly. The host field must be an exact hostname — subdomain wildcards (e.g., *.example.org) are forbidden.
Among matching entities, find all entries where the URL path matches a value in pathPrefixes. A prefix matches if the URL path equals the prefix or the next character in the path is /. The root prefix / matches all paths.
Select the entity with the longest matching prefix (e.g., /de wins over / for the path /de/products/123, but /de does not match /demo)
If no entity matches, the site is not covered by this manifest

Matching considers only hostname and path. Query strings and fragments are ignored.

Options Considered

A. .well-known/trstd.json only. Established pattern; no HTML parsing needed; works for non-HTML services. Requires server-side file placement, which is impractical on some shared hosting platforms and CDNs.

B. HTML meta tag only. Easy for website owners to add via CMS or template. Only works for HTML pages — excludes APIs and MCP services. Requires HTML parsing. Superseded by MCP link tag — see below.

C. HTTP Link header only. Works for any HTTP response (APIs, documents, HTML). Less visible to site operators. Requires server or proxy configuration access. Rejected — adds a third discovery path without sufficient benefit.

D. Combined approach with meta tag (original). .well-known as primary with HTML <meta name="trstd-protocol"> as fallback. Superseded by option E.

E. Direct HTTP link tag today, MCP/WebMCP/manifest planned (chosen). The current spec ships a <link rel="trstd-protocol"> tag pointing directly to the HTTP verify endpoint — the simplest path for trstd-aware agents. A future revision adds MCP, WebMCP, and the .well-known manifest to reach agents that do not know the protocol.

Consequences

Today

Agents implement a single discovery step: scan HTML <head> for <link rel="trstd-protocol">
One HTTP GET per verification — no MCP roundtrips, no additional infrastructure
Low integration bar for service providers — one HTML tag per page
No provider metadata, extension parameters, or multi-entity matching today; the entityId is pre-computed per page
Only trstd-aware agents benefit; agents that do not know the protocol have no discovery path
Testing must cover link tag scanning, endpoint URL extraction, and entityId pass-through

Planned

MCP and WebMCP extend reach to agents that do not know the #trstd <protocol>
The .well-known manifest adds provider metadata, multi-entity matching, and extension parameters
The capabilities array is extensible for future protocol versions without changing the manifest structure
Testing must additionally cover MCP server connectivity, WebMCP tool registration, manifest parsing, and entity matching

References

RFC 8615 — Well-Known URIs
context/related-work.md — Survey of discovery patterns
roadmap/mcp-discovery.md — Design rationale for MCP discovery replacing the meta tag

Context​

Decision​

Current: HTML <link> Tag (Direct HTTP)​

Planned: MCP, WebMCP, and Well-Known Manifest (Deferred)​

Manifest format (planned)​

Provider metadata​

Entities​

Capabilities​

Entity matching algorithm​

Options Considered​

Consequences​

Today​

Planned​

References​