# Agentic Setup for Circles 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.aboutcircles.com/miniapps/agentic-setup-for-circles.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.