以下路径都相对于一个 blocklet host。把 <host> 替换成该 host。
数据面
| 路径 | 方法 | 凭证 | 说明 |
|---|---|---|---|
/mcp | POST | 可选 | streamable HTTP 上的 MCP。无状态：不下发 mcp-session-id，其他方法之前不需要先 initialize |
/api/afs/rpc | POST | 可选 | 给不说 MCP 的客户端使用的 AFS 操作 |
对 /mcp 的匿名请求可以使用握手方法、list 方法和读工具。其余一律返回 401，并在 WWW-Authenticate 头中给出 protected-resource 文档的地址。
发现面
四份都是 GET，都不需要凭证。
| 路径 | 提供什么 |
|---|---|
/.well-known/mcp.json | Server card：名称、URL、传输方式、认证摘要、工具划分 |
/.well-known/mcp | 同一份文档 |
/.well-known/mcp/server-card.json | 同一份文档 |
/.well-known/oauth-protected-resource | RFC 9728 受保护资源元数据 |
/.well-known/oauth-authorization-server | RFC 8414 authorization server 元数据 |
/.well-known/api-catalog | RFC 9727 linkset，列出本 host 上的服务描述 |
三个 server-card 路径是同一份文档的别名。你的客户端已经在找哪个就用哪个。
授权面
这些路径由 authorization server 元数据命名，由跑在同一个 host 背后的 connect service 提供。对 agent 来说，它们就是 blocklet host 上的普通路径。
| 路径 | 方法 | 凭证 | 用途 |
|---|---|---|---|
/.well-known/service/oauth/register | POST | 无 | 动态客户端注册。返回 client_id 并回显注册内容 |
/.well-known/service/oauth/authorize | GET、POST | 用户会话 | 授权请求与同意 |
/.well-known/service/oauth/token | POST | PKCE verifier | 换取 token 与刷新 |
/.well-known/service/oauth/device_authorization | POST | 无 | device flow，给无法打开浏览器的客户端 |
/.well-known/service/gen-access-key | GET | 用户会话 | 在用户会话中完成授权的浏览器页面 |
公布的 grant 类型：authorization_code、refresh_token 和 device code grant。PKCE 方法：S256。token 端点认证方式：none。
响应形状
| 请求 | 结果 |
|---|---|
POST /mcp tools/list，匿名，不先 initialize | 200；八个工具，或在 blocklet 声明了内容集合时为十一个 |
POST /mcp tools/call afs_write，匿名 | 401，正文 {"error":"Unauthorized"}，头部 www-authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource" |
GET /.well-known/oauth-protected-resource | 200；resource 为 https://<host>/mcp，authorization_servers 为 ["https://<host>"] |
GET /.well-known/oauth-authorization-server | 200；issuer 等于该 host |
POST /.well-known/service/oauth/register | 201；client_id 加上回显的注册字段 |
POST /.well-known/service/oauth/device_authorization | 200；device_code、user_code、verification_uri、verification_uri_complete、expires_in: 300、interval: 5 |
POST /.well-known/service/oauth/token（device grant，已批准） | 200；{"access_token":"blocklet-…","token_type":"Bearer","scope":"mcp"} —— 没有 expires_in，没有 refresh_token |
POST /mcp tools/call afs_write，owner 凭证，未声明路径 | 200，带 isError 与 AFS_FORBIDDEN |
全部失败形状及其区分方式，见错误。
文本面
| 路径 | 方法 | 凭证 | 提供什么 |
|---|---|---|---|
/llms.txt | GET | 无 | 指针文档，列出 agent 界面，并按集合分节 |
/llms-<collection>.txt | GET | 无 | 单个集合的索引。集合未声明 llms face 时为 404 |
/llms-<collection>-full.txt | GET | 无 | 单个集合的全文 |
/llms-full.txt | GET | 无 | 所有集合的全文 |
见 llms.txt。
兼容路径
| 路径 | 说明 |
|---|---|
arc mcp | 把 stdio 桥接到本地运行中的 daemon，给无法使用 HTTP 的客户端。见 arc mcp |