AI IT Helpdesk Assistant (MCP + Multi-Agent)

An AI-powered IT Helpdesk built on the layered MCP architecture from class. Employees chat with an assistant that answers IT questions from real documentation, creates and tracks support tickets, generates reports, and notifies teams on Slack — with every step of the reasoning pipeline visible for teaching and demos.

This repository includes:

• A FastMCP server exposing 29 tools, 10 resources, and 6 prompts
• A multi-agent system: Supervisor + Knowledge, Ticket, Reporting, and Notification agents
• A Streamlit chat interface with an explainable execution pipeline
• PostgreSQL with automatic Alembic migrations and seed data
• Docker Compose setup that works out of the box

Project Overview

The domain is an internal IT helpdesk. It is exposed through two interfaces:

1. MCP interface for AI agents and MCP clients
2. Streamlit interface for employees and instructors

Both use the same service layer, so business logic is never duplicated.

Architecture Diagram

flowchart TD
    U[Employee] --> UI[Streamlit Chat UI]
    UI --> CS[ChatService pipeline]

    CS --> LLM[LLM: summary / intent / entities]
    CS --> SUP[Supervisor Agent]

    SUP --> PL[Planner]
    SUP --> KA[Knowledge Agent]
    SUP --> TA[Ticket Agent]
    SUP --> RA[Reporting Agent]
    SUP --> NA[Notification Agent]

    KA --> MC[Shared MCP Client]
    TA --> MC
    RA --> MC
    NA --> MC

    MC -->|streamable-http| MCP[FastMCP Server]
    MCP --> TOOLS[Tools / Resources / Prompts]
    TOOLS --> SVC[Service Layer]
    UI -.direct pages.-> SVC
    SVC --> REPO[Repository Layer]
    REPO --> DB[(PostgreSQL)]
    SVC --> SLACK[Slack API]

Two rules keep the layering honest:

• Agents never touch the database. They reach data only through the shared MCP client.
• Agents never talk to each other directly. The Supervisor passes each agent's result forward, which is how the Notification Agent can announce a ticket it never queried.

Folder Structure

it-helpdesk-mcp/
├── app.py                  # Streamlit UI (chat + dashboards + inspector)
├── main.py                 # MCP server entrypoint (FastAPI + FastMCP)
├── server.py               # FastMCP wiring + ServiceFactory
├── config.py               # Environment-driven settings
├── database.py             # Engine, session, migrations
├── models.py               # SQLAlchemy ORM models
├── schemas.py              # Pydantic v2 validation schemas
├── repositories.py         # All SQL lives here
├── services.py             # Shared business logic
├── tools.py                # MCP tools
├── resources.py            # MCP resources
├── prompts.py              # MCP prompts
├── seed.py                 # Migrations + demo data
├── agents/
│   ├── base_agent.py       # Abstract agent + allowed-tools guard
│   ├── planner.py          # Dependency-aware execution planning
│   ├── supervisor_agent.py # Coordination and delegation
│   ├── knowledge_agent.py
│   ├── ticket_agent.py
│   ├── reporting_agent.py
│   ├── notification_agent.py
│   ├── agent_context.py    # AgentContext, ExecutionPlanStep
│   ├── agent_response.py   # AgentResponse, AgentToolCall
│   ├── agent_registry.py
│   ├── memory_manager.py
│   └── prompts/            # Per-agent system prompts
├── chat/
│   ├── chat_service.py     # The 13-stage execution pipeline
│   ├── conversation.py
│   ├── conversation_service.py  # Memory + analytics
│   ├── openai_client.py    # Provider-agnostic LLM wrapper
│   ├── tool_executor.py    # Shared MCP client
│   ├── intent_service.py
│   ├── entity_service.py
│   ├── summary_service.py
│   ├── prompt_service.py
│   ├── prompt_builder.py   # Assistant personas
│   ├── json_parsing.py
│   └── prompt_templates/   # system / intent / entity / summary / response
├── migrations/
│   ├── env.py
│   └── versions/0001_initial.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── alembic.ini
└── README.md

Database Schema

employees

Column	Type	Notes
id	int	PK
name	varchar(120)
email	varchar(255)	unique, indexed
department	varchar(100)	indexed
role	varchar(100)
slack_handle	varchar(80)	must start with @
created_at	timestamptz

tickets

Column	Type	Notes
id	int	PK
employee_id	int	FK → employees.id, ON DELETE CASCADE
title	varchar(200)
description	text
category	varchar(60)	indexed
priority	varchar(20)	low / medium / high / critical
status	varchar(20)	open / in_progress / resolved / closed
assigned_team	varchar(80)	nullable, indexed
resolution_notes	text	nullable
created_at / updated_at	timestamptz
resolved_at	timestamptz	set on resolve, cleared on reopen

knowledge_articles

Column	Type	Notes
id	int	PK
title	varchar(200)	indexed
category	varchar(60)	indexed
content	text
tags	varchar(255)	comma-separated keywords
created_at	timestamptz

Relationships: one employee has many tickets.

MCP Concepts

Tool

Performs an operation and may change data. Examples: create_ticket, update_ticket, send_slack_message.

Resource

Read-only, fetchable data snapshots. Examples: tickets://open, knowledge://categories.

Prompt

Reusable instruction templates for LLM workflows. Examples: Daily Incident Report, Knowledge Answer.

Implemented MCP Tools (29)

Ticket tools

create_ticket · update_ticket · get_ticket · get_ticket_status · list_open_tickets · list_tickets · tickets_by_status · tickets_by_priority · tickets_by_category · tickets_by_employee · search_tickets · assign_ticket · resolve_ticket · delete_ticket · count_tickets

Knowledge base tools

search_knowledge · list_knowledge_articles · get_knowledge_article · knowledge_by_category

Employee tools

search_employee · get_employee · get_employee_by_email · list_employees · employees_by_department

Reporting tools

generate_daily_report · generate_incident_summary · helpdesk_summary · tickets_per_department

Notification tools

send_slack_message

Implemented MCP Resources (10)

tickets://all · tickets://open · tickets://critical · tickets://summary · tickets://schema · knowledge://all · knowledge://categories · employees://all · employees://departments · reports://daily

Implemented MCP Prompts (6)

Ticket Summary · Daily Incident Report · Knowledge Answer · Escalation Notice · Generate Ticket Email · Helpdesk Triage Assistant

Multi-Agent Design

Agent	Responsibility	Allowed tools
Supervisor	Plans, delegates, threads results between agents, synthesizes	none (coordination only)
Knowledge Agent	Searches documentation for troubleshooting steps	knowledge tools
Ticket Agent	Creates, updates, assigns, resolves, and looks up tickets	ticket + employee tools
Reporting Agent	Daily reports, incident summaries, backlog analytics	reporting tools
Notification Agent	Composes and sends Slack messages	send_slack_message

Each agent enforces an allowed_tools allowlist in BaseAgent.use_tool, so a specialist physically cannot call a tool outside its remit.

Planning rules

• Documentation is searched before a ticket is created, so a self-service fix is offered first.
• A notification step always depends on the steps producing the content it announces.
• If a follow-up mentions no ticket ID but memory holds one, the Ticket Agent runs first so the Slack message carries the real title and priority.

Example collaboration

"Create a support ticket — the VPN gateway is down for the whole Sales floor, this is critical" → knowledge_agent → ticket_agent (ticket #30 created, priority critical)

"Notify the DevOps team on Slack about it" → ticket_agent → notification_agent → Slack: "Critical ticket opened: VPN Gateway Down for Sales Floor (ID 30). Impacting Sales Floor operations. Please review and assign."

Execution Pipeline (13 stages)

Every user message flows through these stages, all inspectable in the UI:

1. Conversation History → 2. Conversation Summary → 3. Intent Detection →
2. Entity Extraction → 5. Relevant Context → 6. Prompt Construction → 7. Planning →
3. Supervisor Decision → 9. Task Delegation → 10. Agent Execution → 11. Tool Selection →
4. MCP Execution → 13. Response Generation

Conversation Memory

ConversationService persists per-session state so follow-ups work: rolling summary, known entities, referenced tickets, tool-usage counts, agent-usage counts, intent distribution, execution plan, collaboration messages, and a debug event timeline.

This is what lets "notify DevOps about it" resolve to the ticket created a turn earlier.

Validation and Error Handling

Validation uses Pydantic v2 and covers email format, Slack handle format, required fields, positive IDs, enum-constrained status/priority, and length bounds.

Handled errors:

• Validation errors → ServiceValidationError
• Missing ticket/employee/article → NotFoundError
• Duplicate employee email
• Invalid status/priority values
• MCP transport failures vs. tool-level rejections (handled separately)
• Slack delivery failures (returned as data, never crashing the pipeline)

Logging

Every MCP tool invocation is logged with timestamp, tool name, arguments, execution time, and success/failure:

2026-08-01 11:57:39 INFO mcp.requests timestamp=2026-08-01T05:57:39Z tool=search_knowledge args={'query': 'vpn', 'limit': 5} execution_ms=47.83 success=true
2026-08-01 11:57:39 ERROR mcp.requests timestamp=2026-08-01T05:57:39Z tool=get_ticket args={'ticket_id': 999999} execution_ms=15.97 success=false error=Ticket with id=999999 not found

Docker Quick Start

1) Configure environment

cp .env.example .env

Add your LLM API key to .env. The client speaks the OpenAI Chat Completions protocol, so switching providers is a base-URL change only:

Provider	OPENAI_BASE_URL	Example OPENAI_MODEL
Groq (free)	https://api.groq.com/openai/v1	llama-3.3-70b-versatile
Google Gemini (free)	https://generativelanguage.googleapis.com/v1beta/openai/	gemini-2.0-flash
OpenAI	https://api.openai.com/v1	gpt-4o-mini

2) Start everything

docker compose up --build

This starts PostgreSQL, the MCP server, and the Streamlit dashboard, running migrations and seeding demo data automatically.

3) Open the app

• Streamlit UI: http://localhost:8511
• MCP endpoint: http://localhost:8010/mcp
• Health check: http://localhost:8010/health

Ports 8010/8511/5433 are used instead of 8000/8501/5432 so this project can run alongside the customer-order-mcp class project without conflicts.

Running Without Docker (optional)

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows PowerShell
pip install -r requirements.txt

# Start only PostgreSQL from compose
docker compose up -d postgres

# Point the app at the host-mapped database port
export POSTGRES_HOST=localhost POSTGRES_PORT=5433

python seed.py --migrate
python main.py

In another terminal:

export POSTGRES_HOST=localhost POSTGRES_PORT=5433
streamlit run app.py --server.port 8511

Slack Integration

The Notification Agent supports three delivery modes, selected automatically:

Mode	Configuration	Behavior
bot_token	SLACK_BOT_TOKEN (+ chat:write scope)	Posts to any channel by name
webhook	SLACK_WEBHOOK_URL	Posts to the webhook's preconfigured channel
dry_run	neither set	Logs the message and reports it as not delivered

Dry-run is the default so the app runs without a Slack workspace. The response prompt instructs the assistant never to claim delivery unless the tool result says delivered: true.

Streamlit Pages

• AI Helpdesk Assistant — chat + live pipeline inspector
• Dashboard — ticket metrics and department breakdown
• Ticket Management — list, create, update, search
• Knowledge Base — search, browse, add articles
• Agent Monitor — agent status, utilization, plans, collaboration messages
• Developer Tools — memory, execution timeline, raw tool calls
• MCP Playground — call any discovered tool with raw JSON
• Database Viewer — all three tables

Testing: Example MCP Requests and Expected Responses

1. search_knowledge({"query":"password reset"}) → {"articles":[{"title":"How to reset your password", ...}]}

2. search_knowledge({"query":"vpn"}) → {"articles":[{"title":"VPN connection troubleshooting", ...}]}

3. list_open_tickets({}) → {"tickets":[...]} sorted critical-first (18 seeded)

4. get_ticket_status({"ticket_id":1}) → {"ticket_id":1,"status":"in_progress","priority":"high", ...}

5. create_ticket({"title":"Laptop overheating","description":"Shuts down under load","category":"Hardware","priority":"high","employee_id":1}) → new ticket object with "status":"open"

6. update_ticket({"ticket_id":1,"updates":{"priority":"critical"}}) → ticket object with updated priority

7. assign_ticket({"ticket_id":1,"team":"DevOps"}) → ticket with assigned_team:"DevOps", status:"in_progress"

8. resolve_ticket({"ticket_id":1,"resolution_notes":"Reissued MFA token."}) → ticket with status:"resolved" and resolved_at set

9. generate_daily_report({"days":7}) → {"tickets_created":23,"tickets_resolved":6,"open_backlog":18,"critical_open":3, ...}

10. helpdesk_summary({}) → {"total_tickets":25,"open_tickets":11,"critical_tickets":4, ...}

11. send_slack_message({"channel":"#devops","message":"Test"}) → {"delivered":false,"mode":"dry_run", ...} when Slack is unconfigured

12. get_ticket({"ticket_id":999999}) → MCP error: Ticket with id=999999 not found

Example User Queries

Query	Agents	Tools called
"My VPN is not working"	knowledge	search_knowledge
"What is the password reset procedure?"	knowledge	search_knowledge
"Show all open tickets"	ticket	list_open_tickets
"Create a support ticket for my broken laptop"	knowledge → ticket	search_knowledge, create_ticket
"Summarize today's incidents"	reporting	generate_incident_summary, helpdesk_summary
"Notify the DevOps team on Slack"	ticket → notification	get_ticket_status, send_slack_message

MCP Inspector / Claude Desktop / Cursor

Use the MCP server URL: http://localhost:8010/mcp (streamable HTTP transport).

If you connect from another hostname, add it to MCP_ALLOWED_HOSTS in .env — the MCP SDK enables DNS-rebinding protection and rejects unlisted Host headers with HTTP 421.

Troubleshooting

1. Ports already in use — change the host port mappings in docker-compose.yml.
2. DB connection issues — confirm .env matches the compose service name (POSTGRES_HOST=postgres). For local runs use POSTGRES_HOST=localhost POSTGRES_PORT=5433.
3. Migration errors — rebuild: docker compose down -v then docker compose up --build.
4. HTTP 421 Misdirected Request — the hostname is missing from MCP_ALLOWED_HOSTS.
5. Streamlit shows no data — check docker compose logs mcp-server to confirm migrations and seeding completed.
6. Assistant says the API key is missing — set OPENAI_API_KEY in .env and restart.
7. Slack says dry run — expected until SLACK_BOT_TOKEN or SLACK_WEBHOOK_URL is set.

Teaching Notes

The code includes concise comments and docstrings explaining what each layer does, why it exists in a real architecture, which parts demonstrate MCP tools/resources/prompts, and how AI agents invoke these components through MCP.

License

Use this project for classroom teaching, internal demos, and MCP learning labs.