> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Reach first successful contact — resolve a user, open MCP, call a tool, handle approval.

**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.

> [!TIP]
>
> **Python?** Use the [Python agent SDK](https://docs.fau.run/developer/agents/python-sdk.md) 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](https://docs.fau.run/developer/connect/enroll.md) (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:

```
https://relay.fau.run
```

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`:

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

`domain` must match the host. No redirects on the node’s fetch. Details:
[Identity](https://docs.fau.run/developer/connect/identity.md).

### 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](https://docs.fau.run/developer/connect/enroll.md).

## 2. Resolve the user

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

```json theme={null}
{
  "relay": "relay.fau.run",
  "hostname": "n….relay.fau.run",
  "box_pubkey": "…",
  "queue_endpoint": "https://relay.fau.run/v1/queue"
}
```

**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](https://docs.fau.run/developer/connect/resolve.md).

## 3. Check the node (unsigned)

```bash theme={null}
curl -sS "https://<hostname>/.well-known/fau-node"
```

Expect `"protocol":"fau/1"` and a tool list. If TLS fails, the Mac may be offline —
use the [offline queue](https://docs.fau.run/developer/connect/offline-queue.md) 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](https://docs.fau.run/developer/connect/signing.md) and [Transport](https://docs.fau.run/developer/connect/transport.md).

**Initialize** first:

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

Then send signed `notifications/initialized` (no `id`). Preserve any `mcp-session-id`
response header.

Required headers on every `/mcp` POST:

```http theme={null}
Content-Type: application/json
Accept: application/json, text/event-stream
Content-Digest: …
Signature-Input: …
Signature: …
```

## 5. Call a tool

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

First contact often returns tool JSON containing:

```json theme={null}
{
  "error": "approval_required",
  "approval_id": "ap_…",
  "match_code": "47",
  "retry_after_seconds": 5
}
```

### 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](https://docs.fau.run/developer/tools/approvals.md).

## 6. Prefer narrow tools

Order of preference: structured tools → `ask` → `get_excerpt` only when raw text is
required. Catalog: [Tools](https://docs.fau.run/developer/tools/overview.md).

## Verify success

| Check | Expected |
| - | - |
| Resolve | HTTP 200 with `hostname` |
| Well-known | HTTP 200, `protocol` = `fau/1` |
| `initialize` | MCP result, not auth error |
| After allow + retry | Answer text / structured JSON; audit on their node |

## If something fails

| Symptom | Likely cause | Next |
| - | - | - |
| TLS never completes | Offline node or decoy | Retry later or offline queue |
| `401` / bad signature | Wrong keyid, skew, nonce reuse | [Signing](https://docs.fau.run/developer/connect/signing.md) |
| Permanent `approval_required` | User denied / expired | New request; do not spin |
| `429` | Rate limited | Back off |

## Next

* [Approvals](https://docs.fau.run/developer/tools/approvals.md) — wait headers, retry rules
* [Offline queue](https://docs.fau.run/developer/connect/offline-queue.md) — Mac asleep
* [Integration checklist](https://docs.fau.run/developer/reference/checklist.md) — before production traffic


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.