AWS MCP/GraphRAG Migration — Executive Overview

Date: April 23, 2026 Author: Terry McGuinness, NOAA NWS POCAI Software Engineering Status: Active migration — OpenSearch operational, Neptune recovery in progress

---

Why Move to AWS?

The MDC MCP RAG Server has been running on a NOAA Parallel Works (COTS) VM since January 2026, using Docker Compose to orchestrate ChromaDB (vector search), Neo4j (graph database), and a Node.js MCP server. This architecture proved the concept and delivered production-quality AI-assisted development tooling for the Global Workflow. However, it has inherent limitations that AWS-native services resolve:

Concern	Parallel Works (Docker)	AWS Native
Persistence	Docker volumes on a single VM — data loss risk on reprovisioning	Managed services with automated backups, multi-AZ
Scaling	Single container per service, manual restart	ECS Fargate auto-scaling 1–4 tasks, managed by AgentCore
Security	SSH tunnels, manual port forwarding	Private API Gateway, VPC endpoints, no internet exposure
IaC	Docker Compose YAML, systemd units	AWS CDK stacks, CloudFormation-managed lifecycle
Observability	Manual log inspection, custom health scripts	CloudWatch dashboards, X-Ray tracing, automated alarms
Multi-user	Docker MCP Gateway with container-per-session overhead	AgentCore Runtime with microVM session isolation
Cost transparency	Flat VM cost, no per-service visibility	Per-service billing, cost allocation tags

The migration preserves every tool and capability while gaining enterprise-grade reliability, security, and scalability.

---

What We Built

The Platform: 51+ MCP Tools Across 9 Modules

The MCP/RAG server provides AI-powered development assistance for the NOAA Global Workflow — one of the most complex computational weather forecasting systems on Earth. It exposes 51+ tools via the Model Context Protocol, organized into 9 functional modules:

Module	Tools	Purpose
Workflow Info	3	System architecture, platform configs, component descriptions
Code Analysis	5	Graph-based dependency mapping, call chain tracing, cross-language bridges
Semantic Search	6	Hybrid vector+graph search across 86K+ documents and 35 documentation sources
EE2 Compliance	4	NCEP operational standards validation with SME-trained anti-pattern detection
Operational	3	HPC procedures, J-Job explanations, graph-enriched component analysis
GitHub Integration	4	Issue search, PR tracking, cross-repo dependency analysis
SDD Workflow	9	Spec-Driven Development session tracking, execution history, compliance
GraphRAG	5	Code context retrieval, architecture search, similar code discovery, change impact
Utility	3	Server health, quality metrics, knowledge integrity monitoring

The Knowledge Base

Store	Technology	Content
Vector (semantic search)	OpenSearch (AWS) / ChromaDB (legacy)	85,921+ documents across 6 collections
Graph (code structure)	Neptune (AWS) / Neo4j (legacy)	59,759 nodes, 2.6M+ relationships
Documentation sources	35 crawled sources	ESMF, NUOPC, MOM6, CICE, WW3, CCPP, METplus, NCEPLIBS, and more

The graph captures the full structure of the Global Workflow codebase: Fortran subroutines, Python modules, Shell scripts, J-Jobs, environment variable dependencies, and cross-language execution bridges (Shell→Fortran, Shell→Python). Hierarchical community detection (Leiden algorithm) produced 2,113 LLM-generated summaries enabling multi-resolution architectural understanding.

---

Infrastructure as Code with LLM Assistance

A core principle of this migration is IaC-first: all AWS infrastructure is defined and deployed via code, never through manual console changes. We use AWS CDK (TypeScript) for infrastructure definition and CloudFormation as the deployment mechanism.

What makes this approach distinctive is the integration of LLM-powered tools directly into the IaC workflow:

CDK Development with Kiro Powers

Three AWS-authored Kiro Powers provide real-time AI assistance during infrastructure development:

• AWS Infrastructure as Code Power — searches CDK documentation, validates CloudFormation templates with cfn-lint, checks security compliance with cfn-guard, and troubleshoots failed deployments with pattern matching against 30+ known failure cases
• IAM Policy Autopilot Power — analyzes application source code to generate least-privilege IAM policies, and troubleshoots access denied errors with automated remediation
• AWS Bedrock AgentCore Power — provides documentation search, runtime management, and deployment tooling for the AgentCore serverless hosting platform

CDK Safety Guardrails

Automated guardrails enforce data safety during infrastructure changes:

• Agent hooks trigger cdk diff review before any deployment
• CDK assertion tests verify DeletionPolicy: Retain on all stateful resources
• Steering rules enforce the two-step pattern for resource migration (deploy RETAIN first, then remove)
• Pre-deploy checklists are embedded in the development workflow

The Adapter Pattern

The data access layer uses an adapter pattern that allows the same 51+ tools to run against either backend:

UnifiedDataAccess
  ├── DB_BACKEND=legacy → ChromaDB + Neo4j (Parallel Works)
  └── DB_BACKEND=aws    → OpenSearch + Neptune (AWS)

Zero tool module files were modified. All tools work identically in both modes.

---

Current Status

What's Working

Component	Status	Details
OpenSearch (vector search)	✅ Operational	85,921 docs across 17 indices, hybrid BM25+kNN search
CDK Stacks	✅ Deployed	4 stacks: VPC, Security, Data, Server
Adapter Pattern	✅ Complete	All 51 tools validated against AWS backends
Bedrock Titan Embeddings	✅ Ingested	1024-dim Titan Embed V2 across 5 indices
VPC Endpoints	✅ Configured	10 endpoints, fully private networking
AgentCore Entrypoint	✅ Built	MCP protocol server ready for deployment
Kiro Powers	✅ Active	IaC, IAM, and AgentCore powers connected
Node.js 20	✅ Upgraded	Required for @aws/agentcore CLI

Migration Metrics

Metric	Legacy (PW)	AWS	Parity
Vector documents	85,995	85,921	99.9%
Graph nodes	95,565	59,759 (deduplicated)	✅
Graph relationships	2,635,130	2,633,374	99.9%
Tool count	51	51	100%
Validation pass rate	—	45/45 non-GitHub tools	100%

Benchmark Results (Titan 1024-dim Hybrid Search)

Metric	Score
Precision@5	0.267
Precision@10	0.196
MRR	0.511
nDCG	0.536
Hybrid search latency (p50)	117ms

Next Steps

1. AgentCore Runtime Deployment — Deploy the MCP server to Bedrock AgentCore as a managed MCP protocol service (Phase 51b, spec complete)
2. Neptune Graph Recovery — Restore graph data from S3 bulk load into the surviving cluster (Phase 53, admin role reattachment pending)
3. Incremental Re-Ingestion — Update graph to reflect source tree changes since April 7 (Phase 53 Track B)
4. Production Cutover — Switch Kiro from legacy MCP to AWS endpoint, retire dev bridge

---

SDD Track Record

All development follows Spec-Driven Development (SDD): "If it's not in the SDD, it doesn't get coded."

Metric	Value
SDD Sessions Completed	26+
Sessions Abandoned	0 (100% completion rate)
Total Steps Executed	219+
Phases Completed	53 (Phase 48–53 are AWS port)

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│  Kiro IDE (EC2 instance, private subnet)                    │
│  ├── aws-infrastructure-as-code Power (CDK/CFN tools)       │
│  ├── iam-policy-autopilot Power (IAM policy generation)     │
│  ├── aws-agentcore Power (Runtime deployment)               │
│  └── eib-mcp-gateway (legacy PW system, reference)          │
└──────────────────────┬──────────────────────────────────────┘
                       │ MCP Protocol
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  AgentCore Runtime (Bedrock, MCP protocol, :8000/mcp)       │
│  └── MDC MCP RAG Server (Node.js, 51+ tools)                │
│       ├── Semantic Search → OpenSearch (85,921 docs)        │
│       ├── Graph Analysis  → Neptune (59K nodes, 2.6M rels)  │
│       └── Health/SDD/EE2  → Local state + S3                │
└─────────────────────────────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
   ┌─────────┐  ┌───────────┐  ┌──────────┐
   │ Neptune │  │OpenSearch │  │    S3    │
   │ (Graph) │  │ (Vector)  │  │(Migration│
   │ VPC-only│  │ VPC-only  │  │  + Logs) │
   └─────────┘  └───────────┘  └──────────┘

All components run in private subnets with no internet exposure. Communication uses VPC endpoints exclusively.

---

Cost Profile

Service	Monthly Estimate
Neptune (db.r5.large)	~$280
OpenSearch (r6g.large.search)	~$150
ECS Fargate / AgentCore	~$50–100
S3 + CloudWatch + misc	~$15–25
Total	~$500–555/month

Compared to the Parallel Works VM cost, this provides managed backups, multi-AZ resilience, auto-scaling, and full observability at a comparable price point.