RubiConnect MCP Integration Guide

2.1 Claude In-App Connector (Desktop App & Claude.ai Web) — Recommended

Whether you are using the Claude Desktop Application on macOS/Windows or Claude.ai in your browser, Anthropic provides an in-app Point-and-Click Connector interface powered by OAuth 2.0 with PKCE. This is the easiest, zero-terminal way to connect RubiConnect to Claude.

1. In Claude Desktop or Claude.ai, navigate to Settings > Connectors (or select Add Custom Connector).
2. Enter the Server URL:

   https://console.rubiconnect.com/api/mcp

1. When prompted by the OAuth connector modal:
   • Client ID: Paste your RubiConnect API Key (e.g. rc_live_...).
   • Client Secret: Leave blank or empty (RubiConnect uses RFC 7636 PKCE which does not require a static client secret).
2. Claude will open your browser to the RubiConnect authorization bridge (/en/authorize), validate your API key, and complete the handshake.
3. All 16 messaging, campaign, template, and analytics tools will immediately become available in your Claude chat sessions.

2.2 OpenAI Custom GPTs & Enterprise Agent Platforms

To connect RubiConnect to ChatGPT Custom GPTs or enterprise agent orchestrators (such as Flowise, LangChain, or Zapier Central):

1. In the GPT Editor, navigate to Actions > Create new action.
2. Under Authentication, select OAuth:
   • Client ID: Enter your RubiConnect API Key (rc_live_...).
   • Client Secret: Any placeholder string (or leave empty if supported).
   • Authorization URL: https://console.rubiconnect.com/en/authorize
   • Token URL: https://console.rubiconnect.com/api/oauth/token
   • Scope: mcp (or leave empty).
   • Token Exchange Method: POST request (Basic or Body)
3. Import the MCP tool definitions from https://console.rubiconnect.com/api/mcp or copy the OpenAPI schema.
4. Save and test the action; ChatGPT will authenticate seamlessly via the RubiConnect OAuth bridge.

2.3 Claude Desktop JSON File (claude_desktop_config.json) — Alternative Stdio Bridge

If you are a developer who prefers configuring Claude Desktop manually by editing claude_desktop_config.json on disk (rather than using the in-app Settings UI described in Section 2.1), Claude Desktop expects a local stdio subprocess. Because the RubiConnect MCP server is hosted remotely as an HTTP SSE service, manual file configuration requires a bridge tool (like mcp-remote) to proxy stdio to the remote SSE endpoint.

Recommended Configuration (mcp-remote)

Add the following configuration to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "rubiconnect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://console.rubiconnect.com/api/mcp",
        "--header",
        "Authorization:Bearer ${RUBI_API_KEY}"
      ],
      "env": {
        "RUBI_API_KEY": "rc_live_your_actual_api_key_token"
      }
    }
  }
}

Syntax Note: The --header parameter must be formatted exactly as "Authorization:Bearer ${RUBI_API_KEY}" with no space after the colon.

macOS GUI PATH Resolution: The Claude Desktop GUI application does not automatically inherit your shell's .zshrc or .bashrc PATH. If Claude reports command not found: npx, replace "command": "npx" with the absolute path to your Node/npx binary:

* Apple Silicon (M1/M2/M3/M4): "/opt/homebrew/bin/npx"

* Intel Mac: "/usr/local/bin/npx"

* Run which npx in your terminal to confirm your exact location.

Alternative: Bundled Node.js Bridge Script

If you prefer not running mcp-remote through npx every time, RubiConnect provides a standalone bridge script in the platform repository at scripts/claude-mcp-bridge.mjs:

{
  "mcpServers": {
    "rubiconnect": {
      "command": "node",
      "args": ["/absolute/path/to/RubiConnect platform/scripts/claude-mcp-bridge.mjs"],
      "env": {
        "RUBI_API_KEY": "rc_live_your_actual_api_key_token"
      }
    }
  }
}

2.4 Cursor IDE

Cursor natively supports remote Server-Sent Events (SSE) MCP servers without needing any local bridge:

1. Open Cursor and press Cmd + , (or Ctrl + ,) to open Settings.
2. Navigate to Features > MCP.
3. Click + Add New MCP Server.
4. Fill in the connection settings:
   • Name: rubiconnect
   • Type: SSE
   • URL: https://console.rubiconnect.com/api/mcp
   • Headers: {"Authorization": "Bearer rc_live_your_actual_api_key_token"} (or {"X-Rubi-Key": "rc_live_your_actual_api_key_token"})
5. Cursor will connect immediately and display a green indicator beside rubiconnect with all 16 registered tools.

2.5 Python SDK Connection

Using the official Python mcp library:

import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client

async def main():
    headers = {"Authorization": "Bearer rc_live_your_actual_api_key_token"}
    async with sse_client("https://console.rubiconnect.com/api/mcp", headers=headers) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print("Available Tools:", len(tools.tools))
            
            # Retrieve active messaging agents
            result = await session.call_tool("list_agents", {})
            print("Agents:", result.content[0].text)

asyncio.run(main())

2.6 Node.js SDK Connection

Using the official JavaScript @modelcontextprotocol/sdk package:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function main() {
  const transport = new SSEClientTransport(
    new URL("https://console.rubiconnect.com/api/mcp"),
    {
      headers: {
        "Authorization": "Bearer rc_live_your_actual_api_key_token"
      }
    }
  );

  const client = new Client({
    name: "rubiconnect-mcp-client",
    version: "1.0.0"
  }, {
    capabilities: {}
  });

  await client.connect(transport);

  // List tools
  const { tools } = await client.listTools();
  console.log(`Discovered ${tools.length} tools`);

  // Query agents list
  const agentsResponse = await client.callTool({
    name: "list_agents",
    arguments: {}
  });
  console.log("Agents:", agentsResponse.content[0].text);
}

main();

2.7 Google Gemini API Integration (Function Calling)

Expose RubiConnect tools to Gemini models using the official @google/genai SDK:

import { GoogleGenAI } from "@google/genai";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function main() {
  // 1. Connect to RubiConnect MCP Server
  const transport = new SSEClientTransport(
    new URL("https://console.rubiconnect.com/api/mcp"),
    {
      headers: {
        "Authorization": "Bearer rc_live_your_actual_api_key_token"
      }
    }
  );
  const client = new Client({ name: "gemini-mcp-agent", version: "1.0.0" }, { capabilities: {} });
  await client.connect(transport);

  // 2. Load MCP Tools
  const { tools } = await client.listTools();

  // 3. Convert MCP Tools to Gemini function declarations
  const geminiTools = tools.map((tool) => ({
    functionDeclarations: [{
      name: tool.name,
      description: tool.description,
      parameters: tool.inputSchema
    }]
  }));

  // 4. Query Gemini model with function calling
  const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'List my active messaging agents, please.',
    config: {
      tools: geminiTools
    }
  });

  // 5. Execute Gemini tool call recommendation
  const call = response.functionCalls?.[0];
  if (call) {
    console.log(`Calling MCP tool: ${call.name}`);
    const result = await client.callTool({
      name: call.name,
      arguments: call.args
    });
    console.log("MCP Execution Result:", result.content[0].text);
  } else {
    console.log("Gemini Response:", response.text);
  }
}

main();

System & Health

get_server_status

Retrieve real-time health status, supported messaging channels, and MCP protocol version for the RubiConnect server.

• Input Schema: object (no parameters)
• Output Format: Health status object containing status, serverName, version, protocolVersion, supportedChannels, and timestamp.

Brand Identities & Agents

list_agents

Retrieve active messaging agent profiles (RCS & WhatsApp) registered to the account.

• Input Schema: object (no parameters)
• Output Format: Array of agent profiles containing id, displayName, type, and status.

get_agent_profile

Retrieve detailed configuration, verification status, and supported channel capabilities for a specific agent profile.

• Parameters:
  • agentId (string, required): Unique agent profile identifier.
• Output Format: Detailed agent object including Sinch/Meta verification metadata, webhooks, and channel attributes.

Messaging & Transcripts

check_capability

Checks whether a recipient's phone number is capable of receiving rich messages (RCS or WhatsApp) on a specified agent profile.

• Parameters:
  • recipient (string, required): Recipient phone number in E.164 format.
  • agentId (string, required): Agent identifier to verify against.
• Output Format: { capable: boolean, channel: "RCS"|"WHATSAPP", status: string }

send_message

Sends a message to a single recipient OR streams a zero-persistence bulk broadcast directly from a remote HTTPS CSV/JSONL URL across RCS and WhatsApp.

• Parameters:
  • agentId (string, required): Unique ID of the sending agent profile.
  • recipient (string, conditional): Phone number of the recipient in E.164 format (for single send).
  • contactsUrl (string, conditional): Pre-signed HTTPS CSV or JSONL URL to stream contacts from with zero database persistence.
  • urlFormat (string, optional): Format of contactsUrl ("csv" or "jsonl", default "csv").
  • text (string, optional): Text message content.
  • mediaUrl (string, optional): Public URL of media to send.
  • templateId (string, optional): Pre-configured template ID.
  • allowSmsFallback (boolean, optional): Fall back to SMS if recipient lacks RCS capability.
  • suggestions (array of objects, optional): List of interactive buttons (max 4). Each object contains:
  • type (string, required): Choice of "reply", "url", "phone", or "copy_code".
  • text (string, required): The label shown on the button (max 25 chars).
  • value (string, optional): Action value (URL for "url", phone number for "phone", code for "copy_code", or custom postback payload for "reply").
• Output Format: Status object returning messageId (for single send) or broadcastId and status: "streaming" (for remote URL broadcasts).

get_inbox_messages

Retrieve recent inbox messages and chat logs for a specific agent profile.

• Parameters:
  • agentId (string, required): Mandatory agent profile identifier.
  • limit (number, optional): Number of messages to return (max 100, default 20).
• Output Format: Array of message logs containing id, recipient, content, status, and date.

get_conversation_history

Retrieves recent back-and-forth chat messages and transcripts for a specific customer phone number.

• Parameters:
  • recipient (string, required): Customer phone number in E.164 format.
  • agentId (string, required): Agent profile identifier.
  • limit (number, optional): Number of message turns to return (default 20).
• Output Format: Chronological array of chat interactions with message direction and delivery state.

Message Templates

list_templates

Retrieves pre-configured rich media, card, carousel, and text message templates for an agent profile.

• Parameters:
  • agentId (string, required): Agent profile identifier.
• Output Format: Array of templates including card orientation, media height, and interactive button definitions.

get_template_detail

Retrieves deep structure, orientation, and button action payloads for a specific message template.

• Parameters:
  • templateId (string, required): Template identifier.
  • agentId (string, required): Agent identifier.
• Output Format: Complete template entity with raw card structures and button configurations.

create_template

Create a message template in the account library. Supports rich standalone cards (image, title, text, buttons), carousels, media, and plain text. For WhatsApp agents, automatically validates Meta formatting rules and submits to the Meta Graph API for review.

• Parameters:
  • name (string, required): Unique name of the template (lowercase, numbers, and underscores only).
  • text (string, required): Main message content. Supports placeholders like {{customer_name}} or {{discount_code}}.
  • type (string, optional): "card", "text", "media", or "carousel".
  • title (string, optional): Bold headline for cards.
  • mediaUrl (string, optional): Optional image, video, or document URL for the header.
  • cardOrientation (string, optional): "VERTICAL" or "HORIZONTAL".
  • mediaHeight (string, optional): "SHORT", "MEDIUM", or "TALL".
  • agentId (string, optional): Associated agent.
  • category (string, optional): Meta template category for WhatsApp agents ("MARKETING", "UTILITY", "AUTHENTICATION", default "MARKETING").
  • language (string, optional): Language code for WhatsApp templates, e.g. "en_US", "es_ES" (default "en_US").
  • footer (string, optional): Optional footer text (max 60 chars).
  • submitToMeta (boolean, optional): For WhatsApp agents: whether to submit immediately to Meta Graph API (default true).
  • suggestions (array of objects, optional): Interactive buttons (reply, url, phone, copy_code, flow).
• Output Format: Status object confirming success, templateId, metaTemplateName, and metaStatus ("PENDING" or "APPROVED").

Campaigns & Broadcasts

list_campaigns

List recent messaging campaigns with live delivery status and performance metrics.

• Parameters:
  • agentId (string, optional): Filter campaigns by sending agent profile.
  • limit (number, optional): Maximum number of campaigns to return (default 20, max 50).
• Output Format: Array of campaign summaries with real-time stats.

get_campaign_status

Retrieve real-time delivery status, sent, delivered, read, and failed counts for a campaign or streaming broadcast.

• Parameters:
  • campaignId (string, required): Unique campaign identifier.
  • agentId (string, optional): Agent identifier to scope query.
• Output Format: Object containing id, name, status, recipientSource, stats: { sent, delivered, read, failed }.

get_campaign_performance

Retrieves detailed analytical performance for a campaign, including delivery rate, read rate, and recipient engagements.

• Parameters:
  • campaignId (string, required): Unique campaign identifier.
  • agentId (string, optional): Agent identifier to scope query.
• Output Format: Performance percentages and engagement analytics.

create_campaign

Create and dispatch an outbound messaging campaign targeting stored contacts or streaming from a remote HTTPS CSV/JSONL URL with zero database persistence.

• Parameters:
  • name (string, required): Descriptive name of the campaign.
  • agentId (string, required): Agent ID to send the campaign from.
  • recipients (array of strings, optional): Array of recipient phone numbers.
  • contactsUrl (string, conditional): Pre-signed HTTPS CSV/JSONL URL to stream contacts from.
  • urlFormat (string, optional): Format of contactsUrl ("csv" or "jsonl", default "csv").
  • recipientSource (string, optional): Audience source ("contacts" or "remote_url").
  • contactListName (string, optional): Stored contact list name.
  • text (string, optional): Main campaign message content.
  • templateId (string, optional): Pre-configured template ID reference.
  • flowId (string, optional): Interactive flow ID reference.
  • sendNow (boolean, optional): Automatically queues and streams the broadcast immediately (default true).
  • allowSmsFallback (boolean, optional): Enable SMS fallback for non-RCS recipients.
• Output Format: Status object with campaignId, status: "Sending", recipientSource, and channel.

Analytics & Media

get_message_stats

Aggregates real-time message delivery volume, failure counts, and read rates over specified time ranges.

• Parameters:
  • agentId (string, optional): Agent identifier.
  • timeRange (string, optional): "today", "yesterday", "7d", or "30d" (default: "today").
• Output Format: Aggregate metrics with total sent, delivered, read, failed, and delivery percentage.

search_images

Searches the workspace media library and external asset providers for royalty-free images matching a search query.

• Parameters:
  • query (string, required): Search terms (e.g. "coffee", "summer sale").
• Output Format: Array of image objects with URLs, previews, and dimensions.

messages://inbox

The workspace inbox contains a list of the 20 most recent messages (incoming customer replies and outgoing messages).

• MIME Type: application/json
• Format: JSON array containing message details: id, recipient, content, status, and date.

Real-Time Update Notifications

Connected MCP client agents can subscribe to the messages://inbox resource.

1. When a contact responds (e.g. clicks a quick-reply button), the carrier delivers the response to RubiConnect.
2. The MCP Server immediately dispatches a JSON-RPC notification notifications/resources/updated with the uri: "messages://inbox" parameter over the active SSE transport stream.
3. The AI client agent receives this notification and can call resources/read to fetch the new reply and continue the conversation interactively.

Salesforce Agentforce & Einstein Copilot

Salesforce Einstein and Agentforce support connecting to external API services to run tools.

1. Named Credentials: Configure a Named Credential in Salesforce Setup targeting https://console.rubiconnect.com/api/mcp and specify the custom header X-Rubi-Key.
2. Apex Action Bridge: Implement a lightweight Apex class that handles connection negotiation (SSE wrapper) and translates JSON-RPC requests, exposing them as Einstein Copilot Actions.
3. Triggering: Einstein Copilot can dynamically trigger send_message or create_campaign when sales representatives prompt the agent (e.g., "Send the product pricing brochure via RCS to the lead").

HubSpot Breeze & AI Agents

HubSpot AI Agents can use custom workflow extensions to query and trigger external messaging actions.

1. Custom workflow actions: Register a Custom Workflow Action in your HubSpot developer portal pointing to our API route.
2. Workflow automation: When a HubSpot workflow trigger occurs (e.g. Lead Status changes to "Contacted"), the HubSpot Breeze agent resolves the customer information and calls the send_message tool on RubiConnect to deliver a rich messaging introduction.

Shopify AI Agents & Flow

Shopify e-commerce sites can utilize AI customer service agents (e.g., built on OpenAI Assistants or custom LangChain flows) to automate transactional messages.

1. Cart Retrieval & Promos: The AI agent detects an abandoned cart or order confirmation event.
2. Tool Invocation: The agent calls the send_message tool to deliver the order update or coupon code directly to the customer's phone via RCS.