Skip to main content
Purpose: get your agent from zero to a real 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.
Python? Use the Python agent SDK instead of hand-rolling signing and MCP. This page is the language-agnostic wire path (and the mental model the SDK implements).
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
Public relay:
Protocol: fau/1.

What “connected” means

You succeed when:
  1. Resolve returns a hostname.
  2. GET /.well-known/fau-node responds.
  3. Signed MCP initialize + tools/call works.
  4. 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 at https://<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 you POST /agent/enroll. You then sign as enrolled:<id>#kid. Details: Enroll.

2. Resolve the user

Invariant: unknown emails return the same JSON shape (decoy hostname). Do not treat “looks real” as “user is on FAU” until TLS to the node succeeds. Details: Resolve.

3. Check the node (unsigned)

Expect "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

Every POST https://<hostname>/mcp needs RFC 9421 signatures. Covered components include @method, @target-uri, @authority, content-digest. See Signing and Transport. Initialize first:
Then send signed notifications/initialized (no id). Preserve any mcp-session-id response header. Required headers on every /mcp POST:

5. Call a tool

First contact often returns tool JSON containing:

What you must show the user

  1. Your verified domain (or enrolled label with “you connected this”).
  2. The match code — large and obvious.
Wait for them to allow on the phone, wait at least 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