Discovery surfaces

A blocklet publishes four discovery documents. All are anonymous GET requests and none requires a prior connection to /mcp. Replace <host> with the blocklet's host.

The server card is reachable at three paths that return the same document, so Endpoints lists more rows than there are documents. The authorization endpoints listed there are a different surface: they are named by these documents, not among them.

Server card

curl -s https://<host>/.well-known/mcp.json

{
  "name": "arc",
  "description": "AFS MCP server — agents discover published content via content tools and generic afs_* tools. Anonymous public read; authenticated writes via DID-Connect.",
  "url": "https://<host>/mcp",
  "transport": "streamable-http",
  "authentication": {
    "required": false,
    "schemes": ["bearer"],
    "oauth_protected_resource": "https://<host>/.well-known/oauth-protected-resource",
    "note": "Anonymous callers may tools/list and generic public-read afs_* tools; content tools (when declared without readRole:guest) and write/delete/exec require DID-Connect session."
  },
  "tools": {
    "anonymous": ["afs_read", "afs_list", "afs_search", "afs_stat", "afs_explain"],
    "authenticated": ["afs_write", "afs_delete", "afs_exec"]
  }
}

authentication.required is false because connecting and reading do not require a credential. The tools object states which names change that.

The example above is from a blocklet that declares no content collections. One that declares them lists search_content, list_content, and get_content under tools.anonymous as well.

The server card is not part of the MCP protocol, so MCP clients do not read it during a connection. Use it when you want to inspect a host, build a directory, or decide whether to connect at all, not as the mechanism that triggers authorization. That mechanism is the 401 challenge described in Authorize a client.

Protected resource

curl -s https://<host>/.well-known/oauth-protected-resource

{
  "resource": "https://<host>/mcp",
  "authorization_servers": ["https://<host>"]
}

This is the document the WWW-Authenticate challenge points at. It always names the same host as its own authorization server.

Authorization server metadata

Endpoints and grant types are listed in Authorize a client. The document is served from the blocklet host, but the endpoints it names are implemented by the connect service; see Endpoints.

API catalog

curl -s https://<host>/.well-known/api-catalog

{
  "linkset": [
    {
      "anchor": "https://<host>/mcp",
      "https://www.iana.org/assignments/link-relations/link-relations.xhtml#service-desc": [
        { "href": "https://<host>/.well-known/mcp.json" }
      ]
    },
    {
      "anchor": "https://<host>/api/afs/rpc",
      "https://www.iana.org/assignments/link-relations/link-relations.xhtml#service-desc": [
        { "href": "https://<host>/.well-known/mcp.json" }
      ]
    }
  ]
}

Two anchors are listed: the MCP endpoint, and the AFS RPC endpoint for clients that do not speak MCP. Both point at the same service description.

Known drift

The server card's authentication.note names a DID-Connect session as the way to authenticate writes. A bearer token obtained through the authorization server is also accepted, and the schemes field already says bearer. Treat schemes and the access tiers as authoritative and the prose note as incomplete.