Banking MCP Agent (Demo)

A deterministic, SOP-driven banking support agent built with LLM assistance and MCP-style tool orchestration.

This project demonstrates how to combine:

• Large Language Models (LLMs) for reasoning and extraction
• A Python-based agent orchestrator for deterministic control flow
• An MCP-style tool layer for side effects (database writes, auditing)
• Full traceability and auditability across all actions

The system is intentionally designed as a production-style demo, not a chatbot toy.

---

Key Design Principles

• LLM-assisted, not LLM-driven

  • The LLM proposes intent, rationale, and extracted fields
  • All decisions (escalation, case creation, auditing) are controlled by Python

• SOP-first

  • Business logic is driven by SOP policies stored in the database
  • Each intent has explicit escalation rules and required fields

• Deterministic and Auditable

  • Every action is associated with a trace_id
  • All tool calls and decisions are logged to the database

• Minimal but extensible

  • The system is intentionally kept small
  • Designed to be extended toward multi-turn conversations or advanced MCP usage

---

Architecture Overview

High-level architecture:

• Planner (LLM)
  • Determines intent and provides rationale
• Field Extractor (LLM)
  • Extracts required structured fields
• BankingAgent (Python Orchestrator)
  • Controls flow, escalation logic, and tool execution
• MCP Server
  • Encapsulates all side effects (DB writes)
• PostgreSQL
  • Stores SOPs, cases, audit events, and tool calls

The agent follows a deterministic flow:

1. Identify intent
2. Lookup SOP
3. Extract required fields
4. Decide whether to escalate or ask for more information
5. Log all actions with full traceability

---

What This Demo Does

• Intent classification using LLM
• SOP lookup based on intent
• Required-field gating (do not create cases prematurely)
• Priority-aware escalation (urgent vs non-urgent)
• Case creation only when appropriate
• Full audit trail (trace_id, tool calls, events)

---

What This Demo Intentionally Does NOT Do

• ❌ Multi-turn conversation state
• ❌ Long-term dialog memory
• ❌ Autonomous tool selection by the LLM

These features are intentionally excluded to keep the demo focused and deterministic.

Multi-turn conversation handling (stateful dialogs and field accumulation across turns) is a natural next step and can be added as a future extension.

---

Why This Design

In regulated or high-risk domains such as banking or finance:

• Deterministic control flow is more important than autonomy
• Auditability matters more than creativity
• LLMs are best used as reasoning components, not decision-makers

This project reflects that philosophy.

---

Project Structure (Simplified)

(project_root)
├── banking_mcp_agent/
|   |-- banking_agent/
│   |   ├── agent/
│   |   │   ├── orchestrator.py
│   |   │   ├── planner.py
│   |   │   └── models.py
│   |   ├── llm/
│   |   │   ├── deepseek_client.py
│   |   │   ├── intent_classifier.py
│   |   │   └── field_extractor.py
|   |   ├── config.py
│   |   └── db.py
│   ├── mcp_server/
│   │   ├── dispatcher.py
│   │   ├── models.py
│   │   ├── repository.py
│   │   ├── server.py
│   │   └── tool_specs.py
├── scripts/
│   ├── demo_agent.py
│   └── demo_mcp.py
└── data/

Running the Demo

uv run python scripts/demo_agent.py

The output includes:

• Identified intent
• Confidence and rationale
• hether escalation occurred
• Case ID (if created)
• Debug information for inspectio

Future Directions

• Multi-turn conversation state (field accumulation across messages)
• Conversation replay using stored audit logs
• Evaluation metrics for intent accuracy and escalation quality
• Evaluation metrics for intent accuracy and escalation quality