# Circle MCP

### 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

#### Other AI tools

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

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

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 community: members, spaces, posts, events, analytics, 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 analytics, form submissions, and live room transcripts
* Get AI-powered summaries of space activity

**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

***

### Billing and usage

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

| Plan                     | Monthly API requests |
| ------------------------ | -------------------- |
| Business                 | 5,000                |
| Enterprise / Circle Plus | 30,000               |
| Circle Plus Platform     | 250,000              |

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

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?**

Disconnect and reconnect with the new level. Your old connection is automatically revoked.

**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** in your community.

***

### Feedback

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