Customer MCP Server

Customer MCP Server is a project for connecting LLMs to customer data using the Model Context Protocol (MCP), allowing AI clients to access customer data securely and with clear governance boundaries.

System Overview

The system is designed so that the LLM can only query customer data through defined tools, without direct database access.

What's Supported

• Retrieve basic customer profile information

• Perform semantic search over customer interaction history using vector embeddings

• Summarize purchase data and financial transactions with exact values

• Record audit logs of transactions

• Prevent prompt injection and unauthorized data access

Architecture

LLM Client
    |
    | MCP Protocol
    v
MCP Server (Python)
    |
    +-------------------+
    |                   |
    v                   v
Semantic Search      SQL / Financial
PostgreSQL + pgvector PostgreSQL

Key Features

1. Customer Profile

• Retrieve basic customer information such as customer_id, name, email, phone, created_at

2. Interaction Semantic Search

• Search customer conversation/interaction history using embedding vectors

• Suitable for semantic search of broad queries such as refund issue, complaint, billing concern

3. Financial Summary

• Calculate order count and total purchase amount from the database

• Use SQL aggregation to produce accurate and reliable values

• Return an audit log of transactions with a hash reference

Hybrid Query Example

Example query:

"What issues has the customer reported, and what is their total purchase amount?"

Flow:

search_customer_interactions()

    |
    v

pgvector similarity search

    +

get_customer_purchase_summary()

    |
    v

SQL aggregation

    |
    v

Combined verified response

Process:

1. MCP Server invokes semantic search from interaction_history using pgvector

2. MCP Server retrieves financial summary from purchase_orders using SQL aggregation

3. Combine the results:

• Customer Context

• Relevant Interaction

• Exact Financial Amount

Return them to the LLM

4. Security Guardrails

• Detects prompt injection patterns

• Validates customer_id before accessing data

• Restricts data access to MCP tools only

Technologies Used

• Python 3.12+

• FastMCP

• asyncpg

• pydantic

• openai

• google-genai

• PostgreSQL 17 + pgvector

• Docker Compose

Project Structure

customer-mcp/
├── app/
│   ├── config.py
│   ├── database.py
│   ├── embeddings.py
│   ├── mcp_server.py
│   ├── security.py
│   └── tools/
│       ├── customer.py
│       ├── financial.py
│       └── semantic_search.py
├── docs/
│   └── ARCHITECTURE.md
├── sql/
│   ├── 01_extensions.sql
│   ├── 02_schema.sql
│   ├── 03_indexes.sql
│   ├── 04_seed.sql
│   └── 05_security.sql
├── docker-compose.yml
├── requirements.txt
├── test_customer.py
├── test_embedding.py
├── test_financial.py
├── test_search.py
├── test_security.py
└── README.md

Prerequisites

• Python 3.12 or newer

• Docker Desktop

• Network access to install packages from PyPI

Installation and Setup

1. Create a virtual environment

py -3.12 -m venv venv

On Windows:

venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Set up environment variables

Create a .env file with the following example:

DATABASE_URL=postgresql://mcp_readonly_user:CHANGE_ME@localhost:5432/customer_mcp

GEMINI_API_KEY=your_gemini_api_key_here

4. Start PostgreSQL database

docker compose up -d

Docker Compose will create a PostgreSQL + pgvector container and automatically initialize the database from the SQL scripts in the sql/ folder.

Note: SQL scripts in docker-entrypoint-initdb.d run only the first time a PostgreSQL volume is created.

To reinitialize everything from scratch:

docker compose down -v

docker compose up -d

Initialization order

sql/01_extensions.sql Enable PostgreSQL extensions Enable pgvector sql/02_schema.sql Create customer tables Create interaction history table Create purchase tables Create immutable audit structure sql/03_indexes.sql Create database indexes Create pgvector HNSW index for semantic search sql/04_seed.sql Insert demo customer data Insert interaction history Insert purchase records Insert audit records sql/05_security.sql Create read-only database user Grant SELECT permission

Verify the container

docker ps

5. Run MCP Server

python -m app.mcp_server

MCP Inspector

You can also inspect MCP Tools through the UI.

mcp-inspector python -m app.mcp_server

Available MCP Tools

get_customer_profile

Retrieve customer profile information

Data source:

• customers table

Returns:

• customer_id

• first_name

• last_name

• email

• phone

• created_at

Example input:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

search_customer_interactions

Semantic search for interaction history using pgvector

Example input:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "refund issue",
  "limit": 3
}

get_customer_purchase_summary

Retrieve exact purchase totals using SQL aggregation

Example input:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}

Available MCP Tools

Testing

You can run the following test files from the repository root:

python test_embedding.py
python test_search.py
python test_financial.py
python test_security.py
python test_customer.py

Security Notes

• LLM cannot access the database directly

• Data access is allowed only through MCP Tools

• Input validation is applied to customer_id

• Detects prompt injection patterns

• Financial data uses SQL aggregation to return exact values

• Audit log is an immutable append-only structure

• The database user for MCP has least-privilege permissions

• UPDATE / DELETE / DDL operations are not allowed