All paths below are relative to a blocklet host. Replace <host> with that host.
Data plane
| Path | Method | Credential | Notes |
|---|---|---|---|
/mcp | POST | Optional | MCP over streamable HTTP. Stateless: no mcp-session-id is issued, and initialize is not required before other methods |
/api/afs/rpc | POST | Optional | AFS operations for clients that do not speak MCP |
Anonymous requests to /mcp may use the handshake methods, the list methods, and the read tools. Anything else returns 401 with a WWW-Authenticate header naming the protected-resource document.
Discovery
All four are GET and none requires a credential.
| Path | Serves |
|---|---|
/.well-known/mcp.json | Server card: name, URL, transport, authentication summary, tool split |
/.well-known/mcp | Same document |
/.well-known/mcp/server-card.json | Same document |
/.well-known/oauth-protected-resource | RFC 9728 protected-resource metadata |
/.well-known/oauth-authorization-server | RFC 8414 authorization server metadata |
/.well-known/api-catalog | RFC 9727 linkset naming the service descriptions on this host |
The three server-card paths are aliases for one document. Use whichever your client already looks for.
Authorization
These paths are named by the authorization server metadata and served by the connect service running behind the same host. To an agent they are ordinary paths on the blocklet host.
| Path | Method | Credential | Purpose |
|---|---|---|---|
/.well-known/service/oauth/register | POST | None | Dynamic client registration. Returns a client_id and echoes the registration |
/.well-known/service/oauth/authorize | GET, POST | User session | Authorization request and consent |
/.well-known/service/oauth/token | POST | PKCE verifier | Token exchange and refresh |
/.well-known/service/oauth/device_authorization | POST | None | Device flow, for clients that cannot open a browser |
/.well-known/service/gen-access-key | GET | User session | Browser page that completes an authorization in a user's session |
Grant types advertised: authorization_code, refresh_token, and the device code grant. PKCE method: S256. Token endpoint authentication: none.
Response shapes
| Request | Result |
|---|---|
POST /mcp tools/list, anonymous, no initialize | 200; eight tools, or eleven when the blocklet declares content collections |
POST /mcp tools/call afs_write, anonymous | 401, body {"error":"Unauthorized"}, header www-authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource" |
GET /.well-known/oauth-protected-resource | 200; resource is https://<host>/mcp, authorization_servers is ["https://<host>"] |
GET /.well-known/oauth-authorization-server | 200; issuer equals the host |
POST /.well-known/service/oauth/register | 201; client_id plus the echoed registration fields |
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, approved) | 200; {"access_token":"blocklet-…","token_type":"Bearer","scope":"mcp"}, with no expires_in and no refresh_token |
POST /mcp tools/call afs_write, owner credential, undeclared path | 200 with isError and AFS_FORBIDDEN |
For every failure shape and how to tell them apart, see Errors.
Text surfaces
| Path | Method | Credential | Serves |
|---|---|---|---|
/llms.txt | GET | None | Pointer document naming the agent surfaces, plus a section per collection |
/llms-<collection>.txt | GET | None | Index for one collection. 404 when the collection declared no llms face |
/llms-<collection>-full.txt | GET | None | Full text for one collection |
/llms-full.txt | GET | None | Full text for every collection |
See llms.txt.
Compatibility path
| Path | Notes |
|---|---|
arc mcp | Bridges stdio to a running local daemon, for clients that cannot use HTTP. See arc mcp |