> For the complete documentation index, see [llms.txt](https://api.circle.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.circle.so/mcp.md).

# Circle MCP

Connect your Circle data (members, posts, and revenue) to AI tools like Claude, Cursor, and ChatGPT. Manage members, create posts, manage workflows, and more — just by asking

### Set up

The connection URL you'll need is:

```
https://app.circle.so/api/mcp
```

When you connect for the first time, you'll sign in with your Circle account and choose what the AI can do — just read your data, or read and make changes.

#### Claude ([claude.ai](http://claude.ai), Cowork, and Claude Desktop)

**Pro and Max plans**

1. Go to **Customize → Connectors**
2. Click **"+"** then **"Add custom connector"**
3. Enter the URL above
4. Click **"Add"**, then follow the sign-in prompts

**Team and Enterprise plans**

1. An Owner must first add the connector: **Organization settings → Connectors → Add → Custom → Web**
2. Enter the URL above and click **"Add"**
3. Members can then find it under **Customize → Connectors** and click **"Connect"**

**Enabling in chat:** Click the **"+"** button in the lower left of your chat, then **"Connectors"** to toggle Circle on or off per conversation.

#### Claude Code (terminal)

```bash
claude mcp add --transport http circle https://app.circle.so/api/mcp
```

Then run `/mcp` in your session and follow the sign-in prompt.

#### Cursor

1. Open **Settings → Tools and MCP → Add new global MCP server**
2. Paste:

```json
{
  "mcpServers": {
    "circle": {
      "url": "https://app.circle.so/api/mcp"
    }
  }
}
```

1. Save, restart Cursor, and sign in when prompted

#### ChatGPT

Custom MCP apps in ChatGPT are in beta and require **Developer mode** to be enabled.

**Step 1: Enable Developer mode**

1. Go to **Settings → Apps → Advanced Settings**
2. Turn on **Developer mode**

**Step 2: Create the Circle app**

1. Go to **Settings → Apps → Create** (or **Workspace Settings → Apps → Create** if you're an admin)
2. Enter:
   * **Name:** Circle
   * **MCP Server URL:** `https://app.circle.so/api/mcp`
   * **Authentication:** OAuth
3. Click **Create**

**Step 3: Connect**

* The app will appear under **Settings → Apps → Enabled Apps** with a **Dev** label
* Click **Connect** and follow the sign-in prompts

**For workspace admins:**

* The app starts as a **Draft** in **Workspace Settings → Apps**
* Review it, then click **Publish** to make it available to your workspace
* You can also configure which actions the app is allowed to take before publishing

#### VS Code (GitHub Copilot)

1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and run **MCP: Add Server**
2. Choose **HTTP** as the type
3. Enter the URL above and name it **Circle**
4. Start the server and complete the sign-in

Or add it manually to `.vscode/mcp.json`:

```json
{
  "servers": {
    "circle": {
      "type": "http",
      "url": "https://app.circle.so/api/mcp"
    }
  }
}
```

#### Windsurf

1. Open **Settings** (`Cmd+,`) → search **MCP** → click **View raw config**
2. Add:

```json
{
  "mcpServers": {
    "circle": {
      "serverUrl": "https://app.circle.so/api/mcp"
    }
  }
}
```

1. Save and restart

#### Grok

1. Sign in to Grok and open [Connectors](https://grok.com/connectors)
2. Click **New Connector**, then select **Custom**.
3. Enter the MCP server URL: `https://app.circle.so/api/mcp`.
4. Follow the sign-in prompts to connect your Circle account.
5. Choose **Read only** or **Full access** when prompted, then approve the connection.
6. Start a conversation by asking, “Show me the spaces in my Circle community.”

#### Other AI tools

Most MCP-compatible tools will ask for either a URL or a JSON config. Use:

```
https://app.circle.so/api/mcp
```

The tool also has to complete the sign-in with your Circle account (OAuth). Desktop and command-line tools that sign in through a localhost callback work. Web-based tools that aren't on Circle's approved list will show a "Redirect URI not approved by Circle" error. If you see it, contact Circle Support and include the complete callback URI from the error.

If your tool doesn't support remote connections directly, use this as a workaround:

```json
{
  "mcpServers": {
    "circle": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.circle.so/api/mcp"]
    }
  }
}
```

***

### Access levels

You pick one when you connect. You can always change it later by disconnecting and reconnecting.

**Read only** — The AI can view your Circle data: members, spaces, posts, events, workflows, subscriptions, and more. It can't create, change, or delete anything. Write tools are completely hidden.

**Full access** — The AI can also take action: invite members, create posts, manage events, send messages, and more.

> We recommend starting with **Read only** and switching to Full access only when you need it.

***

### What you can do

Here's what the AI can help with, depending on your access level:

**View and explore** (both levels)

* Browse members, spaces, posts, events, courses, and tags
* Search for specific members or content
* View forms and form submissions, flagged content, and the gamification leaderboard
* View live rooms and their transcripts
* Get AI-powered summaries of spaces and posts
* View workflows
* View paywalls, member subscriptions, charges, and affiliates
* View contact notes, tax settings, and payment method settings

**Create and manage** (Full access only)

* Invite, update, or remove members
* Create, edit, or delete posts, comments, and events
* Set up courses, sections, and lessons
* Send direct messages and chat messages
* Manage tags, segments, and access groups
* Upload files and images
* Activate, deactivate, or duplicate workflows
* Publish, archive, or delete paywalls, manage paywall groups, delete coupons, and sync paywall access
* Cancel or resume member subscriptions and change billing dates
* Export subscriptions and charges
* Invite and update affiliates, and start, mark paid, or export affiliate payouts
* Add or remove community leads, and add contact notes
* Update, duplicate, or delete forms
* Update tax settings

***

### Billing and usage

Circle MCP runs on the Admin API v2, so every action the AI takes counts as one API request against your account's monthly limit.

| Plan                        | Monthly API requests |
| --------------------------- | -------------------- |
| Business                    | 5,000                |
| Scale                       | 30,000               |
| Circle Plus Lite            | 30,000               |
| All other Circle Plus plans | 250,000              |

Some contracts include a custom allowance instead of these defaults.

You can see your current usage in **Settings → Developers**.

A few things to keep in mind:

* Each tool call = one API request (for example, "show me all members" is one request, "create a post" is one request)
* There's also a rate limit of 2,000 requests per 5 minutes
* If you hit your monthly limit, the AI will let you know it can't complete the action

See [Usage and limits](https://api.circle.so/apis/admin-api/usage-and-limits) for full details.

***

### FAQ

**Can multiple admins connect?**

Yes. Each admin connects with their own account and picks their own access level.

**How do I change my access level?**

Reconnect and choose the new level. Your previous connection is replaced with the new one. Reconnecting with the same level keeps your existing connection.

Connections don't expire. To fully revoke access, delete the `MCP: <tool name>` token in **Settings → Developers → Tokens**.

**The AI says it can't perform an action. What do I do?**

If you're connected with Read only, write actions won't be available. Disconnect and reconnect with Full access. If you've hit your API usage limit, check **Settings → Developers**.

**Can I issue refunds through Claude?**

Not through Claude connectors added under **Customize → Connectors**. Refunds aren't available there, and if you cancel a member's subscription through that connector, it's cancelled without a refund.

**Can the AI set a member's password?**

No. Passwords can't be set through Circle MCP. New members set their own password from the invitation email.

***

### Feedback

* [Developer community](https://community.circle.so/c/developers/)
* [Send us feedback](https://circleco.typeform.com/to/xFEpyITZ)