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

# Agent Self-Onboarding

> Let a coding agent set up Anona Memory from the terminal. One browser approval from you, no dashboard tour.

## What this is

A coding agent can connect itself to Anona Memory without you navigating the
dashboard beyond one approval screen. You approve the connection once, in a
browser. You never copy an API key, and never paste a password.

Which route it takes depends on your client, and
[The four ways to connect](#the-four-ways-to-connect) below is the single answer
to that. The rest of this page is the native OAuth route in detail.

## The one thing you do

A browser window opens. You sign in with Google. You see the name of the client
that is asking for access, and you press Approve. That approval is the whole
security model, so read the client name before you press it.

## The flow

```
agent:  POST /oauth/register  {redirect_uris:["http://localhost:PORT/cb"]}
agent:  print .../oauth/authorize?client_id=…&code_challenge=…  then wait
human:  opens it
        -> /login?return_to=/consent?req=…
        -> Continue with Google
        -> Clerk -> POST /auth/social creates org + project + quota,
           email_verified=true
        -> /consent?req=…  -> reads client name -> Approve
agent:  code -> POST /oauth/token -> mcp_access token (+ refresh)
agent:  record / retrieve / reason / list_spaces / get_profile /
        get_model / get_user_profile
```

One human action. No inbox trip, because Clerk verified the address. No
password anywhere. No dashboard navigation beyond the consent screen itself.

## The four ways to connect

This is the one table to read; every other page links here rather than
restating it. **An API key is not required to connect over MCP** — two of these
paths need no key at all, and a third needs no account. A key is required only
to call the REST API or an SDK directly.

| Path | What it needs | Which clients | Account |
| - | - | - | - |
| **A. Native MCP OAuth** | a client that implements OAuth 2.1 and can drive the browser hop itself | **Claude Code** today, and nothing else verified (per-client status in tab A below) | Created for you on the approval screen |
| **B. `anona login` + `anona mcp`** | pip `anona` 0.19.0+ or npm `@anona-labs/memory` 0.16.0+, and a client that can launch a **stdio** server | any such client — Codex, Kimi, Cursor, OpenCode, and Claude Code too | Created for you on the approval screen |
| **C. Temporary profile** | pip `anona` 0.19.0+ or npm 0.16.0+ | any stdio client; and with pip 0.20.0+, no MCP client at all | **None.** 1,000 credits, 72 hours, claimable later |
| **D. API key** | a key minted in the dashboard under **API keys** | any MCP client, over an `Authorization` header | Yours already |

Paths A, B and C all end with the same MCP tools. They differ only in who does
the OAuth dance: your client (A), the CLI (B), or nobody (C).

**The credential paths A and B mint is MCP-scoped, and the REST API refuses
it** — see [Limits](#limits). For REST or an SDK you need either an API key
(path D) or a temporary profile's token (path C), which does work wherever a key
does. This is also why `anona record` / `retrieve` / `reason` run on a temporary
profile and refuse on a signed-in account.

### Setup per path

**A. Native MCP OAuth**

```bash theme={null}
claude mcp add --transport http anona-oauth https://memory.anonalabs.com/mcp
```

That one command is the agent's whole job: it drives discovery, client
registration, the browser hop and the token exchange natively. No API key, no
header, nothing else to configure. The rest of this page describes this path.

| Client | Status |
| - | - |
| Claude Code | Flow verified end to end with a conforming OAuth client (see the note below); Claude Code's own client not separately exercised |
| Codex | Not yet verified completing the OAuth flow — use path B |
| Kimi | Not yet verified completing the OAuth flow — use path B |

**B. anona login**

```bash theme={null}
pip install -U anona        # or: npm install -g @anona-labs/memory
anona login                 # one browser approval, before any client starts
claude mcp add anona -- anona mcp   # Claude Code; other clients below
```

`anona login` does the approval up front, so the client has nothing left to
authenticate: no `/mcp` step and no interactive picker. The last line is Claude
Code's spelling; any client that can launch a stdio server takes the same
`anona mcp` command, for example `codex mcp add anona -- anona mcp`,
`gemini mcp add -s user anona anona mcp` or `opencode mcp add anona -- anona mcp`.
Goose, Cursor and the rest are in [the per-client table](https://docs.memory.anonalabs.com/agents/onboarding-prompt.md#2-start-a-temporary-profile). See [the anona CLI](https://docs.memory.anonalabs.com/cli/overview.md).

**C. Temporary profile**

```bash theme={null}
anona start                 # no account, no email address
claude mcp add anona -- anona mcp   # Claude Code; other clients below
```

A memory workspace nobody owns, with 1,000 credits and 72 hours to live. A human
claims it later with `anona login`, which keeps everything it holds. With pip
`anona` 0.20.0 or later it also answers `anona record`, `anona retrieve` and
`anona reason` directly, so it is the only path that works with no MCP client at
all. Registering the server in any other client is the same as in path B. See [Temporary profiles](https://docs.memory.anonalabs.com/agents/temp-profiles.md).

**D. API key**

Mint a key in the dashboard under **API keys**, then follow the header-based
setup in [MCP Integration](https://docs.memory.anonalabs.com/mcp-integration.md). This is also the credential the
REST API and both SDKs take — see [Authentication](https://docs.memory.anonalabs.com/api-reference/authentication.md).

> [!NOTE]
>
> **The flow itself is proven.** On 2026-10-09 a conforming OAuth 2.1 client ran
> it against production start to finish: protected-resource discovery, the
> `WWW-Authenticate` hint on an unauthenticated call, authorization-server
> metadata, RFC 7591 dynamic registration, PKCE S256 with a loopback redirect on
> an ephemeral port, a human approving on the consent screen, the code exchange,
> a `tools/call` that returned real spaces, and a refresh that rotated the token.
>
> What that does not prove is any particular client's own implementation. The
> table above says which ones have been exercised.

> [!WARNING]
>
> **Only a client that implements OAuth 2.1 natively can complete *this* flow**,
> and today that means Claude Code. It is not the only keyless path, though: on
> any other client, `anona login` + `anona mcp` (path B above) does the same
> approval from the command line and still needs no API key. Reach for a
> dashboard key only if you cannot run a command, or if you need the REST API.

## What you get

Once connected, the agent has the MCP tools: `record`, `retrieve`, `reason`,
`list_spaces`, `get_profile`, `get_model`, and `get_user_profile`. See
[MCP Integration](https://docs.memory.anonalabs.com/mcp-integration.md) for what each one does and how transports
differ.

## Limits

An OAuth credential minted this way is not an API key. It works over MCP, and
only over MCP. It does not work with the SDK or with raw HTTP calls to the REST
API. For those, mint a key from the dashboard (path D), or use a temporary
profile's token (path C), which the REST API does accept.

This is also why `anona record`, `anona retrieve` and `anona reason` never use
the MCP login: they call the REST API, and this credential is the one thing the
REST API will not take. They use an API key, the separate command-line login
that `anona login` also stores, or a temporary profile. See
[Sign in & credentials](https://docs.memory.anonalabs.com/cli/sign-in.md).

## Troubleshooting

**Nothing happened when the agent tried to use memory, and no browser opened.**
Adding the MCP server does not sign you in, and a failed tool call does not
start the flow. You have to begin it: run `/mcp` in Claude Code (or `/mcps` in
OpenCode), pick the Anona server, and authenticate. The browser opens from
there. An agent cannot do this for you; it is an interactive picker in your
own terminal.

**Your agent says Anona is connected, but it has no memory tools.** Adding the
MCP server does not load its tools into a session that is already running;
Claude Code reads its server list at startup. Restart Claude Code in the same
directory and ask again. The browser approval opens on the first memory call
after that, not when the server is added. If the server shows as disabled for
this project, run `/mcp` and enable it first.

**The approval link expired.** It is valid for 15 minutes. Start the flow again
from the beginning rather than retrying the dead link.

**You approved, and the first tool call still fails with "No active API key for
this organization."** The account was created and the approval worked; the
failure is on our side, not yours. A brand-new account holds no API key by
design, and the gateway needs a way to tell the engine which organization you
are without one. If you see this, the deployment you are talking to does not
have that configured yet. Report it rather than minting a key to work around
it. The workaround hides exactly the thing we need to know is broken.

**The agent says it is connected but no memory is stored.** Ask it to run
`retrieve` on something you know it recorded. An agent that treats your "I
approved it" as proof of connection will report success it has not verified;
a tool call that returns data is the only evidence that counts.

**Do not poll the login endpoint.** It allows 10 attempts per 5 minutes per
address, so a polling loop locks you out within a minute. Wait for the human to
act instead of retrying.

**Signed up with a password instead of Google, and the approval broke.** The
password path requires verifying your email address first, and starting that
detour interrupts the consent flow you had open. Verify your address, then
start the flow again from the beginning.

**A verification email cannot be resent.** If it expired before you clicked it,
sign up again with the same address rather than waiting for a second email.

**What the new-account response is telling you.** It names verifying your
address as the next step, and that is the only thing it actually requires.


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