> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cooby.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connect AI Assistants to Cooby 

# Connect AI assistants to Cooby (MCP)

Connect AI assistants like Claude or ChatGPT to your Cooby workspace and get answers straight from your WhatsApp conversations — ask who's waiting on a reply, get a deal summary before a call, or, as a sales manager, review your team's follow-ups.

Cooby exposes a **read-only** [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server at `https://mcp.cooby.co/mcp`. Any MCP-compatible AI client can connect: Claude (Desktop and claude.ai), ChatGPT, Cursor, and others.

**What AI agents can do:** read your WhatsApp chats and messages, your contacts, and their CRM links.
**What they can never do:** send messages, log CRM activity, or change or delete anything.

---

## Requirements

* A Cooby workspace account (any role — see [Roles & data access](#roles--data-access)).
* An MCP-compatible AI client. This guide covers Claude Desktop, claude.ai, ChatGPT, and Cursor — plus generic instructions for any other MCP client.
* No API keys and no setup by your admin: you authorize the connection yourself with your Cooby login.

---

## Connect Claude Desktop

1. Open **Claude Desktop → Settings → Connectors → Add custom connector**.
2. Enter the server URL:
```
   https://mcp.cooby.co/mcp
```
3. Click **Add**, then **Connect**. Your browser opens Cooby's sign-in page — log in with your Cooby account if you aren't already.
4. Review the **consent screen**. It shows which app is asking (e.g. "Claude") and exactly what it can and cannot do:
* ✅ Can read your WhatsApp chats and messages
* ✅ Can read your contacts and CRM links
* ❌ Cannot send messages
* ❌ Cannot change or delete anything
5. Click **Approve**. You're redirected back and the connector shows as connected.
6. Try it: *"Who should I follow up with today?"*

## Connect claude.ai (web)

1. Go to **claude.ai** **→ Settings → Connectors → Add custom connector**.
2. Enter `https://mcp.cooby.co/mcp` and click **Add**.
3. Complete the same sign-in + consent flow as above.

## Connect ChatGPT or Codex

Custom connectors in ChatGPT require a plan with connector support (e.g. Plus/Pro/Business) and may need **Developer mode** enabled (Settings → Apps & Connectors → Advanced).

1. Open **ChatGPT → Settings → Apps & Connectors → Create** (or **Add custom connector**).
2. Name it "Cooby" and enter the MCP server URL:
```
   https://mcp.cooby.co/mcp
```
3. Choose **OAuth** authentication (ChatGPT discovers Cooby's sign-in service automatically) and save.
4. Complete the same Cooby sign-in + consent flow as above, then enable the connector in a conversation (in some plans: via the tools/"Use connectors" menu).

![](https://storage.crisp.chat/users/helpdesk/website/-/a/7/7/6/a776868fb0318800/screenshot-2026-07-03-at-11531_p7lnki.png =720xauto)


## Connect Cursor

1. **Cursor → Settings → MCP → Add new MCP server**, transport **HTTP (streamable)**.
2. URL: `https://mcp.cooby.co/mcp`. Cursor triggers the same browser sign-in + consent flow.

## Connect any other MCP client

Cooby works with any client that supports **MCP over Streamable HTTP with OAuth**:

* Server URL: `https://mcp.cooby.co/mcp`
* Authentication: OAuth 2.1 with automatic discovery — no API key, no client ID to paste. The client registers itself and opens a browser window for Cooby sign-in + consent.
* For clients configured by JSON (e.g. some desktop tools), a typical entry looks like:
```json
{
    "mcpServers": {
      "cooby": { "type": "http", "url": "https://mcp.cooby.co/mcp" }
    }
  }
```
* If your client asks for OAuth details manually: authorize/token endpoints are published at `https://mcp.cooby.co/.well-known/oauth-authorization-server`; scope is `mcp:read`; PKCE (S256) is required.

> Note: for security, Cooby only accepts OAuth redirect URLs from known AI-client apps (Claude, ChatGPT, Cursor) and local desktop apps (localhost). If your MCP client is not accepted, contact support and we'll review adding it.

---

## What to ask

### For sales reps

| You ask | What happens |
| ---- |
| "Who should I follow up with today?" | Lists your chats where the **last message is from the customer** (awaiting your reply), newest first. |
| "Summarize my conversation with Acme from last week." | Finds the contact, pulls the recent messages, and summarizes them. |
| "What did Carla say about pricing?" | Reads the chat with Carla and answers from the actual messages. |
| "Which of my chats went quiet in the last 3 days?" | Combines chat activity timestamps with the unreplied flag. |

### For sales managers (Admins only)

| You ask | What happens |
| ---- |
| "List my team members." | Returns every workspace member with their user ID and role. |
| "Show unreplied chats across the whole team from the last 48 hours." | Queries every member's chats in the time range; each result shows **whose** chat it is. |
| "Pull this week's chats for Maria and Ken and flag at-risk deals." | Queries just those two reps and reasons over the results. |
| "Show me Maria's conversation with Acme." | Reads one rep's specific chat (admins only). |

---
## Interactive views
When your AI client supports **MCP Apps** (Claude and ChatGPT do), some answers come back as an interactive card rendered right inside the conversation — not just text. Two views ship today:
### Team activity dashboard (admins)
Ask *"Show me the team dashboard"* (or *"How is my team doing this week?"*). Instead of a wall of numbers, you get a visual card with one row per rep:
* total chats, and how many are **awaiting a reply** (bar chart)
* how many chats have been **active in the last 7 days**
* a **last-activity** indicator so quiet reps stand out at a glance
Use it as a Monday-morning glance at where follow-ups are piling up and who needs a nudge. (Admins only, like the underlying team data.)

![](https://storage.crisp.chat/users/helpdesk/website/-/a/7/7/6/a776868fb0318800/screenshot-2026-07-04-at-11433_1dnp6a8.png)


### Conversation view
Ask *"Show my conversation with Acme"* (reps) or *"Show Maria's chat with Acme"* (admins) and the messages render as a familiar **WhatsApp-style thread** — your messages on the right, the customer's on the left, with day separators and an "unreplied" badge when the last word was theirs. Easier to skim than a plain transcript before you jump into the actual chat.
**If your client doesn't support MCP Apps**, nothing breaks — you get the same information as clean text instead of a card. No setting to toggle; the view appears automatically when the client can render it.
![](https://storage.crisp.chat/users/helpdesk/website/-/a/7/7/6/a776868fb0318800/screenshot-2026-07-04-at-11434_1erhtrh.png =577xauto)
---

## Managing connected agents

Go to **Cooby workspace → Settings → Connected AI agents** (`app.cooby.co/settings/connected-agents`).

* **Members** see the agents connected to their own account.
* **Admins** see every agent connected across the workspace, with the owner shown per row.
* Each row shows the agent name, when it was connected, and when it was last used.
* **Revoke** cuts off that agent **immediately** — its current session token stops working on the next request, not just at the next refresh. Members can revoke their own agents; admins can revoke anyone's.

Reconnecting after a revoke is the same flow as the first connection.

![](https://storage.crisp.chat/users/helpdesk/website/-/a/7/7/6/a776868fb0318800/screenshot-2026-07-03-at-12531_1nm4wld.png =1113xauto)

---

## Roles & data access

| Capability | Member | Admin |
| ---- |
| Read own chats, messages, contacts | ✅ | ✅ |
| List workspace members | ❌ | ✅ |
| Read a specific teammate's chats/messages | ❌ | ✅ |
| Read several members' / the whole team's chats, with time ranges | ❌ | ✅ |
| Revoke own connected agents | ✅ | ✅ |
| Revoke any member's connected agents | ❌ | ✅ |

Every request is scoped to **one workspace** — the one you authorized during consent. There is no way for an agent to reach another workspace's data, and a member asking for someone else's data gets a permission error, regardless of how the question is phrased.

---

## Technical details


### Protocol & endpoint

* MCP over **Streamable HTTP** at `https://mcp.cooby.co/mcp` (stateless; no server-side session affinity).
* Tool surface (all read-only, with `readOnlyHint` annotations and typed output schemas): `get_workspace_snapshot`, `search_contacts`, `get_contact`, `list_chats`, `get_chat`, `list_members` (admin).

### Authorization & data isolation

* Every token is bound to one user + one workspace, fixed at consent. Every database query filters by that workspace; no tool parameter can widen it.
* Member vs. admin capabilities are enforced server-side per request (see table above).
* Revoking a grant invalidates its access **and** refresh tokens immediately.

### Rate limits, audit, privacy

* Rate limits: **60 requests/minute per connected agent**, 600/minute per workspace. Exceeding them returns a rate-limit error the agent can retry after a pause.
* Every tool call is audit-logged: who, which agent, which tool, status, latency. Tool **arguments are stored only as a hash** — message content and contact names never appear in logs.
* Message bodies are encrypted at rest and decrypted only inside the request that returns them to your authorized agent.

---

## Troubleshooting

| Symptom | Likely cause / fix |
| ---- |
| "Couldn't connect" / "couldn't register" | Check the URL is exactly `https://mcp.cooby.co/mcp` (with the `/mcp` path). Then retry — transient network issues surface this way too. |
| Consent page says the request expired | The sign-in took longer than 10 minutes. Go back to your AI client and connect again. |
| Agent answers "I don't have access to that" for a teammate's data | You're a Member; teammate data requires the Admin role. Ask your workspace admin. |
| "Who should I follow up with?" returns an error about your phone | Your Cooby account has no WhatsApp number connected yet, so replied/unreplied can't be computed. Connect your WhatsApp first. |
| Agent suddenly gets permission errors mid-conversation | The grant was revoked (by you or an admin) in Settings → Connected AI agents. Reconnect if intended. |
| Rate-limit errors | The agent is calling very rapidly; it can simply retry after a minute. Limits: 60/min per agent. |

**Questions?** Contact support@cooby.co.