Agente CRM LangGraph MCP AWS DynamoDB

Galaxy Telecom — Integración estandarizada de herramientas de IA mediante Model Context Protocol

Un agente de IA de nivel de producción que demuestra la integración de MCP (Model Context Protocol) con AWS DynamoDB — conectando un agente LangGraph a datos CRM en tiempo real mediante un protocolo de herramientas estandarizado en lugar de integraciones personalizadas a medida.

📄 Documento de portafolio (PDF) — informe completo con arquitectura, configuración de AWS DynamoDB e interacciones de ejemplo

Descripción general

Los agentes de IA tradicionales que necesitan datos CRM requieren integraciones codificadas de forma fija — código personalizado para cada sistema externo, estrechamente acoplado a la lógica del agente. Este proyecto demuestra un enfoque mejor: el agente se conecta a un servidor MCP de Python en tiempo de ejecución, descubre dinámicamente las herramientas disponibles y las llama para recuperar datos en tiempo real de cuentas de clientes y tickets desde AWS DynamoDB — sin ninguna lógica de integración codificada de forma fija en el agente.

Related MCP server: Agorus MCP Server

¿Qué es MCP?

MCP (Model Context Protocol) es un estándar abierto introducido por Anthropic que define cómo los agentes de IA se conectan a herramientas externas y fuentes de datos. Es para los agentes de IA lo que las API REST son para los servicios web — un contrato universal que permite la interoperabilidad sin adaptadores a medida para cada integración.

La capacidad clave es el descubrimiento de herramientas en tiempo de ejecución. El agente no sabe qué herramientas existen al iniciarse. Se conecta al servidor MCP y pregunta «¿qué puedes hacer?». El servidor responde con nombres de herramientas, descripciones y esquemas de entrada. El agente decide entonces qué herramientas llamar según la consulta del cliente.

Arquitectura

Customer CLI Input
        │
        ▼
┌─────────────────────┐
│   LangGraph Agent   │  ← ReAct pattern, Claude Haiku (Anthropic API)
│   (crm_agent.py)    │
└──────────┬──────────┘
           │ MCP protocol — stdio transport
           │ Runtime tool discovery via get_tools()
           ▼
┌─────────────────────┐
│    MCP Server       │  ← FastMCP, Python
│    (server.py)      │
│                     │
│  get_customer_      │  ← queries CustomerAccounts table
│  account()          │
│                     │
│  get_open_          │  ← queries SupportTickets table
│  tickets()          │
└──────────┬──────────┘
           │ boto3
           ▼
┌─────────────────────┐
│   AWS DynamoDB      │  ← eu-west-1
│                     │
│ GalaxyTelecom_      │
│ CustomerAccounts    │
│                     │
│ GalaxyTelecom_      │
│ SupportTickets      │
└─────────────────────┘

Definición de herramientas MCP

Las herramientas se registran en el servidor MCP mediante el decorador @server.tool(). El agente no tiene conocimiento de estas funciones — recibe sus definiciones dinámicamente a través del protocolo en tiempo de ejecución.

@server.tool()
def get_customer_account(customer_id: str) -> str:
    """
    Retrieve a Galaxy Telecom customer account from DynamoDB.
    Returns account details including plan, status, and balance due.
    """
    ...

@server.tool()
def get_open_tickets(customer_id: str) -> str:
    """
    Retrieve all open support tickets for a Galaxy Telecom customer.
    Returns a list of tickets with issue type, description, status and priority.
    """
    ...

Sustituir DynamoDB por Salesforce o Dynamics solo requiere una nueva implementación del servidor MCP. El código del agente permanece completamente sin cambios — lo que demuestra el beneficio de portabilidad del protocolo.

Tablas de AWS DynamoDB

GalaxyTelecom_CustomerAccounts

• Clave de partición: customer_id

• Almacena: nombre, email, plan, cargo mensual, estado de la cuenta, saldo pendiente, miembro desde

GalaxyTelecom_SupportTickets

• Clave de partición: customer_id, Clave de ordenación: ticket_id

• Almacena: tipo de incidencia, descripción, estado, fecha de creación, equipo asignado, prioridad

• La clave compuesta permite recuperar todos los tickets de un cliente en una sola consulta

Interacciones de ejemplo

Cuenta vencida con tickets abiertos (C001)

Customer ID : C001
Message     : Hi, I wanted to check on my account and see if there are any issues.

[MCP] Tools discovered: ['get_customer_account', 'get_open_tickets']

Response: Hi John, I can see your account is overdue with a balance of £47.50.
You have 2 open tickets — a billing query (T001, medium priority) and
broadband dropouts (T002, high priority, in progress with Technical Support)...

Cuenta activa, ticket técnico existente (C002)

Customer ID : C002
Message     : I have been having some signal issues at home, can you help?

Response: Hello Sarah! I can see you're on our EliteMax plan with no balance due.
You've already raised ticket T003 regarding weak 5G signal — an engineer
visit has been requested, marked medium priority...

ID de cliente no válido — manejo elegante de errores

Customer ID : 99
Message     : I have been having some signal issues at home, can you help?

Response: I'm unable to locate a Galaxy Telecom account associated with
Customer ID 99. The ID may have been entered incorrectly...

Stack tecnológico

Estructura del proyecto

langgraph-mcp-aws-dynamodb-agent/
├── agent/
│   ├── __init__.py
│   └── crm_agent.py        # LangGraph ReAct agent — connects to MCP server
├── dynamo/
│   ├── __init__.py
│   └── seed_data.py        # Creates DynamoDB tables and seeds mock CRM data
├── mcp_server/
│   ├── __init__.py
│   └── server.py           # MCP server — exposes CRM tools backed by DynamoDB
├── main.py                 # Interactive CLI entry point
├── requirements.txt
├── .env.example            # Environment variable template
└── .gitignore

Configuración e instalación

Requisitos previos

• Python 3.11+

• Clave de API de Anthropic

• Cuenta de AWS con CLI configurada (aws configure)

• Usuario de IAM con permisos de lectura/escritura en DynamoDB

Instalación

# Clone the repository
git clone https://github.com/gayatrianne/langgraph-mcp-aws-dynamodb-agent.git
cd langgraph-mcp-aws-dynamodb-agent

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env and add your Anthropic API key

Variables de entorno

# Anthropic
ANTHROPIC_API_KEY=your_key_here

# AWS — credentials come from AWS CLI profile (aws configure)
AWS_REGION=eu-west-1

# DynamoDB table names
CUSTOMER_TABLE=GalaxyTelecom_CustomerAccounts
TICKETS_TABLE=GalaxyTelecom_SupportTickets

# LLM Configuration
CLAUDE_MODEL=claude-haiku-4-5-20251001
CLAUDE_TEMPERATURE=0.3

Poblar las tablas de DynamoDB

Ejecutar una vez antes de iniciar el agente:

python dynamo/seed_data.py

Esto crea ambas tablas de DynamoDB en eu-west-1 y las puebla con registros de clientes y tickets de soporte simulados de Galaxy Telecom.

Ejecutar

python main.py

Introduce un ID de cliente (C001, C002, C003, C004) y un mensaje de soporte. El agente descubrirá las herramientas MCP, consultará DynamoDB y devolverá una respuesta personalizada basada en datos CRM en tiempo real.

Decisiones de diseño clave

Descubrimiento de herramientas en tiempo de ejecución mediante MCP El agente llama a await client.get_tools() en tiempo de ejecución — no sabe qué herramientas existen hasta que se lo pregunta al servidor MCP. Este es el beneficio principal del protocolo: el agente está desacoplado de la implementación.

Manejo elegante de errores Los ID de cliente no válidos devuelven un JSON de error estructurado desde el servidor MCP. El agente interpreta esto de forma natural y responde de manera útil sin exponer detalles técnicos al cliente.

Portabilidad de MCP Sustituir DynamoDB por Salesforce, Dynamics o cualquier otro CRM solo requiere una nueva implementación del servidor MCP. El código del agente LangGraph en crm_agent.py permanece completamente sin cambios — el agente está desacoplado de la fuente de datos mediante la capa de protocolo.

Modelo de datos de AWS DynamoDB CustomerAccounts utiliza una única clave de partición (customer_id). SupportTickets utiliza una clave compuesta (customer_id + ticket_id) — lo que permite que una sola consulta devuelva todos los tickets de un cliente, reflejando los patrones reales de acceso a datos CRM.

Habilidades demostradas

• Model Context Protocol (MCP) — integración estandarizada de herramientas de IA

• Descubrimiento de herramientas en tiempo de ejecución — el agente descubre herramientas dinámicamente, sin codificación fija

• Orquestación de agentes con LangGraph — patrón ReAct con llamadas a herramientas externas

• AWS DynamoDB — almacén de datos CRM NoSQL con claves de partición y ordenación

• boto3 — AWS SDK para Python

• FastMCP — framework de servidor MCP para Python

• Manejo elegante de errores — respuestas de error estructuradas de MCP

• Configuración externalizada — modelo y región mediante variables de entorno

Autora

Gayatri Anne Arquitecta de IA y Cloud | Más de 18 años en TI empresarial

Construyo sistemas de automatización impulsados por IA que eliminan el trabajo manual de los procesos empresariales, combinando flujos de trabajo con agentes, grandes modelos de lenguaje e integración en la nube para ofrecer soluciones listas para producción.

Certificaciones: Azure Solutions Architect Expert | Azure AI Engineer Associate | Python PCAP | TOGAF Foundation

GitHub: gayatrianne