# CoolPlatform.AI Customer Success Agent

An agentic AI proof of concept that gives Customer Success teams a unified view of customer data, identifies evidence-based risks and opportunities, recommends next steps, and creates follow-up tasks after receiving user approval.

## Project Overview

Customer Success Managers often need to search across several systems to understand an account. Account information may live in Salesforce, usage data in a product platform, customer interactions in Gainsight, and support history in Service Cloud.

This project demonstrates how a single AI agent can use the Model Context Protocol (MCP) to retrieve information from those sources, combine it into a Customer 360 summary, reason over the retrieved evidence, and take an approved action.

The project was built for **Project 3: Agentic AI** using a single AI agent, an MCP client, an MCP server, and multiple MCP tools.

## Project Documentation

- [Detailed Architecture Explanation](docs/architecture.md)
- [Architecture Diagram](docs/images/architecture-diagram.png)
- [Project Reflection](docs/project-reflection.md)

## Business Problem

Customer Success teams need a quick and reliable way to answer questions such as:

- What is happening with this customer?
- Is product adoption increasing or declining?
- Are there unresolved support concerns?
- What customer interactions have occurred recently?
- Is an upcoming renewal showing observable risk?
- What should the CSM do next?

Without an integrated workflow, answering these questions requires manually gathering and reconciling data across several systems.

## Solution

The CoolPlatform.AI Customer Success Agent provides a conversational interface through which a user can:

- Retrieve customer account and contract details.
- Review monthly product-usage trends.
- Review recent customer interactions.
- Analyze support activity.
- Generate a consolidated Customer 360 summary.
- Receive evidence-based recommendations.
- Create a follow-up task after explicit user confirmation.

## Key Agentic Behaviors

The solution goes beyond a basic chatbot because the agent can:

1. Interpret the user's intent.
2. Select the appropriate MCP tool or tools.
3. Retrieve data from multiple business sources.
4. Combine and reason over the retrieved information.
5. Maintain conversational context using memory.
6. Recommend an action based on observable evidence.
7. Request explicit approval before performing a write action.
8. Create and assign a follow-up task after approval.

## Architecture

At runtime, the Replit web interface sends the user's message to the published n8n Chat Trigger. The n8n AI Agent uses the Nebius-hosted Qwen model to understand the request and determine which MCP tools it needs. The n8n MCP Client calls the Python MCP server hosted on Replit. The server retrieves the relevant records from the project datasets and returns structured results to the agent. The agent then generates a response that is displayed in the Replit interface.

```text
User
  → Replit web interface
  → n8n Chat Trigger
  → n8n AI Agent + Conversation Memory
  → MCP Client
  → Python MCP Server on Replit
  → Customer datasets / Follow-up task store
  → AI-generated response
  → Replit web interface
```

## Technology Stack

| Component | Technology | Purpose |
|---|---|---|
| User interface | HTML, CSS, JavaScript on Replit | Provides the branded conversational experience |
| Agent orchestration | n8n | Coordinates chat, model, memory, and tool execution |
| Language model | Qwen3-30B-A3B-Instruct-2507 | Interprets requests, selects tools, and generates responses |
| Model provider | Nebius Token Factory | Hosts the OpenAI-compatible model endpoint |
| Tool protocol | Model Context Protocol (MCP) | Standardizes communication between the agent and tools |
| MCP client | n8n MCP Client | Discovers and invokes tools exposed by the server |
| MCP server | Python | Exposes customer-data and action tools |
| Hosting | Replit | Hosts the application, static interface, API, and MCP server |
| Data | Microsoft Excel and JSON | Simulates enterprise customer systems and task storage |

## Data Sources

The proof of concept uses four synthetic Excel datasets containing 50 fictional customers. No real customer or personal data is used.

| Dataset | Simulated source | Information |
|---|---|---|
| `customer_accounts.xlsx` | Salesforce | Customer identity, ownership, contract, ARR, renewal, and account details |
| `product_usage.xlsx` | CoolPlatform product platform | Monthly active-user and adoption trends |
| `customer_interactions.xlsx` | Gainsight | Customer meetings, engagement history, sentiment, and follow-ups |
| `support_summary.xlsx` | Salesforce Service Cloud | Support volume, severity, status, and resolution information |

Created follow-up tasks are stored in `followup_tasks.json` for demonstration purposes.

## MCP Tools

The MCP server exposes six tools:

| Tool | Function |
|---|---|
| `get_customer_account` | Retrieves customer account, ownership, contract, ARR, and renewal information |
| `get_product_usage` | Retrieves recent product usage and adoption trends |
| `get_customer_interactions` | Retrieves Customer Success interaction history |
| `get_support_summary` | Retrieves summarized support activity |
| `get_customer_360` | Retrieves a consolidated cross-system customer view in one call |
| `create_followup_task` | Creates a follow-up task only after the user approves the action |

The aggregate `get_customer_360` tool reduces the number of round trips required for broad account-summary, renewal-preparation, and risk-analysis requests. The individual tools remain available for narrower questions.

## Responsible Agent Design

The agent includes the following safeguards:

- It bases account analysis on information retrieved through MCP tools.
- It does not claim that a stored health score or stored at-risk classification exists.
- It describes only observable concerns supported by the available data.
- It asks for explicit confirmation before calling `create_followup_task`.
- It separates read operations from the write operation.
- It uses synthetic data rather than real customer records.

## Example Workflow

**User request:**

> Give me a complete Customer Success summary for Horizon Engineering.

**Agent behavior:**

1. Identifies the request as a broad customer-summary request.
2. Calls `get_customer_360` using the customer name or SID.
3. Reviews account, renewal, product usage, interaction, and support information.
4. Produces a structured summary with evidence-based observations.
5. Recommends appropriate next steps.
6. Asks whether the user wants a follow-up task created.
7. Calls `create_followup_task` only if the user explicitly approves.

## Project Structure

```text
app/
├── __init__.py
├── data_loader.py
├── mcp_server.py
└── static/
    ├── index.html
    ├── styles.css
    └── app.js

data/
├── customer_accounts.xlsx
├── customer_interactions.xlsx
├── product_usage.xlsx
├── support_summary.xlsx
└── followup_tasks.json

tests/
├── check_mcp.py
├── test_customer_360.py
├── test_data.py
├── test_joins.py
└── test_web.py
```

The exact static filenames may vary slightly depending on the final Replit project structure.

## Local Setup

### Prerequisites

- Python 3.11 or later
- An n8n instance
- A Nebius API key
- The four project datasets

### Environment Variables

Configure the following values as secrets rather than committing them to source control:

```bash
N8N_CHAT_URL=<published-n8n-chat-trigger-url>
SESSION_SECRET=<random-secret-value>
```

The Nebius credential is configured securely inside n8n.

### Start the Replit Application

```bash
python -m app.mcp_server
```

The application listens on `0.0.0.0:8000` and serves:

- The web interface
- Static assets
- The `/api/chat` integration endpoint
- The `/mcp` Streamable HTTP endpoint

## n8n Workflow Configuration

The n8n workflow contains these connected components:

1. **When chat message received** — receives the user's message.
2. **AI Agent** — interprets the request and orchestrates tool usage.
3. **OpenAI Chat Model** — uses the Nebius OpenAI-compatible endpoint and the Qwen model.
4. **Simple Memory** — maintains conversational context within the session.
5. **MCP Client** — connects to the Replit `/mcp` endpoint and exposes all six tools to the agent.

The workflow and Chat Trigger must be published before the deployed Replit interface can use them.

## Testing

The final project test suite contains **14 passing tests** covering areas such as:

- Dataset loading and integrity
- Cross-dataset joins using the Customer SID
- Individual MCP tool behavior
- Consolidated Customer 360 retrieval
- Follow-up task creation
- Web and static-asset endpoints
- Chat configuration and timeout behavior
- Markdown-to-HTML response rendering

Run the automated test suite with:

```bash
pytest
```

End-to-end testing also verified:

- Successful communication from the Replit interface to n8n
- Successful MCP tool discovery and execution
- Customer 360 response generation
- Conversational memory
- Approval followed by task creation
- Correct display of formatted agent responses

## Deployment

The application is deployed on Replit using:

```bash
python -m app.mcp_server
```

Public application:

[https://coolplatform-cs-agent.replit.app](https://coolplatform-cs-agent.replit.app)

The published n8n MCP Client connects to:

```text
https://coolplatform-cs-agent.replit.app/mcp
```

API keys, session secrets, and the n8n Chat Trigger URL are stored as environment secrets and are not included in the repository.

## Limitations and Future Improvements

This is a proof of concept built with synthetic, file-based datasets. A production implementation could:

- Replace Excel files with authenticated Salesforce, Gainsight, support, and product-data APIs.
- Store tasks in a production Customer Success or CRM platform.
- Add role-based access control and user authentication.
- Add audit logs for tool calls and write actions.
- Stream responses to improve perceived speed.
- Add automated evaluations for response accuracy and tool selection.
- Add observability, retries, and production-grade error handling.
- Extend the design to multiple specialized agents when the use case warrants it.

## Project Outcome

The completed proof of concept demonstrates a practical agentic workflow in which one AI agent uses MCP to access multiple sources, maintains conversational context, reasons over retrieved customer evidence, recommends next steps, and performs an approved business action.

## Author

**Ganesh Raghu**  
Project 3 — Agentic AI