Servicios BAU empresariales con MCP y Gemini

Una prueba de concepto ejecutable que muestra cómo un agente de IA puede trabajar con microservicios REST existentes de operaciones habituales (BAU) a través del Model Context Protocol (MCP).

La demostración utiliza Google Gemini para descubrir herramientas MCP, recuperar información de clientes y pedidos, y realizar una acción controlada de cancelación de pedidos. Los servicios BAU siguen siendo API REST independientes; MCP proporciona la frontera de integración entre esas API y el agente.

Demostración

El escenario incluido pide al agente:

1. Recuperar el perfil de CUST-1001.

2. Listar los pedidos del cliente.

3. Identificar el pedido en estado Processing.

4. Cancelar ORD-9002 con un motivo proporcionado.

5. Resumir el trabajo completado.

La secuencia de herramientas esperada es:

Gemini agent
    -> MCP tool discovery over stdio
    -> MCP server
    -> Customer and Order REST APIs
    -> Tool results returned to Gemini
    -> Final user-facing summary

Related MCP server: MCP API Tool Demo

Arquitectura

+------------------+       stdio        +------------------+       HTTP       +----------------------+
| Gemini agent     | <----------------> | MCP server       | <--------------> | Customer service     |
| agent_runner.py  |                    | server.py        |                  | localhost:8001       |
+------------------+                    +--------+---------+                  +----------------------+
                                                   |
                                                   | HTTP
                                                   v
                                         +----------------------+
                                         | Order service        |
                                         | localhost:8002       |
                                         +----------------------+

Herramientas MCP

Estructura del proyecto

.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference

Requisitos previos

• Python 3.11 o más reciente

• Una clave de API de Gemini de Google AI Studio

• Windows PowerShell, shell de macOS/Linux o un terminal equivalente

• Acceso de red a la API de Gemini al ejecutar el agente

Este proyecto no requiere una clave de API de Anthropic ni de OpenAI.

Inicio rápido en Windows

Abra PowerShell en el directorio del proyecto:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Abra .env y reemplace your_gemini_api_key_here con su clave:

GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash

Nunca haga commit de .env ni coloque una clave de API en el código fuente. El modelo seleccionado debe estar disponible para su cuenta de Gemini.

Ejecutar la demostración

Use tres terminales. Active .venv en cada terminal.

Terminal 1: servicio de clientes

python services/customer_service.py

Se ejecuta en http://localhost:8001.

Terminal 2: servicio de pedidos

python services/order_service.py

Se ejecuta en http://localhost:8002.

Terminal 3: agente Gemini

python agent/agent_runner.py

El agente inicia el servidor MCP como un proceso hijo, descubre sus herramientas y ejecuta el flujo de trabajo de ejemplo.

Verificar los servicios locales

Ejecute estos comandos mientras los dos servicios están activos:

Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001

Ejecutar las pruebas

Con el entorno virtual activo:

python -m pytest -q

Las pruebas cubren la búsqueda de clientes sin distinción de mayúsculas y minúsculas, clientes inexistentes, la cancelación de un pedido en proceso y la protección contra la cancelación de un pedido enviado.

Configuración

Alcance y limitaciones

Este es un POC local, intencionadamente pequeño, pensado para que el patrón de integración sea fácil de inspeccionar y ejecutar.

• Los registros de clientes y pedidos se almacenan en memoria y se restablecen cuando los servicios se reinician.

• Los servicios no implementan autenticación ni autorización.

• La operación de cancelación debería estar protegida por controles de aprobación y políticas de negocio en un sistema real.

• MCP utiliza stdio para la integración local de procesos. Una arquitectura desplegada debería utilizar un transporte de red autenticado.

• Los errores posteriores se devuelven como texto de herramienta para su visibilidad; los sistemas de producción deberían usar errores estructurados, reintentos, trazado y métricas.

• El agente de ejemplo realiza una solicitud real a la API de Gemini y requiere una clave válida.

Solución de problemas

GOOGLE_API_KEY is not set

Confirme que .env existe en el directorio del proyecto y contiene una clave válida. Ejecute el agente desde el directorio del proyecto.

404 NOT_FOUND para un modelo de Gemini

Establezca GEMINI_MODEL en .env a un modelo habilitado para su cuenta. El valor predeterminado en este POC es gemini-3.6-flash.

Fallo en el inicio de MCP o en el descubrimiento de herramientas

Confirme que las dependencias se instalaron en el entorno virtual activo:

python -m pip install -r requirements.txt

El proyecto fija MCP al rango de API 1.x porque la implementación del servidor usa FastMCP.

Errores de conexión de las herramientas MCP

Confirme que ambos servicios REST se están ejecutando en los puertos 8001 y 8002. Si un puerto ya está en uso, actualice el puerto del servicio y la URL correspondiente en .env.

Lecturas adicionales

• Detalles de acceso a LLM

• Plan detallado del POC