🔧 Nimbus MCP Server

Standalone Model Context Protocol (MCP) server for the Nimbus Furniture platform.

Provides live user account lookup tools over HTTP, consumed by the nimbus_agent AI support agent.

---

What is this?

The nimbus_mcp service is a lightweight, independently deployable HTTP server that exposes two tools via FastMCP:

Tool	Description
get_user_by_email	Look up a Nimbus customer account by email address
get_user_account_status	Retrieve plan type, account status, and plan details by user ID

The agent calls these tools at runtime over HTTP using the MCP protocol — keeping live user data completely separate from the AI agent logic.

---

Project Structure

nimbus_mcp/
├── server.py          # FastMCP server — defines and exposes MCP tools
├── data/
│   └── users.json     # Nimbus customer database (8 mock users)
├── requirements.txt   # Minimal dependencies (fastmcp, mcp, python-dotenv)
├── .gitignore
└── README.md

---

Tools Exposed

get_user_by_email(email: str) → dict

Looks up a customer by their email address.

Returns:

{
  "found": true,
  "id": "usr_001",
  "name": "Sarah Chen",
  "email": "sarah.chen@example.com",
  "plan": "premium",
  "account_status": "active",
  "last_login": "2026-08-03T10:22:14Z",
  "created_at": "2024-03-15T08:00:00Z",
  "total_orders": 12,
  "store_credit": 25.00
}

If not found:

{ "found": false, "error": "No Nimbus Furniture account found for email: x@x.com" }

---

get_user_account_status(user_id: str) → dict

Returns plan and status details for a user by ID.

Returns (Free plan):

{
  "found": true,
  "id": "usr_002",
  "name": "James Patel",
  "plan": "free",
  "account_status": "active",
  "plan_details": "Nimbus Free: standard shipping rates apply, White Glove Delivery available for $49/item, regular support. Upgrade to Nimbus Premium for $9.99/month..."
}

Returns (Premium plan):

{
  "found": true,
  "id": "usr_001",
  "name": "Sarah Chen",
  "plan": "premium",
  "account_status": "active",
  "plan_details": "Nimbus Premium: free standard shipping on all furniture orders, free White Glove Delivery & assembly on large items, 10% member discount..."
}

Returns (Suspended):

{
  "found": true,
  "id": "usr_004",
  "name": "Derek Kim",
  "plan": "free",
  "account_status": "suspended",
  "suspension_reason": "Payment dispute — account under review",
  "plan_details": "..."
}

---

Setup

1. Prerequisites

• Python 3.10+

2. Create a virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables (optional)

The only configurable variable is the port. Create a .env file if needed:

MCP_SERVER_PORT=8001

The default port is 8001 if not set.

---

Running Locally

python server.py

The MCP server starts at:

http://127.0.0.1:8001/mcp

To verify it's running, check the console output:

INFO:     Started server process
INFO:     Uvicorn running on http://127.0.0.1:8001

⚠️ Always start nimbus_mcp before nimbus_agent. The agent connects to this server on startup and falls back to RAG-only mode if it can't reach it.

---

Deploying to Render

Deploy as a Web Service from your GitHub repo:

Setting	Value
Root Directory	nimbus_mcp
Build Command	pip install -r requirements.txt
Start Command	python server.py
Port	8001

Environment variable to set in Render dashboard:

MCP_SERVER_PORT=8001

After deploying, copy the public URL (e.g. https://nimbus-mcp.onrender.com) and set the following in your nimbus_agent Render service:

MCP_SERVER_URL=https://nimbus-mcp.onrender.com/mcp

⚠️ Deploy nimbus_mcp first, then deploy nimbus_agent. The agent needs the MCP URL to be live at startup.

---

Updating the User Database

The user data lives in data/users.json. Each user record follows this schema:

{
  "id": "usr_001",
  "email": "user@example.com",
  "name": "Full Name",
  "plan": "premium | free",
  "account_status": "active | suspended",
  "last_login": "2026-08-03T10:22:14Z",
  "created_at": "2024-03-15T08:00:00Z",
  "total_orders": 12,
  "store_credit": 25.00,
  "suspension_reason": "Optional — only present if account_status is suspended"
}

After editing users.json, restart the server — the file is loaded once at startup.

---

Mock Users (for testing)

Email	Plan	Status
sarah.chen@example.com	Premium	Active
james.patel@example.com	Free	Active
maria.gonzalez@example.com	Premium	Active
derek.kim@example.com	Free	Suspended
linda.wu@example.com	Premium	Active
tom.nguyen@example.com	Free	Active
aisha.johnson@example.com	Premium	Active
carlos.rivera@example.com	Free	Active

---

Requirements

fastmcp>=2.0.0
mcp>=1.0.0
python-dotenv>=1.0.0

---

License

MIT — free to use, modify, and extend.