MCP Configuration

The Model Context Protocol (MCP) by Caramelo AI is an open standard that allows you to connect Artificial Intelligence assistants (such as Claude Desktop, ChatGPT, and Gemini) directly to your project’s data securely and in real-time.

With this integration, the AI of your choice gains the ability to query and analyze metrics, leads, conversations, and the performance of your campaigns autonomously.

🚀 How to Access the MCP Panel

1. Access the Caramelo AI Admin Dashboard.
2. Navigate to your project.
3. In the sidebar menu, click on Integrations.
4. In the Model Context Protocol (MCP) card, click on Manage.

On this page, you will find your project’s exclusive Connection URL, the list of active OAuth connections, and the MCP API Keys section.

[!IMPORTANT] Exclusive API Keys for MCP: For clients using static authentication (such as Claude Desktop or Cursor), you must generate an MCP key (mak_...) on this screen. General project API keys (sak_... or cak_...) will be strictly rejected by the MCP server for security reasons.

⚙️ Configuration Instructions by Client

Your project’s connection URL has the following format: https://mcp.carameloai.com/mcp/projects/<PROJECT_ID>

Available URL Parameters

To extend compatibility with different clients and CLIs, you can append query parameters to the connection URL:

• ?json=true (or ?jsonResponse=true): Forces the server to respond to POST requests in application/json format instead of text/event-stream. Useful for clients that do not support reading SSE packages in POST request responses.
• Automatic Detection & Support: The server dynamically detects and negotiates connections from the official SSE standard or legacy connections from the Streamable HTTP draft (sent by CLIs like agy or Go-based clients), providing backward-compatible support under the same URL.

🔵 Cursor / Antigravity IDE (Direct SSE Connection)

If you are using an editor or IDE with native support for MCP connections via SSE/HTTP (such as Cursor or Antigravity IDE):

1. Add a new MCP server in your IDE settings.
2. Select the transport type as SSE (or use the "serverUrl" property in the agent configuration file).
3. Enter your exclusive Connection URL obtained from the dashboard: https://mcp.carameloai.com/mcp/projects/YOUR_PROJECT_ID
4. Configure the authorization headers by passing the mak_ key generated in the dashboard. Example in the mcp_config.json file:

{
  "mcpServers": {
    "caramelo-vendedor": {
      "serverUrl": "https://mcp.carameloai.com/mcp/projects/YOUR_PROJECT_ID",
      "headers": {
        "Authorization": "Bearer mak_YOUR_MCP_KEY_HERE"
      }
    }
  }
}

🟣 Claude Desktop (stdio Connection Bridge via Supergateway)

Since Claude Desktop natively only supports local servers via stdio (standard input/output), you need to use a bridge to convert our server’s SSE connection into local stdio. To do this, we use the supergateway tool, providing the corresponding mak_ key.

1. Open or create the Claude Desktop configuration file on your operating system:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Insert the following structure under the mcpServers key (replacing the URL and the mak_ key with your credentials copied from the Dashboard):

{
	"mcpServers": {
		"caramelo-vendedor": {
			"command": "npx",
			"args": [
				"-y",
				"supergateway",
				"--sse",
				"https://mcp.carameloai.com/mcp/projects/YOUR_PROJECT_ID",
				"--oauth2Bearer",
				"mak_YOUR_MCP_KEY_HERE"
			]
		}
	}
}

3. Restart Claude Desktop. A plug icon will appear in the chat indicating that the tools have been loaded.

🟢 ChatGPT (Custom GPTs / Connectors)

ChatGPT supports remote integration with automatic authorization flow (OAuth 2.1) and dynamic client registration.

1. In ChatGPT, go to Explore GPTs -> Create GPT.
2. In the Configure tab, scroll down to Actions and click Create new action.
3. In the Authentication section, select OAuth and fill in the settings using the connection base URL obtained in the dashboard. ChatGPT will perform auto-registration (DCR) on our server.
4. When the user interacts with the Custom GPT for the first time, they will be redirected to the Caramelo AI login and consent screen.
5. After approval, the connection will be established and listed under Active Connections in your dashboard.

🔵 Gemini CLI / SSE-Compatible Clients

For CLI tools or custom clients using Server-Sent Events (SSE) transport:

• Configure the client by pointing to your project’s HTTP connection URL.
• The MCP client will receive a 401 Unauthorized challenge with the WWW-Authenticate header containing the consent screen information.
• Follow the client instructions to complete browser authentication.

📊 Available Tools for the AI

Once connected, the AI assistant will be able to trigger the following tools when requested in the chat:

📁 Projects and Accounts

• list_projects: Lists all projects available in the account to quickly locate identifiers.
• get_account_subscription: Retrieves data about the current subscription plan.

👥 Customers and Leads

• search_customers: Allows performing text-based search of contacts in the customer database (name, email, phone, etc.).
• get_lead_funnel: Displays lead distribution across the different stages of the sales funnel (CRM).
• get_funnel_transitions: Returns conversion rates and average duration of leads in each stage of the sales pipeline.

📈 Metrics and Performance

• get_chatbot_metrics: Returns aggregated performance metrics of the chatbot (conversion rates, human handoff rates, costs, and sentiments).
• get_live_metrics: Obtains real-time metrics of interactions and messages in the last few hours (active conversations, waiting queue, handoffs).
• get_daily_usage: Presents daily resource and token consumption in the project to track limits.
• get_usage_insights: Provides consolidated usage volume insights in the account (tokens consumed, API calls, tasks, etc.).

💬 Conversations and Support

• list_chatbots: Lists all chatbots configured in the project.
• read_conversation: Allows the AI to view the complete message history of a specific conversation to analyze customer service context.
• list_conversations: Lists project conversations (threads) with support for status and sentiment filters, etc.
• get_failed_conversations: Identifies and lists conversations with low engagement, negative sentiment, or user dissatisfaction.

🔧 Diagnostics and Logs (v1.2)

• get_chatbot: Gets the detailed configuration of prompts, personas, and tools of a chatbot.
• get_tool_execution_logs: Retrieves chatbot tool and API execution logs for integration failure diagnostics.
• get_nlp_insights: Returns cluster insights of user intents and unanswered questions.

🤖 Chatbot Lifecycle (Mutation - v1.3)

• create_chatbot: Creates a new chatbot in the project with an initial draft version.
• get_chatbot_draft: Gets the configuration of the current draft of a chatbot.
• edit_chatbot_draft: Allows editing configuration properties of a chatbot draft.
• generate_chatbot_test_url: Creates a temporary URL to test and preview the chatbot draft.
• publish_chatbot_draft: Promotes the chatbot draft to production, generating a new active version.

🔒 Security and Control

[!IMPORTANT] Data Isolation: Each connection is strictly bound to the selected project. The assistant cannot view data from other projects without explicit, new authorization.

[!TIP] Instant Revocation: If you lose access to a device or want to terminate an AI assistant’s connection, go to the Active Connections section on the MCP page in the dashboard and click Revoke next to the corresponding connection. The token will be invalidated immediately.

[!WARNING] Rate Limiting: To ensure platform stability, each project has a limit of 30 requests per minute to the MCP server.

🙋 Frequently Asked Questions (FAQ)