corebee-plugin

<p align="center">
  <img src="assets/logo.svg" width="72" height="72" alt="Corebee logo">
</p>

<h1 align="center">Corebee plugin</h1>

<p align="center">
  Work your Corebee support inbox from your AI agent: triage conversations, send replies, look up customers, keep the knowledge base current and pull support reports.
</p>

<p align="center">
  Cursor · Grok Bot · Grok Build · Claude Code
</p>

<p align="center">
  <a href="https://github.com/Corebee-AI/corebee-plugin/actions/workflows/validate.yml"><img src="https://github.com/Corebee-AI/corebee-plugin/actions/workflows/validate.yml/badge.svg" alt="Validate"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2E7D6B" alt="MIT license"></a>
</p>

The plugin connects your agent to Corebee's hosted MCP server and adds six skills that tell the agent how to use it safely. You sign in with OAuth. There is no API key to paste.

## Quick start

1. Install the plugin for your client (see [Install](#install)).
2. Sign in when your client asks. Connecting the server opens a Corebee sign-in and consent page in your browser, before any tool runs. Where that happens depends on the client:
   - **Cursor:** use the install button on the marketplace listing, or run `/add-plugin corebee`. Cursor installs the plugin and opens the Corebee sign-in. If the browser did not open, find `corebee` under **Customize** in the sidebar, where Cursor manages its MCP servers, and connect it from there.
   - **Grok Bot:** add the plugin, then approve the connection when Grok Bot asks and finish the sign-in in your browser. If the sign-in window closed too early, reopen it from the plugin's entry. The plugin then appears under your installed plugins.
   - **Grok Build:** enable Corebee under `/plugins`, then finish the sign-in in your browser when Grok asks.
   - **Claude Code:** run `/mcp`, pick `corebee` and choose **Authenticate**, or run `claude mcp login corebee` from your shell. Claude Code shows the Corebee tools only after that.
3. Approve, then ask your agent something about your Corebee inbox, and review what the agent proposes before it changes anything.

## What you can ask

| Ask | Skill |
|---|---|
| "Go through my open Corebee conversations and suggest priorities and owners." | `corebee-inbox-triage` |
| "Draft a reply to Dana's latest conversation from our knowledge base. Show me before sending." | `corebee-reply-drafting` |
| "What do we know about dana@example.com before my call?" | `corebee-customer-lookup` |
| "Can our knowledge base answer these five questions? Add our new returns page if not." | `corebee-knowledge-base` |
| "Give me this month's support report with CSAT and a 30 day trend." | `corebee-support-report` |
| "Change our chat widget to our brand color and move it to the left." | `corebee-widget-setup` |

You can also ask for a single tool, for example "list my pending Corebee conversations" or "how many conversations did each agent resolve this week?".

## Install

You need a Corebee account ([sign up](https://corebee.ai/auth/signup)). When your client connects to the server, it opens a Corebee sign-in and consent page in your browser, before any tool runs.

### Cursor

- **Community directory (live now):** open [Corebee on cursor.directory](https://cursor.directory/plugins/corebee) and use **Add to Cursor**. This installs the whole plugin: the MCP server, the six skills and the rule.
- **Cursor Marketplace:** our listing is in review. Once it is live you will be able to install from the Marketplace or from **Customize**.
- **MCP server only:** [Add Corebee MCP to Cursor](https://cursor.com/install-mcp?name=corebee&config=eyJ1cmwiOiJodHRwczovL2NvcmViZWUuYWkvYXBpL3YxL21jcC9zdHJlYW0ifQ==). This adds the server without the skills and rule.
- **Local test:** copy this repository to `~/.cursor/plugins/local/corebee`, run **Developer: Reload Window**, then check **Customize**.

### Grok Bot

Open **Plugins**, search for Corebee and select **Add to Grok Bot**. Grok Bot uses the Cursor Marketplace listing, so there is nothing else to install. Corebee appears there once the Cursor listing is live.

### Grok Build

From the xAI catalog: open `/plugins` and install Corebee from the **Marketplace** tab. xAI reviews catalog entries, so if Corebee is not listed yet, install from this repository.

From this repository: clone it at the `v1.0.0` tag (or at a commit you reviewed) into `~/.grok/plugins/corebee`, or start Grok with `--plugin-dir <path to the clone>`. Then open `/plugins` and enable Corebee. Grok loads plugins from `./.grok/plugins/`, `~/.grok/plugins/` and any `--plugin-dir` path. This plugin ships one MCP server and six skills, with no hooks or scripts, so enabling it activates nothing that runs on your machine.

### Claude Code

```text
/plugin marketplace add Corebee-AI/corebee-plugin
/plugin install corebee@corebee
```

MCP server only:

```bash
claude mcp add --transport http corebee https://corebee.ai/api/v1/mcp/stream
```

Either way, run `/mcp`, pick `corebee` and choose **Authenticate** to sign in, or run `claude mcp login corebee` from your shell. Claude Code lists the Corebee tools only after that.

### Other MCP clients

Any client with streamable HTTP and OAuth works, as long as its callback is `https` or plain `http` on a loopback host (localhost, `127.0.0.1` or `[::1]`, any port). The one private app scheme Corebee also accepts is Cursor's own desktop callback, `cursor://anysphere.cursor-mcp/oauth/callback`. This is the same file the plugin ships as `mcp.json` and `.mcp.json`:

```json
{
  "mcpServers": {
    "corebee": {
      "type": "http",
      "url": "https://corebee.ai/api/v1/mcp/stream"
    }
  }
}
```

## What's included

| Component | Path | Hosts |
|---|---|---|
| Corebee MCP server (hosted, OAuth) | `mcp.json`, `.mcp.json` | all |
| Skills: inbox triage, reply drafting, customer lookup, knowledge base, support report, widget setup | `skills/` | all |
| Rule: safe use of Corebee tools (applied when a task involves Corebee) | `rules/corebee.mdc` | Cursor |
| Manifests | `.cursor-plugin/`, `.grok-plugin/`, `.claude-plugin/` | one per host |

No hooks, scripts, binaries or telemetry. `scripts/validate.mjs` runs only in CI and is never loaded by a host.

## Sign-in and permissions

- OAuth 2.1 with PKCE and Dynamic Client Registration. Your client finds the sign-in details itself and keeps the tokens. The plugin stores no credentials.
- A connection acts for you, in the Corebee workspace selected when you signed in. To connect another workspace, switch to it in Corebee first.
- Access tokens last 1 hour. Refresh tokens last 30 days and rotate on each use.
- **Access follows your role.** Whatever scopes the client asks for, a connection never gets more than your current role allows, and Corebee checks your role and membership again as requests come in (each server caches the result for at most 30 seconds). If your role is reduced, the connection is limited to the new role within about 30 seconds. If you leave the workspace, it stops working within about 30 seconds. A promotion does not widen an existing connection: reconnect to get the extra access.

| Role | Scopes a connection can hold |
|---|---|
| Owner | All 11 scopes |
| Agent | Read and write for conversations, contacts and knowledge, plus `metrics:read` and `settings:read`. No deletes, no settings changes. |
| Viewer | Read only: `conversations:read`, `contacts:read`, `knowledge:read`, `metrics:read`, `settings:read` |

A member whose role shows as `admin` (a legacy role that `list_team_members` can still return) has the Agent scopes.

| Scope | Allows |
|---|---|
| `conversations:read` | List, read and export conversations |
| `conversations:write` | Reply, add internal notes, assign, close, set priority, label, snooze and tag |
| `contacts:read` / `contacts:write` | Search and read contacts / create, update and add notes |
| `contacts:delete` | Delete contacts (their conversations, messages, CSAT responses, call records and other linked records are kept, without a contact) |
| `knowledge:read` / `knowledge:write` | List, read and search sources, and use the assistant tools / add and update web page sources |
| `knowledge:delete` | Delete knowledge sources |
| `metrics:read` | Metrics, trends and reports |
| `settings:read` / `settings:write` | Read widgets, team and workspace settings / change widget settings |

The consent screen lists the scopes you will get and any your role does not allow, with **Allow access** or **Cancel**. A client that sends no scope (this plugin's `mcp.json` requests none, and many clients send none) gets everything your role allows; the consent screen lists exactly that set. A client that asks only for scopes Corebee does not recognise gets read access only.

### Managing connected apps

In Corebee, open **Settings > Login & security > Connected apps** ([corebee.ai/settings/security](https://corebee.ai/settings/security)). This works for every role. You see the apps you connected and can revoke them. Owners see and can revoke every member's apps there, and also under **Settings > Connect to ChatGPT & Claude**. **Revoke** signs an app out within about 30 seconds, including its current access token. Removing the server in your client discards its copy of the tokens; the connection itself stays until it expires or you revoke it under **Settings > Login & security > Connected apps**.

An owner who wants a read-only connection has two options: connect from a client that lets you request only the read scopes, or connect as a member with the Viewer role.

## Tools

The hosted server lists every tool when your client connects (flat discovery, with no search step). Snapshot 2026-10-12: 44 tools (22 read-only, 19 write, 3 destructive). The same list, with parameters, is in [`scripts/tools.json`](scripts/tools.json), and CI checks that this table matches it.

### Conversations

| Tool | Scope | What it does |
|---|---|---|
| `list_conversa