# RubiConnect Model Context Protocol (MCP) Server

[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node: >=18](https://img.shields.io/badge/Node.js->=18-brightgreen.svg)](https://nodejs.org)

The official **Model Context Protocol (MCP)** server for [RubiConnect](https://console.rubiconnect.com) — the enterprise platform for **RCS (Rich Communication Services)** and **WhatsApp Business** messaging.

Connect external AI assistants (such as **Claude Desktop**, **Claude.ai**, **Cursor**, **ChatGPT**, and autonomous agent pipelines) directly to your RubiConnect messaging workspace to check phone reachability, send rich cards and carousels, trigger bulk campaigns, inspect live inbox conversations, and query messaging analytics.

---

## ⚡ Quick Start

### 1. Claude Desktop & Claude.ai (Recommended: Native In-App Connector)

RubiConnect supports zero-terminal **OAuth 2.0 with PKCE** inside Claude:

1. In **Claude Desktop** or **Claude.ai**, open **Settings** > **Connectors** > **Add Custom Connector**.
2. Enter the Server URL:
   ```text
   https://console.rubiconnect.com/api/mcp
   ```
3. When prompted by the OAuth connector modal:
   * **Client ID**: Paste your RubiConnect API Key (e.g. `rc_live_...`).
   * **Client Secret**: Leave empty.
4. Authorize in the browser window. All 18 messaging tools will become immediately available in Claude.

---

### 2. Claude Desktop (`claude_desktop_config.json`)

If you configure Claude Desktop via its JSON file:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add the following under `mcpServers`:

```json
{
  "mcpServers": {
    "rubiconnect": {
      "command": "npx",
      "args": [
        "-y",
        "rubiconnect-mcp"
      ],
      "env": {
        "RUBI_API_KEY": "rc_live_your_api_key_here"
      }
    }
  }
}
```

> **Note for macOS GUI apps:** If Claude reports `command not found: npx`, replace `"command": "npx"` with your absolute path (e.g. `"/opt/homebrew/bin/npx"` or `"/usr/local/bin/npx"`).

---

### 3. Cursor IDE

In **Cursor**, open **Cursor Settings** > **Features** > **MCP Servers** > **Add New MCP Server**:

* **Name:** `RubiConnect`
* **Type:** `sse`
* **URL:** `https://console.rubiconnect.com/api/mcp`
* **Headers:**
  ```json
  {
    "Authorization": "Bearer rc_live_your_api_key_here"
  }
  ```

---

### 4. Smithery (1-Click Install)

```bash
npx -y @smithery/cli install rubiconnect-mcp --client claude
```

---

### 5. OpenAI Custom GPTs & Enterprise Agent Orchestrators

In the Custom GPT Editor or Agent framework:
1. **Action Type:** Import from OpenAPI or specify remote MCP endpoint.
2. **Authentication:** OAuth 2.0 (PKCE)
   * **Authorization URL:** `https://console.rubiconnect.com/en/authorize`
   * **Token URL:** `https://console.rubiconnect.com/api/oauth/token`
   * **Client ID:** Your RubiConnect API Key (`rc_live_...`)
   * **Client Secret:** Leave blank or enter any placeholder.

---

## 🛠️ Available MCP Tools (18 Tools)

All tool executions are authenticated and scoped strictly to your account:

### 📱 Messaging & Capabilities
| Tool | Description |
| :--- | :--- |
| `check_capability` | Check whether a phone number supports **RCS** (carrier capability lookup) or falls back to SMS. |
| `send_message` | Send outbound plain text, media cards, or template messages via RCS or WhatsApp. |
| `get_inbox_messages` | Fetch unread and incoming customer messages across your agents. |
| `get_conversation_history` | Retrieve full two-way chat history with a specific customer phone number. |

### 📋 Templates
| Tool | Description |
| :--- | :--- |
| `list_templates` | List pre-approved RCS and WhatsApp rich message templates. |
| `get_template_detail` | Get complete structure of a template (rich card content, media, suggestion chips). |
| `create_template` | Draft a new interactive rich card, carousel, or text template with suggestion chips. |
| `submit_template_to_meta` | Submit a WhatsApp template to Meta for official review and carrier approval. |

### 🚀 Broadcast Campaigns
| Tool | Description |
| :--- | :--- |
| `list_campaigns` | List active, scheduled, and past broadcast campaigns. |
| `get_campaign_status` | Check live progress of a running campaign. |
| `get_campaign_performance` | Retrieve conversion, delivery, read rates, and CTR metrics for a campaign. |
| `create_campaign` | Launch an automated broadcast campaign to a contact list. |

### 🤖 Agents & Channels
| Tool | Description |
| :--- | :--- |
| `list_agents` | List registered RCS Agents and WhatsApp Business phone numbers in your account. |
| `get_agent_profile` | Get carrier verification, logos, colors, and launch status for a specific messaging agent. |

### 📊 Analytics & Media
| Tool | Description |
| :--- | :--- |
| `get_message_stats` | Retrieve 30-day message volume, delivery rates, and deduction statistics. |
| `get_server_status` | System health, API status, and connection diagnostics. |
| `search_images` | Search royalty-free image libraries for rich card headers. |
| `search_documentation` | Search official platform developer documentation directly within the LLM context. |

---

## 🔒 Security & Tenant Isolation

- **Zero Cross-Account Leakage:** Every MCP request is authenticated via API Key or OAuth Bearer token and runs strictly in the context of the authenticated `accountId`.
- **Audit Logged:** Every state-modifying action (sending messages, creating campaigns, submitting templates) is automatically recorded in your account's audit logs under the `mcp-agent` actor.

---

## 🔑 Getting Your API Key

1. Sign in to your [RubiConnect Console](https://console.rubiconnect.com).
2. Go to **Settings** > **API Access**.
3. Generate a new Developer API Key (`rc_live_...`).
4. Use this key to authenticate with Claude, Cursor, or your custom agents.

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.