一个 blocklet 会公布四份发现文档。它们都是匿名 GET，都不需要先连上 /mcp。把 <host> 替换成该 blocklet 的 host。
server card 有三个路径返回同一份文档，所以端点页列出的行数多于文档数。那里列的授权端点属于另一个面 —— 它们是被这些文档点名的，不在这些文档之列。
| 路径 | 回答什么 |
|---|---|
/.well-known/mcp.json | 这个 MCP server 是什么、在哪里、哪些工具需要凭证 |
/.well-known/oauth-protected-resource | 哪个 authorization server 保护 /mcp |
/.well-known/oauth-authorization-server | 端点、grant 类型、PKCE 方法 |
/.well-known/api-catalog | 这个 host 上有哪些服务描述 |
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 是 false，因为连接和读取不需要凭证。tools 对象说明哪些工具名会改变这一点。
上面的示例来自一个未声明内容集合的 blocklet。声明了集合的 blocklet，会把 search_content、list_content 和 get_content 也列在 tools.anonymous 下。
server card 不属于 MCP 协议，因此 MCP 客户端在连接过程中不会读它。用它来检查一个 host、建立目录，或判断要不要连接 —— 不要把它当作触发授权的机制。触发授权的是 401 挑战，见授权客户端。
受保护资源
curl -s https://<host>/.well-known/oauth-protected-resource{
"resource": "https://<host>/mcp",
"authorization_servers": ["https://<host>"]
}这就是 WWW-Authenticate 挑战所指向的文档。它总是把同一个 host 指为自己的 authorization server。
Authorization server 元数据
端点与 grant 类型列在授权客户端。这份文档由 blocklet host 提供，但它所命名的端点由 connect service 实现，见端点。
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" }
]
}
]
}列出两个锚点：MCP 端点，以及给不说 MCP 的客户端用的 AFS RPC 端点。两者指向同一份服务描述。
已知漂移
server card 的 authentication.note 把 DID-Connect session 说成认证写入的方式。通过 authorization server 取得的 bearer token 同样被接受，而且 schemes 字段已经写了 bearer。请以 schemes 和访问分档为准，把这段散文说明当作不完整的表述。