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.

Related MCP server: snow-mcp

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

tickets

knowledge_articles

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

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:

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:

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

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.