Controlled Agentic Operations Assistant

A minimal end-to-end operations agent using Groq, MCP, live business APIs, and deterministic refund guardrails.

Architecture

Browser
  ↓
Chat/session layer
  ↓
Groq agent
  ↓
MCP client/server
  ↓
Deterministic integration guardrail
  ↓
Order / CRM / Policy systems

MCP lets the agent dynamically discover standardized tools instead of directly knowing each external system's API. The MCP server exposes live order details, customer profiles, and the guarded refund operation.

Related MCP server: commerce-ops-mcp

Services

• Order API: src/backend.ts on port 3000

• CRM API: src/crm-backend.ts on port 3001

• Authoritative Policy API: src/policy-service.ts on port 3002

• Chat server and browser UI: src/chat-server.ts on port 8080

Safety model

1. The current refund policy is supplied to the LLM context so the model can plan sensible actions.

2. The deterministic integration and policy layer prevents MANUAL_REVIEW and BLOCK decisions from issuing refund writes.

3. The external Order API independently validates every refund as the final business-system safeguard.

The Policy API is authoritative. The application caches its refund policy for 60 seconds and refreshes it when stale.

Session memory

The LLM is stateless. The chat server stores only user messages and final assistant replies in an in-process session array, then resends that history for each model call. System prompts, MCP calls, and tool results are not persisted.

Live order and customer state is never trusted from conversation memory; MCP tools fetch it from the external systems each time.

Run

Requires Node.js 20 or later and a Groq API key.

npm install

Start each process in a separate terminal:

npm run order
npm run crm
npm run policy

Then set the key and start the chat server.

PowerShell:

$env:GROQ_API_KEY = "your-key"
npm run chat

macOS/Linux:

export GROQ_API_KEY="your-key"
npm run chat

Open http://localhost:8080.

Demo prompts

• Handle the refund for order 101. → ALLOW, refund executed

• Handle the refund for order 102. → MANUAL_REVIEW, no refund write

• Refund order 103. → BLOCK, no refund write

Multi-turn example:

1. Check order 102.

2. Can you refund it?

Sessions and seeded business data are in memory and reset when their respective processes restart.