MCP Integration

Anona exposes memory over the Model Context Protocol, so an MCP-capable assistant can record and recall context directly.

Tools

Tool	What it does	Transport
`record`	Stores a memory in a space. Optional `user_id` / `agent_id` / `session_id` scope it.	Both
`retrieve`	Semantically searches memories in a space. Pass the same scope keys to see only that user’s memories.	Both
`list_spaces`	Lists the available memory spaces.	Both
`reason`	Synthesizes an answer from accumulated memories.	Both
`get_profile`	Reads a space’s standing profile and the memory models it keeps current.	Remote
`get_model`	Reads one memory model, the space’s current answer to a standing question, such as how this user prefers to be communicated with.	Remote
`get_user_profile`	Reads what a space knows about one end user, by their `user_id`.	Remote

Per-tool failures, such as a denied space or exhausted credits, come back as structured tool errors rather than broken connections. The MCP session stays alive.

Choosing a transport

	Local (stdio)	Remote (Streamable HTTP)
Runs	On your machine, via `uvx`	On the hosted gateway
Install	Python SDK required	Nothing to install
Auth	`ANONA_API_KEY` environment variable	API key header, or OAuth sign-in
Best for	Local development, scripted setups	Everyday use, and teams

Remote (recommended)
Local (stdio)

Connect directly to the hosted gateway. There is no local process to run.

claude mcp add --transport http anona https://memory.anonalabs.com/mcp \
  --header "Authorization: Bearer anona_live_YOUR_KEY"

Authentication uses the same API key as the REST API, so there is no separate credential to manage.Hermes Agent: add a mcp_servers entry to ~/.hermes/config.yaml:

mcp_servers:
  anona:
    url: "https://memory.anonalabs.com/mcp"
    headers:
      Authorization: "Bearer ${env:ANONA_API_KEY}"

Hermes also supports auth: oauth in place of a static header, the same OAuth flow described below for Claude Code.Connecting without a key. Leave off --header and an OAuth-capable client such as Claude Code, Claude Desktop, or Cursor signs you in instead.

claude mcp add --transport http anona-oauth https://memory.anonalabs.com/mcp

add does not open a browser, and that is expected. It only writes the server to your config file. OAuth sign-in does not run until the client actually connects, which happens at session start or when you run /mcp. After add you are not signed in yet.

Your organization needs at least one API key for this path to work today. Signing in with OAuth authenticates you, but the gateway still reaches the memory service using one of your organization’s existing keys, so an organization that has never created one gets 403 No active API key for this organization on its first tool call. If you signed up with Google and have not made a key yet, create one in the dashboard once. You do not have to put it in your MCP config, it only has to exist.

To trigger sign-in:

Run /mcp in Claude Code, or restart it. This connects to the server for the first time.
Your browser opens the Anona consent screen. Sign in with email and password, or with Google, GitHub, or Microsoft, whichever your account uses.
Approve, and the client stores the token. No API key ever touches its config.

Manage or revoke authorized apps at any time from the dashboard, under MCP → Connected apps. Tokens refresh automatically, and revoking cuts an app’s access immediately.

Opening https://memory.anonalabs.com/mcp in a browser returns Method Not Allowed. That endpoint speaks the MCP protocol over POST and is not a web page. Point an MCP client at it rather than visiting it.

Runs on your machine via uvx, and ships with the Python SDK.

uvx --from 'anona[mcp]' anona-mcp

Set the environment before starting your client:

export ANONA_API_KEY="anona_live_YOUR_KEY"
export ANONA_SPACE_ID="customer-support-bot"   # optional, scopes the server to one space

Or install the extra explicitly:

pip install "anona[mcp]"

Register with Claude Code:

claude mcp add --transport stdio anona -- uvx --from 'anona[mcp]' anona-mcp

Set ANONA_API_KEY, and optionally ANONA_SPACE_ID, in your shell environment before starting Claude Code.

Things worth knowing

Behavior	Detail
Tools only load at session start.	Adding or changing an MCP server mid-session will not expose its tools until you restart the client.
Space scoping is optional.	Without `ANONA_SPACE_ID`, tools that need a space will ask you to name one, or operate across whichever spaces your API key can see.
Same quota, same billing.	MCP calls consume credits and count against your usage exactly as REST calls do.

Example session

Once registered, talk naturally:

Remember that the user prefers dark mode and uses VS Code.

What do we know about this user’s editor preferences?

Claude Code calls record and retrieve behind the scenes.

Serving several people through one MCP connection? Pass user_id on record and retrieve so each person’s memories stay separate inside the shared space. See Scoping.

Client setup guides

Claude Code

Get a key from the dashboard, under API keys.

claude mcp add --transport http anona https://memory.anonalabs.com/mcp \
  --header "Authorization: Bearer anona_live_YOUR_KEY"

Run /mcp in Claude Code, or restart it, to connect.
Try it: “Remember that I prefer dark mode and use VS Code.”

Hermes Agent

Get a key from the dashboard, under API keys.

Add to ~/.hermes/config.yaml:

mcp_servers:
  anona:
    url: "https://memory.anonalabs.com/mcp"
    headers:
      Authorization: "Bearer ${env:ANONA_API_KEY}"

Set ANONA_API_KEY in ~/.hermes/.env or your shell environment.
If Hermes is already running, it auto-reloads the config within 30s, or run /reload-mcp in-session. Otherwise the server picks it up on next start.
Try it: “Remember that I prefer dark mode and use VS Code.”

Getting Started

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

SDKs & MCP

Integrations

Guides

Changelog

Tools

Choosing a transport

Things worth knowing

Example session

Client setup guides

Claude Code

Hermes Agent

Next steps

Python SDK

API overview

​Tools

​Choosing a transport

​Things worth knowing

​Example session

​Client setup guides

​Claude Code

​Hermes Agent

​Next steps

Python SDK

API overview

Tools

Choosing a transport

Things worth knowing

Example session

Client setup guides

Claude Code

Hermes Agent

Next steps