mcp-support-agent

A local MCP (Model Context Protocol) server that extends Claude Desktop with six customer support tools — order lookup, refund eligibility, policy search, ticket creation, issue summarization, and escalation recommendations.

All data is local and fake. No external services are required beyond the Anthropic API.

---

What Is This Project?

This project builds a local MCP server that connects to Claude Desktop. Once connected, Claude gains access to six custom tools that simulate a real customer support workflow — all powered by fake, local data.

Instead of Claude making things up, it uses structured tools to retrieve real (fake) data, apply deterministic business logic, and take defined actions. This is how production AI assistants in real companies are built.

---

Tools

Tool	Description
lookup_order_status	Retrieve a full order record by order ID
check_refund_eligibility	Apply deterministic 30-day + status rules to evaluate refund eligibility
search_company_policy	Keyword search over the local company policy document
create_support_ticket	Create and persist a structured support ticket
summarize_customer_issue	Generate a concise summary of a customer issue via the Claude API
recommend_human_escalation	Rule-based recommendation on whether to escalate to a human agent

Full input/output documentation for each tool: TOOLS.md

---

Project Structure

mcp-support-agent/
├── server.py                  # FastMCP server — registers all six tools
├── tools/
│   ├── orders.py              # lookup_order_status logic
│   ├── refunds.py             # check_refund_eligibility logic
│   ├── policy.py              # search_company_policy logic
│   ├── tickets.py             # create_support_ticket logic
│   ├── summarize.py           # summarize_customer_issue logic
│   └── escalation.py         # recommend_human_escalation logic
├── data/
│   ├── orders.json            # 14 fake order records
│   ├── tickets.json           # Ticket store (written to at runtime)
│   └── policies.md            # Fake company support policy document
├── setup.ps1                  # Windows: automated setup script
├── run_server.bat             # Windows: one-click server launcher
├── install_claude_config.ps1  # Windows: auto-configure Claude Desktop
├── requirements.txt
├── .env.example
└── .gitignore

---

Easy Windows Setup

For Windows users, three automation scripts handle the full setup.

Step 1 — Run setup.ps1

Right-click setup.ps1 → Run with PowerShell.

This script will:

• Verify Python is installed
• Create a venv virtual environment
• Install all dependencies from requirements.txt
• Copy .env.example → .env

After it finishes, open .env and add your Anthropic API key:

ANTHROPIC_API_KEY=your_key_here

Step 2 — Run install_claude_config.ps1

Right-click install_claude_config.ps1 → Run with PowerShell.

This script will:

• Find your Claude Desktop config file automatically
• Back it up before making any changes
• Add this project's MCP server entry using absolute paths
• Preserve any existing MCP server entries in your config
• Print step-by-step instructions for completing the setup

Step 3 — Start the server

Double-click run_server.bat. Keep this window open while using Claude Desktop.

Step 4 — Restart Claude Desktop

Fully quit Claude Desktop (check the system tray — right-click the icon → Quit), then reopen it. The support-agent tools will appear in the chat interface.

---

Manual Setup (Mac / Linux / Windows)

Prerequisites

• Python 3.10 or higher
• Claude Desktop

1. Clone and set up environment

git clone https://github.com/wyzd0m/mcp-support-agent.git
cd mcp-support-agent
python -m venv venv
source venv/bin/activate        # Mac/Linux
venv\Scripts\activate           # Windows
pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

3. Run the server

python server.py

4. Connect Claude Desktop

Add the following to your Claude Desktop config file:

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

{
  "mcpServers": {
    "support-agent": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/mcp-support-agent/server.py"]
    }
  }
}

Fully restart Claude Desktop after saving.

---

Demo

With the server running and Claude Desktop connected, try:

"A customer named Sarah Mitchell is reporting that her order #ORD-1042 hasn't shipped after 10 days and the estimated delivery date has passed. She wants a refund."

Claude will call the tools in sequence — order lookup, refund eligibility, policy search, ticket creation, and escalation check — grounding every response in the local data rather than inference.

---

Design Notes

Deterministic business logic: Refund eligibility and escalation decisions are handled by rule-based Python functions, not Claude inference. The same input always produces the same output regardless of how a customer phrases their request.

Grounding over inference: Claude uses tool results to answer factual questions about orders and policy. It does not guess at your data.

Write actions are explicit: create_support_ticket is a write operation. Claude Desktop will prompt for user approval before executing it.

---

Documentation

File	Description
SPEC.md	Product specification — goals, non-goals, tool design, data model
TOOLS.md	Full tool reference — inputs, outputs, edge cases
DATA_MODEL.md	Fake data schemas and example records
SECURITY_AND_SAFETY.md	Safety boundaries and design decisions
ROADMAP.md	Planned improvements
CHANGELOG.md	Version history

---

Future Improvements

• Replace JSON files with a SQLite database for proper persistence
• Add semantic search for the policy document using embeddings
• Build a Streamlit dashboard to view created tickets
• Add tool call logging for observability
• Write pytest tests for each tool
• Containerize with Docker
• Add a mock CRM integration layer

Full roadmap: ROADMAP.md

---

Related Projects

• resume-critiquer — AI resume critique app using Python, Streamlit, and the Claude API
• customer-service-ai — AI customer service assistant with knowledge-base grounding and escalation logic

---

License

MIT