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


---

# 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://api.circle.so/mcp.md?ask=<question>
```

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.