Ops Copilot MCP Server — AI-Native Commerce Operations

Remotely hosted TypeScript Model Context Protocol (MCP) server for automated e-commerce payment-fulfillment discrepancy detection, root-cause investigation, and durable human-review escalation.

Hosted MCP Endpoint: https://ops-copilot-mcp.vercel.app/mcp
Health Check Endpoint: https://ops-copilot-mcp.vercel.app/health

1. Problem Statement & Solution

The Challenge

Online commerce businesses frequently rely on engineering teams to manually investigate and resolve operational problems across fragmented systems (payment gateways, ERP/order management, warehouse WMS, shipping carriers). Operations analysts lack direct diagnostic tools to answer questions like:

• Why was payment captured for an order that never shipped?

• Why is a fully refunded package still moving through DHL transit?

• Why did a customer receive an over-refund?

The Solution

Ops Copilot MCP makes operations teams independent by exposing 5 purpose-built, safe MCP tools to any AI client (Claude, Codex, Cursor, MCP Inspector). The server executes a complete operational workflow:

1. Detect: Automatically scan synthetic order data to surface payment-fulfillment anomalies (ops_list_discrepancies).

2. Retrieve: Fetch unified, cross-system timeline data for any order (ops_get_order_details).

3. Investigate: Run automated diagnostic reasoning to determine root cause (ops_investigate_discrepancy).

4. Escalate: File a durable, evidence-backed human-review ticket in external storage (ops_create_escalation).

5. Track: Query active escalation tickets and monitor resolution status (ops_get_escalations).

Related MCP server: Commerce Ops MCP Server

2. Hosted Endpoint & Quick Start

2.1 Connecting via MCP Inspector (No Local Setup Required)

To inspect and test the live server directly:

npx @modelcontextprotocol/inspector

In the Inspector browser UI:

1. Set Transport Type to HTTP / Streamable HTTP.

2. Set URL to https://ops-copilot-mcp.vercel.app/mcp.

3. Click Connect. All 5 registered tools will appear with full Zod schemas, descriptions, and annotations.

2.2 Local Development & Testing

# 1. Clone repository & install dependencies
npm install

# 2. Build TypeScript
npm run build

# 3. Run full Vitest test suite (34/34 passing)
npm run test

# 4. Start local development server (runs on http://localhost:3000/mcp)
npm run dev

3. MCP Capabilities & Tool Inventory

All tools use strict Zod validation (.strict()), include standardized MCP annotations (readOnlyHint, idempotentHint), and return structured JSON (structuredContent) along with clean human-readable markdown summaries.

4. Architecture & State Durability

                      ┌─────────────────────────────────────────┐
                      │  AI Consumer (Claude / MCP Inspector)   │
                      └────────────────────┬────────────────────┘
                                           │ Streamable HTTP (JSON-RPC)
                                           ▼
                      ┌─────────────────────────────────────────┐
                      │       Vercel Serverless Function        │
                      │        (TypeScript + Express)           │
                      └────────────────────┬────────────────────┘
                                           │ Upstash REST API
                                           ▼
                      ┌─────────────────────────────────────────┐
                      │   Upstash Redis (Durable KV Database)   │
                      └─────────────────────────────────────────┘

• Stateless Compute: Express application using @modelcontextprotocol/sdk with StreamableHTTPServerTransport hosted on Vercel Serverless Functions.

• Decoupled Durability: Per client requirements, escalation tickets are persisted to Upstash Redis REST API (@upstash/redis). This ensures created escalations survive serverless container cold starts and redeployments.

• Safety: Source commerce systems remain strictly read-only; mutations are restricted exclusively to escalation ticket creation.

5. Product Scoping, Assumptions & Tradeoffs

In Scope

• 5 core operational tools built on TypeScript SDK v1.6.1.

• Synthetic dataset containing 8 orders (3 healthy + 5 distinct discrepancy types).

• Rule-based diagnostic engine pinpointing root causes.

• Upstash Redis REST persistence for durable escalations.

• 10-question evaluation benchmark suite (docs/EVALUATION.xml).

Explicitly Out of Scope (Per Assignment Brief)

• Frontend or design system (MCP Inspector used as standardized UI).

• Authentication / user management (unauthenticated public demo endpoint per client Q&A answer #3).

• Mutation of underlying order/payment/fulfillment source systems.

• Production payment gateway or ERP webhooks.

6. Live Verification & Durability Retest Evidence

6.1 Automated Vitest Suite

✓ tests/services/discrepancy-detector.test.ts (3 tests)
✓ tests/services/investigation-engine.test.ts (6 tests)
✓ tests/services/escalation-store.test.ts (2 tests)
✓ tests/e2e/workflow.test.ts (1 test)
✓ tests/tools/tools.test.ts (4 tests)
✓ tests/e2e/evaluation.test.ts (10 tests)
✓ tests/tools/error-handling.test.ts (7 tests)
✓ tests/e2e/inspector-verification.test.ts (1 test)

Test Files  8 passed (8) | Tests  34 passed (34)

6.2 Cold-Start Durability Proof

1. Created record ESC-4001 on live endpoint (https://ops-copilot-mcp.vercel.app/mcp).

2. Triggered production deployment (npx vercel deploy --prod -y --no-wait), terminating previous runtime containers.

3. Fetched ESC-4001 after container replacement:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "escalation": {
        "escalation_id": "ESC-4001",
        "order_id": "ORD-1004",
        "discrepancy_type": "paid_not_shipped",
        "severity": "high",
        "diagnosis": "Paid but not shipped - verified via Upstash",
        "evidence": { "payment_id": "PAY-9999" },
        "status": "open",
        "created_at": "2026-08-02T07:57:59.822Z"
      }
    }
  }
}

Result: PASS — 100% data preservation across serverless cold start.

6.3 Evaluation QA Benchmark (docs/EVALUATION.xml)

All 10 complex multi-step operational queries executed against the live endpoint matched expected outputs with 100% accuracy (10/10 passed).

7. Requirements Traceability Summary

8. AI Worklog & Engineering Journal

8.1 AI Tools & Models Used

• Gemini 3.1 Pro: Initial requirements research, assignment analysis, and traceability matrix generation.

• Claude Opus 4.6 (Thinking): PRD drafting, MCP tool schema design (ops_*), annotations (readOnlyHint), and architecture design.

• Gemini 3.6 Flash: TypeScript code generation, Vitest test suite implementation, live deployment scripts, and empirical verification.

• TinyFish Agent / CLI: Web research, MCP standard verification, and Upstash Redis REST specs verification.

8.2 Human–AI Division of Responsibilities

• Product Decisions: AI proposed workflow candidates; Human selected payment-fulfillment discrepancy investigation.

• MCP Tool Design: AI drafted tool schemas & annotations per mcp-builder standards; Human approved tool list.

• Architecture & State: Human audited hosting cold-start behavior; AI implemented Upstash Redis REST external persistence.

• Code & Test Generation: AI generated implementation & 34 Vitest tests; Human reviewed every file and verified runtime behavior.

8.3 AI Suggestions Corrected (Key Engineering Pivot)

• Initial AI Proposal: Switch hosting provider from Vercel to Railway to avoid cold-start memory loss.

• Human Correction / Refinement: Research showed free-tier containers (including Railway idle sleep) can still cold-start. Instead of changing hosts, we externalized state persistence to Upstash Redis REST API (@upstash/redis), keeping the stateless compute on Vercel while guaranteeing true durability.

8.4 Verification & Remaining Risks

• Verification Result: 34/34 Vitest unit/integration tests passing. 10/10 evaluation benchmark QA pairs 100% matched against live server.

• Remaining Risks: None for submitted scope. Local dev falls back seamlessly to in-memory store if Upstash env vars are unset.