RA-Nested-MCP

A nested MCP (Model Context Protocol) system demonstrating MCP composition over HTTP/SSE — a server that is simultaneously a client to three other MCP servers.

This started as a fork of Origin-Digital-LLC/nested-mcps (a generic "Acme Robotics" RAG demo, re-plumbed to run without Azure) adapted to telecom Revenue Assurance, and has since grown from a pure knowledge agent into a full Telecom Revenue Assurance Analytics & Intelligence Platform: structured data + statistics + forecasting sit alongside the original RAG knowledge base, orchestrated by the same agentic loop.

Architecture

Claude Desktop
     │  stdio
     ▼
[stdio proxy]              ← spawned by Claude Desktop, bridges stdio ↔ HTTP
     │  HTTP/SSE (:8002)
     ▼
MCP 2: Orchestrator        ← FastAPI/uvicorn. Agentic loop (Llama 3.3 70B via Groq).
     │                        Decides which of the three data sources below to call,
     │                        for none/one/many depending on the question.
     ├── HTTP/SSE (:8001) → MCP 1: Vector Store    (RAG knowledge base)
     ├── HTTP/SSE (:8003) → MCP 3: Analytics        (structured RA data: KPIs,
     │                                                anomalies, hypothesis tests,
     │                                                correlation, segmentation)
     └── HTTP/SSE (:8004) → MCP 4: Forecasting      (Holt-Winters revenue_leakage
                                                       forecast, model comparison)

MCP 1 (mcp1_vectorstore) — unchanged from the original. A low-level in-memory vector store: embeds 10 Revenue Assurance documents locally via sentence-transformers at startup, serves semantic search via numpy cosine similarity. Internal only, never exposed directly.

MCP 2 (mcp2_orchestrator) runs the agentic reasoning loop using Llama 3.3 70B via Groq's free API tier. It exposes a single ask tool via HTTP/SSE, decomposes questions into tasks, and calls MCP 1/3/4 as needed — the system prompt instructs it to use the minimum set of tools for a given question (a "what does CRMS mean" question never touches MCP 3/4; a "why did leakage spike and what's next" question uses all three). Independent tool calls within one turn are dispatched in parallel via asyncio.gather.

MCP 3 (mcp3_analytics) — new. Loads cdr_transactions.csv / daily_ra_metrics.csv / operational_events.csv (or their cleaned/aggregated Parquet equivalents) into pandas at startup and exposes 11 tools: KPI computation, descriptive stats, z-score/IQR anomaly detection, incident pre/during/post analysis, auto-selected hypothesis testing (Welch's t-test or Mann-Whitney U based on sample size/normality), Pearson/Spearman correlation, and segmentation by region/service/network/plan. Internal only.

MCP 4 (mcp4_forecasting) — new. Fits Holt-Winters (additive damped trend + weekly seasonality) on the revenue_leakage series and exposes forecasting, chronological-holdout model comparison against a seasonal-naive baseline, day-by-day accuracy, and Monte-Carlo-simulated prediction intervals. Internal only.

The proxy (extension/server/proxy.py) is a thin stdio↔HTTP bridge, unchanged. Claude Desktop spawns it locally; it connects to MCP 2 over the network. This is the only piece that runs on client machines.

Related MCP server: acme-mcp

Project Structure

src/
├── mcp1_vectorstore/
│   ├── documents.py      # Revenue Assurance knowledge base (10 docs)
│   ├── settings.py       # embedding_model, port
│   └── server.py         # FastAPI/SSE: search + list_documents tools
├── mcp2_orchestrator/
│   ├── settings.py       # groq_api_key, groq_model, mcp1_url, mcp3_url, mcp4_url
│   ├── mcp1_client.py    # HTTP/SSE client wrapping MCP 1
│   ├── mcp3_client.py    # HTTP/SSE client wrapping MCP 3 (generic call_tool)
│   ├── mcp4_client.py    # HTTP/SSE client wrapping MCP 4 (generic call_tool)
│   ├── agent.py          # Agentic loop: scratchpad, task planning, parallel tool dispatch
│   └── server.py         # FastAPI/SSE: exposes the ask tool
├── mcp3_analytics/
│   ├── data_access.py    # Loads/caches the three RA datasets
│   ├── analytics.py      # KPIs, anomaly detection, hypothesis tests, correlation, segmentation
│   ├── settings.py       # port
│   └── server.py         # FastAPI/SSE: 11 analytics tools
└── mcp4_forecasting/
    ├── data_access.py    # Loads/caches the revenue_leakage time series
    ├── forecasting.py    # Holt-Winters, seasonal-naive baseline, chronological evaluation
    ├── settings.py       # port
    └── server.py         # FastAPI/SSE: 4 forecasting tools
data/
├── raw/                  # cdr_transactions.csv, daily_ra_metrics.csv, operational_events.csv
└── processed/            # cleaned/aggregated Parquet versions
tests/
├── test_analytics.py     # unit tests for mcp3_analytics.analytics (pytest)
└── test_forecasting.py   # unit tests for mcp4_forecasting.forecasting (pytest)
extension/
├── manifest.json         # Claude Desktop Extension manifest
└── server/
    └── proxy.py          # stdio ↔ HTTP/SSE bridge (runs on client machines)

Server Setup

1. Install dependencies

uv sync

The first run of MCP 1 will download the all-MiniLM-L6-v2 model (~90MB) from Hugging Face automatically — this requires network access once, then it's cached locally and runs fully offline.

2. Configure environment

cp .env.example .env
# Fill in your GROQ_API_KEY (free — get one at https://console.groq.com, no card required)

No Azure account, no paid API billing — this project runs entirely on free tiers (Groq's free API + a locally-run embedding model).

3. Start the servers

In four separate terminals (MCP 1, 3, 4 must be up before MCP 2 receives a request — MCP 2 lazily connects to each on demand, so exact startup order between 1/3/4 doesn't matter, but all three should be running before you ask):

make run-mcp1   # vector store  (RAG)          on http://0.0.0.0:8001
make run-mcp3   # analytics     (structured RA) on http://0.0.0.0:8003
make run-mcp4   # forecasting   (revenue_leakage) on http://0.0.0.0:8004
make run-mcp2   # orchestrator  (the one exposed to clients) on http://0.0.0.0:8002

MCP 3 and MCP 4 read from data/raw/ and data/processed/ relative to the repo root — populate those with your cdr_transactions.csv / daily_ra_metrics.csv / operational_events.csv (and optionally the cleaned Parquet versions, which are preferred when present) before starting them.

Connecting Claude Desktop (local dev)

Run make claude-config to print the config block, then paste it into %APPDATA%\Claude\claude_desktop_config.json and restart Claude Desktop.

This spawns proxy.py via WSL, which connects to MCP 2 over HTTP. Both servers must be running first.

Enterprise Deployment (claude.ai)

For enterprise claude.ai, no proxy or client-side installation is needed:

1. Deploy MCP 2 on an internal server with a publicly reachable HTTPS URL

2. An org admin adds the URL once: claude.ai → Settings → Connectors → Add custom connector

3. Users click to enable it — no URL entry, no configuration

MCP 1 stays internal; only MCP 2 needs to be reachable from Claude's servers (claude.ai's connector infrastructure).

Distributing via Claude Desktop Extension (.mcpb)

Any Claude Desktop user — not just local dev — needs the proxy to connect to an internal server, since Claude Desktop only speaks stdio. The .mcpb packages the proxy and all Python dependencies into a one-click install.

make pack   # produces ra-orchestrator-proxy.mcpb

Before packing, update MCP2_URL in extension/manifest.json to point at your internal server. Distribute the .mcpb to users — they double-click it in Windows Explorer and Claude Desktop installs it automatically.

Tools

MCP 1 tools (internal, HTTP only)

MCP 3 tools (internal, HTTP only)

MCP 4 tools (internal, HTTP only)

MCP 2 tool (exposed via HTTP/SSE)

Agentic Loop

The agent in agent.py maintains a per-request scratchpad:

{
  "question": str,
  "tasks": [{"id", "description", "status", "depends_on", "result"}],
  "final_answer": str | None
}

The LLM drives the loop using four internal tools: add_task, complete_task, search_knowledge, and finish. Tasks with satisfied dependencies are dispatched concurrently. The loop is hard-capped at 10 iterations.

Test Questions

Knowledge-only (MCP 1)

These require multi-hop retrieval over the Revenue Assurance knowledge base — not derivable from any LLM's training data alone, since they depend on the specific document set in documents.py.

Sequential (two-hop):

"What is the relationship between CRMS and RMS, and how does a mismatch between them lead to revenue leakage?"

Parallel + synthesis:

"Compare where leakage originates in rating/mediation versus what CPI validation is meant to prevent — how do these two failure points differ?"

Multi-hop stretch:

"Walk through how a duplicate CDR moves through the ETL pipeline and which stage should catch it, then explain how that failure would show up in the RA KPIs."

Data-only (MCP 3 / MCP 4)

"What was our revenue leakage last month, and how does it compare to the month before?" (descriptive → get_ra_summary/get_kpi_metrics)

"Which days in the last quarter were statistically anomalous for revenue leakage?" (anomaly → detect_anomalies)

"Which region contributes the most revenue leakage, and is the problem concentrated in 5G?" (segmentation → analyze_by_region, analyze_by_network)

"What do you expect revenue leakage to look like over the next 30 days?" (forecast → forecast_revenue_leakage)

Combined — the main demonstration (MCP 1 + MCP 3 + MCP 4)

"Revenue leakage increased significantly last month. What caused it, what does our RA documentation say about the likely causes, and what do you forecast for the next 30 days?"

This should route through: detect_anomalies/get_revenue_leakage_trend (confirm the increase and locate it in time) → analyze_incident (check for a coinciding operational event) → run_hypothesis_test (statistical significance) → search_knowledge (why that failure mode causes leakage, in general) → forecast_revenue_leakage (what's next) → a synthesized answer separating observed facts, statistical evidence, retrieved domain knowledge, the forecast, and recommendations.

Testing

Unit tests cover the analytics and forecasting logic directly (no server required):

uv run pytest tests/ -v

Integration smoke tests exercise each server over real HTTP/SSE (server must be running first):

make run-mcp1 &   # or mcp3 / mcp4
uv run python test_ask.py         # MCP 2 → MCP 1
uv run python test_analytics.py   # MCP 3 directly
uv run python test_forecast.py    # MCP 4 directly

make check verifies .env is present and all four settings classes load without error.

Credits

Original architecture and implementation: Origin-Digital-LLC/nested-mcps. This fork adapts the domain to telecom Revenue Assurance, swaps Azure OpenAI for local embeddings (sentence-transformers) + Groq's free API tier, and extends the original two-layer knowledge agent into a four-server platform combining RAG, structured analytics, and time-series forecasting — the whole project still runs at zero cost.