Quickstart

Assumes the public relay at https://relay.fau.run and a user whose Mac node is registered.

1. Publish your agent keys

Host this JSON at https://<your-domain>/.well-known/fau-agent over HTTPS (no redirects for the node’s fetch):

{
  "domain": "assistant.example",
  "keys": [
    {
      "kid": "k1",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url of raw 32-byte Ed25519 public key>"
    }
  ]
}

domain must match the host that serves the document. See Identity.

2. Resolve the user

curl -sS https://relay.fau.run/v1/resolve \
  -H 'content-type: application/json' \
  -d '{"address":"user@gmail.com"}'

{
  "relay": "relay.fau.run",
  "hostname": "n….relay.fau.run",
  "box_pubkey": "…",
  "queue_endpoint": "https://relay.fau.run/v1/queue"
}

Treat unknown users the same as offline ones — the JSON shape is identical for decoys. See Resolve.

3. Check the node (unsigned)

curl -sS "https://<hostname>/.well-known/fau-node"

{
  "protocol": "fau/1",
  "node": "<hostname>",
  "auth": "rfc9421+capability",
  "tools": ["ask", "get_upcoming_travel", "…"],
  "served_at": 1760000000
}

This GET is not signed. If TLS fails, use the offline queue or retry later — do not treat that as “user does not exist.”

4. Open an MCP session (signed)

Every POST https://<hostname>/mcp must include RFC 9421 headers (Signing) plus:

Content-Type: application/json
Accept: application/json, text/event-stream

Initialize first:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  }
}

Then send notifications/initialized (signed, no id). Preserve any mcp-session-id response header on later calls. See Transport.

5. Call a tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": { "question": "When is my next flight?" }
  }
}

First contact usually returns tool JSON with "error":"approval_required", a match_code, and an approval_id. Show the verified domain and match code to the user, wait for phone approval, then retry the same tools/call (same args). You normally do not get a capability token back from /mcp. After approval the node stores a grant for your domain; retry signed without inventing a Bearer token. See Approvals.

6. Prefer narrow tools

Structured tools → ask → get_excerpt only when raw text is explicitly needed. Catalog: Tools.

Start here

Connect

Call tools

Reference

1. Publish your agent keys

2. Resolve the user

3. Check the node (unsigned)

4. Open an MCP session (signed)

5. Call a tool

6. Prefer narrow tools

​1. Publish your agent keys

​2. Resolve the user

​3. Check the node (unsigned)

​4. Open an MCP session (signed)

​5. Call a tool

​6. Prefer narrow tools

1. Publish your agent keys

2. Resolve the user

3. Check the node (unsigned)

4. Open an MCP session (signed)

5. Call a tool

6. Prefer narrow tools