> For the complete documentation index, see [llms.txt](https://docs.aboutcircles.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aboutcircles.com/miniapps/agentic-setup-for-circles.md).
# Agentic Setup for Circles
Build Circles dApps and miniapps using AI coding assistants grounded in always-fresh, version-aware Circles documentation.
This page is a practical guide for developers (and curious non-developers) who want to **vibe-code** on Circles using an AI assistant like Claude, Cursor, Windsurf, or VS Code Copilot. By wiring [Context7](https://context7.com/) into your editor, your AI agent pulls live snippets from the official Circles docs and SDK source, so it stops hallucinating outdated APIs and starts writing code that actually compiles.
***
### What is an agentic workflow?
An *agentic workflow* is one where you describe what you want in plain language and an AI agent does the work — reading docs, writing code, running it, fixing its own errors, and iterating. The catch: large language models are trained on data that's months or years old. Without a grounding layer, an agent confidently writes code that imports packages that don't exist or calls methods that were renamed in v2.
**Context7** fixes this. It's an open Model Context Protocol (MCP) server from Upstash that injects up-to-date, version-specific documentation directly into your AI assistant's context window the moment you ask about a library. The Circles team publishes two libraries on Context7:
* [**`aboutcircles/circles-docs`**](https://context7.com/aboutcircles/circles-docs) — the full developer documentation, including protocol concepts, configuration, and end-to-end examples.
* [**`aboutcircles/sdk`**](https://context7.com/aboutcircles/sdk) — the TypeScript SDK reference, including every package (`@aboutcircles/sdk`, `sdk-core`, `sdk-rpc`, `sdk-runner`, `sdk-pathfinder`, `sdk-profiles`, `sdk-transfers`) with code examples for almost every method.
Together, they give your agent everything it needs to build production-grade Circles apps without you having to copy-paste from docs.
***
### Why Context7 + Circles
Without Context7, ask Claude to "trust an address with the Circles SDK" and you'll get pre-2024 examples using `@circles-sdk/sdk` and ethers v6. With Context7, the same prompt produces the current `@aboutcircles/sdk` flow on Gnosis Chain (chainId 100) with viem, a `ContractRunner`, and the right `circlesConfig[100]`. The difference is hours of debugging vs. shipping.
The Circles SDK has a layered architecture — `Sdk` for high-level avatar work, `CirclesRpc` for read-only queries, `Core` for raw contract calls, `SafeContractRunner` / `SafeBrowserRunner` for Safe-based transactions, and a `Pathfinder` for multi-hop trust transfers. An AI assistant with the right docs in context can navigate all of these for you.
***
### Prerequisites
Before you start, make sure you have:
* **Node.js 18+** installed (`node --version`)
* An **MCP-compatible AI assistant**: Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code with an MCP extension
{% hint style="info" %}
*Optional (but recommended):* A free **Context7 API key** from [context7.com/dashboard](https://context7.com/dashboard) for higher rate limits
{% endhint %}
***
### Step 1: Install Context7 in your AI assistant
Pick the section that matches your editor. The configuration is essentially the same JSON across all clients — Context7 runs as a local MCP server via `npx`.
Cursor
* Open Cursor → **Settings** → **Cursor Settings** → **MCP** → **Add new global MCP server**.
* Or edit the config file directly:
* macOS / Linux: `~/.cursor/mcp.json`
* Windows: `%USERPROFILE%\.cursor\mcp.json`
1. Add the following:
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"],
"env": {
"CONTEXT7_API_KEY": "your-key-here-optional"
}
}
}
}
```
4. Restart Cursor.
Claude Desktop
* Open your config file:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
* Add the same `mcpServers` block as above.
1. Quit and reopen Claude Desktop.
Claude Code
Run a single command in your terminal:
```bash
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest --api-key YOUR_KEY
```
The `--scope user` flag registers Context7 globally so it's available in every Claude Code session. Verify with `/mcp` inside a session — you should see `context7` with a *connected* status.
VS Code
```json
"mcp.servers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
```
Add Context7 under `mcp.servers` in your `settings.json`:
Then reload the window (Ctrl/Cmd+Shift+P → "Developer: Reload Window").
#### Verify it's working
In any of the above clients, send a prompt like:
> *Using the latest @aboutcircles/sdk, write me a TypeScript snippet that registers a new human avatar on Gnosis Chain. use context7*
If Context7 is wired up correctly, the response will include the current packages (`@aboutcircles/sdk`, `@aboutcircles/sdk-core`, `@aboutcircles/sdk-runner`, viem) and use `circlesConfig[100]` and not the deprecated `@circles-sdk/sdk` packages.
***
### Step 2: Connect the Circles libraries
Context7 auto-discovers libraries when you reference them in a prompt, but for the most reliable results, point your agent directly at the Circles entries by name or ID.
#### Library IDs
| Library | Context7 ID | What's inside |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Circles documentation | `aboutcircles/circles-docs` | Protocol overview, getting-started guides, every SDK method with runnable TypeScript examples, RPC endpoints, REST API for profiles |
| Circles SDK v2 | `aboutcircles/sdk` | Per-package API reference: `Sdk`, `HumanAvatar`, `OrganisationAvatar`, `BaseGroupAvatar`, `CirclesRpc`, `Core`, `SafeContractRunner`, `Pathfinder`, `Profiles`, utility helpers |
#### Pin a library in a prompt
You can reference either entry with the slash syntax to make sure the agent looks at the right one:
```
Show me how to use sdk.register.asGroup to create a BaseGroup.
use library /aboutcircles/sdk
```
Or, for documentation-level questions like configuration and protocol concepts:
```
Explain how the Circles trust graph works and how pathfinding routes payments.
use library /aboutcircles/circles-docs
```
***
### Step 3: Add a project rule so you don't have to remember
Typing `use context7` every time gets old fast. Instead, add a one-time rule so your assistant **automatically** fetches Circles docs whenever it sees a relevant import or keyword.
#### For Cursor — `.cursorrules`
Create a `.cursorrules` file at the root of your project:
```
You are building on the Circles protocol (Gnosis Chain, chainId 100).
Whenever I ask about anything involving Circles, CRC, trust graphs, avatars,
pathfinding, group minting, or any package starting with @aboutcircles/,
automatically use the Context7 MCP server to fetch the latest docs from
the aboutcircles/sdk and aboutcircles/circles-docs libraries before writing code.
Never use the deprecated @circles-sdk/* packages. Always prefer:
- @aboutcircles/sdk for high-level avatar workflows
- @aboutcircles/sdk-rpc for read-only data queries
- @aboutcircles/sdk-core for raw contract calls
- @aboutcircles/sdk-runner for Safe transaction execution
- viem (not ethers) as the underlying client
Default to circlesConfig[100] from @aboutcircles/sdk-core for all Gnosis Chain config.
All token amounts are BigInt in atto-CRC (10^18 per CRC).
```
#### For Claude Code — `CLAUDE.md`
Drop the same content into a `CLAUDE.md` at your project root. Claude Code reads it automatically.
***
### Step 4: Vibe-code your first Circles Mini App
A **Circles miniapp** is a lightweight, focused dApp built with the Circles SDK, usually a single-page web app that reads/writes the Circles graph, mints or transfers CRC, manages a group, or exposes a small piece of functionality that complements Gnosis Wallet.
Here's a starter prompt you can give any Context7-equipped agent. It assumes the rules from Step 3 are already in place:
> Build a Vite + React + TypeScript miniapp that:
>
> 1. Connects a Safe via `SafeBrowserRunner` from `@aboutcircles/sdk-runner`
> 2. Shows the connected avatar's profile, total CRC balance, and a paginated trust list
> 3. Has a "Mint" button that calls `avatar.personalToken.mint()` only when `getMintableAmount()` returns > 0
> 4. Has a "Send" form that uses `avatar.transfer.advanced(recipient, amount, { useWrappedBalances: true })` and shows the pathfinder route before submitting
> 5. Subscribes to `avatar.events` and shows a live feed of incoming `CrcV2_TransferSingle` events
>
> Use Tailwind for styling. Keep state local with React hooks. Don't add a backend.
The agent will fetch the relevant SDK pages from Context7, scaffold the project, and write the code. You then iterate the same way: "the trust list pagination breaks at page 2", "wrap the mint button in a loading state", "add a copy-address button". Each follow-up triggers another targeted Context7 lookup.
{% hint style="info" %}
Use [Mini Apps SDK](https://www.npmjs.com/package/@aboutcircles/miniapp-sdk) for building Embedded Mini Apps.
{% endhint %}
***
### Querying the docs without an editor
If you're building a fully autonomous agent (no editor, no MCP), the Circles docs site itself ships an agent-friendly endpoint. Send an HTTP GET with an `ask` query parameter:
```
GET https://docs.aboutcircles.com/readme.md?ask=
```
The response is a structured answer plus relevant excerpts and source links from the documentation. This is useful for:
* Server-side agents that need to look up Circles concepts on demand
* CI pipelines that validate generated code against current API shapes
* Backfill workflows where you want to enrich code comments with doc links
Use it alongside Context7 when you need a quick natural-language answer rather than a code snippet.
***
### Bonus
You can also checkout this Agentic first MiniApps branch for builiding your own applications
{% embed url="" %}
### Troubleshooting
**The agent still suggests `@circles-sdk/*` packages.** The deprecation note is on the docs but the agent's pre-training data is loud. Strengthen your project rule (Step 3) with an explicit "never use @circles-sdk/\*" line, and prefix one-off prompts with `use context7`.
**`use context7` does nothing.** Check that the MCP server is actually running: in Claude Code run `/mcp`; in Cursor open the MCP panel; in Claude Desktop check the gear icon. The most common causes are a JSON syntax error in the config file, missing Node.js in `PATH`, or forgetting to restart the editor.
**Rate limits.** Without an API key, Context7 is generous but capped. Grab a free key from [context7.com/dashboard](https://context7.com/dashboard) and add it under the `env` block in your MCP config — no other changes needed.
**The generated code uses `ethers` instead of `viem`.** Older Circles SDK examples used ethers. The current `@aboutcircles/sdk` uses viem. Either pin viem explicitly in your prompt or add it to the project rule.
**Pathfinder returns `maxFlow: 0`.** Either there's no trust path between sender and recipient, or both balances need wrapping. Try passing `useWrappedBalances: true` and inspect `rpc.pathfinder.findMaxFlow` first to confirm any liquid path exists.
Happy building. The trust economy is yours to extend.