☁️ Claude in the Cloud

Run Claude CLI inside Kubernetes (AWS EKS or GCP GKE) with secure access to your codebase, documentation, and database — all wired together via MCP servers.

This allows you to have Claude constantly running, scanning newly created JIRA service requests, doing root cause analysis and writing mitigation steps.

This repository deploys:

• Claude CLI exposed through a FastAPI endpoint
• Two MCP servers (database + documentation/RAG)
• An automatic RAG system that dramatically narrows Claude’s search scope and reduces hallucinations

---

✨ What’s Included

🧠 MCP Servers

• mcp-db
  Connects Claude to your MySQL/Postgres database. Supports only safe, read-only operations:

  • SELECT
  • DESCRIBE
  • EXPLAIN

• mcp-documentation
  A RAG knowledge base built from your system’s technical documentation, schema, queries, and glossary.

🚀 Claude CLI Deployment

• Runs as a Kubernetes deployment
• Exposed via a FastAPI /ask endpoint
• Automatically:
  • Downloads your code
  • Configures authentication
  • Injects MCP connections
  • Applies a customizable system prompt

---

📁 Repository Structure

.
├── main/                 # Claude CLI + FastAPI (K8s deployment)
├── mcp-db/               # MCP server for DB access (MySQL/Postgres)
├── mcp-documentation/    # MCP server for RAG-based documentation search

---

🧭 How It Works (High Level)

1. You generate structured technical documentation
2. Documentation + schema are embedded into a RAG index
3. MCP servers expose DB + documentation via internal K8s services
4. Claude CLI connects to those services
5. You query Claude through a FastAPI endpoint

---

📝 Step 1: Generate Documentation

1.1 Technical Documentation

Generate technical documentation for each repository / microservice.

Recommended tools:

• Claude CLI
• Cursor

Guidelines:

• Output Markdown (.md)
• Use # headings generously (important for contextual chunking)

📂 Place the files in:

mcp-documentation/services/

---

1.2 Database Schema Documentation

1. Dump your database schema
2. Paste it into:

mcp-documentation/schema/

3. Use Claude CLI or Cursor to:
   • Analyze the schema dump
   • Generate a structured .md file
   • Split tables using # headings

Highly recommended (if you have time):

• Add table sizes next to each table definition

This helps Claude:

• Avoid full table scans
• Generate more efficient queries

---

1.3 Common Queries (Optional but Strongly Recommended)

Extract your most frequently used SQL queries:

• From application code
• Or via Claude CLI code search

📂 Place them in:

mcp-documentation/queries/

This allows Claude to:

• Semantically search real query examples
• Avoid hallucinated joins

---

1.4 Business Glossary

If your system uses domain-specific or business terms, document them.

📂 Place glossary files in:

mcp-documentation/glossary/

---

1.5 Generate RAG Indexes

Once all documentation is in place, instruct Claude CLI to:

generate indexes

This will:

1. Chunk the documentation
2. Embed it using BGE-large-en-v1.5
3. Enable fast semantic search

---

🔐 Step 2: Configure Database Access

Inside mcp-db, configure:

• Database URL
• Credentials

Security Notes

• MCP enforces intent checks (only SELECT, DESCRIBE, EXPLAIN)
• Strongly recommended:
  • Use a read-only DB user
  • Connect to a read replica if available

---

☸️ Step 3: Deploy MCP Servers

Deploying the MCPs creates:

• A Kubernetes Deployment
• A Kubernetes Service (ClusterIP)

⚠️ Services are not exposed publicly for security reasons

Internal Service URLs

After deployment, note the internal service URLs:

http://mcp-documentation.mcp.svc.cluster.local:20124/sse
http://mcp-mysql-server.mcp.svc.cluster.local:20123/sse

Add these URLs to:

entrypoint.sh

They will be injected into Claude’s internal configuration during deployment.

---

🤖 Step 4: Deploy Claude CLI

Location

Claude CLI lives in:

main/

What the Deployment Does

• Deploys Claude CLI as a K8s workload
• Exposes a FastAPI endpoint
• Downloads your Bitbucket repositories
• Configures authentication
• Injects MCP connections
• Applies systemprompt.md

Required Kubernetes Secrets

ANTHROPIC_API_KEY     # Claude API key
BITBUCKET_SSH_KEY    # SSH private key for Bitbucket service account

---

🧪 Using Claude

Once deployed, you can interact with Claude via:

POST /ask

The endpoint:

• Invokes Claude CLI
• Uses your codebase
• Queries documentation via RAG
• Queries the database safely via MCP

---

✅ Result

You now have:

• Claude running inside your cloud
• Context-aware, schema-aware, query-aware AI
• Strong guardrails against hallucinations
• Zero public exposure of internal services

---

Adam Stanic Backend / AWS / ML engineer

🔗 LinkedIn: linkedin.com/in/adam-stanic-234284147

✍️ Medium: https://medium.com/@stanic.adam

📧 Email: stanic.adam@yahoo.com