tools/call against a user’s node on
the public relay.
Audience: engineers integrating an assistant in any language. Assumes you can
make HTTPS requests and hold an Ed25519 keypair.
Time to first contact: about an afternoon if you already have keys; longer if you
must publish /.well-known/fau-agent.
Prerequisites
- An HTTPS-reachable agent domain that can serve JSON, or willingness to use claim-code enrollment (Lane B)
- A test user whose FAU Mac node is online (or use offline queue later)
- Ability to show the user a match code in your UI
fau/1.
What “connected” means
You succeed when:- Resolve returns a hostname.
GET /.well-known/fau-noderesponds.- Signed MCP
initialize+tools/callworks. - If you get
approval_required, you show domain + match code; after the user allows on their phone, a retry returns an answer.
1. Establish agent identity
Option A — publisher domain (preferred)
Host athttps://<your-domain>/.well-known/fau-agent:
domain must match the host. No redirects on the node’s fetch. Details:
Identity.
Option B — claim code
If you cannot host JWKS yet, the user creates a claim in FAU and youPOST /agent/enroll. You then sign as enrolled:<id>#kid. Details:
Enroll.
2. Resolve the user
3. Check the node (unsigned)
"protocol":"fau/1" and a tool list. If TLS fails, the Mac may be offline —
use the offline queue or retry later. Do not conclude the
user does not exist.
4. Open a signed MCP session
EveryPOST https://<hostname>/mcp needs RFC 9421 signatures. Covered components
include @method, @target-uri, @authority, content-digest. See
Signing and Transport.
Initialize first:
notifications/initialized (no id). Preserve any mcp-session-id
response header.
Required headers on every /mcp POST:
5. Call a tool
What you must show the user
- Your verified domain (or enrolled label with “you connected this”).
- The match code — large and obvious.
retry_after_seconds, then
retry the same tools/call (same arguments). For most tools you do not send
approval_id on retry; the node now has a grant. Excerpt/send retries differ — see
Approvals.
6. Prefer narrow tools
Order of preference: structured tools →ask → get_excerpt only when raw text is
required. Catalog: Tools.
Verify success
If something fails
Next
- Approvals — wait headers, retry rules
- Offline queue — Mac asleep
- Integration checklist — before production traffic