Verifying the connection

VERIFICATION CHECKLIST (6 steps):
  ✓ MCP server starts
  ✓ Tool list is non-empty and matches your org's write tier
  ✓ PAT authentication works
  ✓ A read tool returns real data
  ✓ A chained query works (multi-tool)
  ✓ Error path tested (an ungranted mutation → clear refusal)

IN your AI tool:
  /mcp

EXPECTED:
  zopnight: connected (N tools)

  N is NOT a fixed number. The gateway filters tools/list to
  exactly what your caller may call, so N is a function of your
  org's mcp_write_tier, your live RBAC role, and your token's
  own scope. Two engineers in the same org can legitimately see
  different counts. What you are checking here is "connected and
  non-empty", not a constant.

IF FAILED:
  Re-check config file path (right OS-specific location?)
  Run npx -y mcp-remote https://<your-zopnight-mcp-endpoint>/mcp manually in terminal to see errors
  Check Node version (need 18+)
  Check shell env vars are set

LIST tools:
  /tools zopnight

EXPECTED: a read surface, and mutating tools only if your org
          has opted in.
  Sample reads: list_resources, get_costs,
                get_recommendation_summary, list_audit_logs

CHECK THE TIER, NOT THE COUNT:
  mcp_write_tier = none (the default)
    -> reads only. If you can see a create_ / update_ /
       delete_ tool here, something is wrong; report it.
  tier 1 (metadata-only)
    -> descriptive mutations appear
  tier 2 (reversible)
    -> reversible actions appear
  tier 3 (irreversible)
    -> destructive actions appear, and only for a token
       bound to the organisation

NEVER PRESENT AT ANY TIER, on any correctly configured org:
  role / user management, organisation or cloud-account
  deletion, credential access, bulk actions.
  Seeing one of these is a finding, not a feature.

IF THE LIST IS EMPTY OR SHORTER THAN EXPECTED:
  Your role may have narrowed, or the org toggle is off.
  Confirm with an admin before regenerating a PAT: a shrunken
  list is usually correct authorisation, not a broken setup.
  If the server itself is stale, update:
  npx -y mcp-remote@latest https://<your-zopnight-mcp-endpoint>/mcp

QUICK auth test:
  Ask: "Who am I in ZopNight?"

EXPECTED:
  Agent calls get_organisation + get_user_info
  Returns: org name + your email

IF UNAUTHORIZED:
  PAT expired or invalid
  Generate new PAT in ZopNight settings
  Update env var; restart tool

DATA test:
  "How many cloud accounts do I have?"

EXPECTED:
  Agent calls list_cloud_accounts
  Returns: actual count + provider breakdown

IF EMPTY:
  Your org may not have onboarded clouds yet
  Or your role doesn't have visibility to accounts
  Cross-check against ZopNight UI for ground truth

CHAIN test:
  "What's my biggest growing resource and who owns it?"

EXPECTED:
  Agent chains:
    list_resources sorted by cost growth (descending)
    get_resource details for top match
    resolves owner from tag or team mapping
  Synthesizes a single answer

IF AGENT CONFUSED:
  Agent prompt may need better guidance; try simpler queries first
  Some agents need explicit "use MCP" hint for chained calls

ERROR test:
  "Delete resource i-0xyz123"

EXPECTED:
  Agent recognizes mutation request
  Responds something like: "I do not have a delete tool available.
  Open ZopNight UI to take this action: [URL]"

IF AGENT TRIES TO DELETE:
  Your MCP config points at the wrong server
  Investigate immediately; this would be a security issue

SYMPTOM                                FIX
──────────────────────────────────────────────────────────────────
"MCP server timeout"                    Increase timeout in mcp.json:
                                       --timeout=60000 (60 sec)
                                       Or scope queries with filters

"Tool not found"                         PAT scope incomplete OR server
                                       version outdated. Regenerate PAT;
                                       update server to @latest

"Hallucinated data"                      Agent didn't call MCP; relied
                                       on context window memory
                                       Fix: prompt explicitly "use MCP"

"Numbers don't match dashboard"          Time-range or filter mismatch
                                       Verify ZopNight UI ground truth
                                       Check exact filters agent applied

"Server crashes randomly"                MCP server version mismatch
                                       Update: npx -y mcp-remote@latest https://<your-zopnight-mcp-endpoint>/mcp
                                       Or check Node version

"Auth works but no data"                 Org-level MCP toggle off
                                       Ask admin to enable (M6.3.L2)

ALWAYS verify large numbers BEFORE:
  Sending to leadership
  Posting to customer
  Making a budget decision
  Quoting in board materials
  Citing in compliance documentation

VERIFICATION procedure:
  Agent reports "Spend last month = $42,000"
  Engineer opens ZopNight UI → Reports → Cost Overview
  Filter to "last month"; compare totals
  If match (±2%): trust the agent
  If mismatch: investigate the filter or date range

COMMON CAUSES of number mismatch:
  Different date range interpretation (calendar month vs 30 days)
  Different team/account filter
  Stale data (rare; ZopNight is real-time)
  Hallucination (most concerning; the agent made it up)

TYPE                              LATENCY
──────────────────────────────────────────────────────────────────
Single tool call (small org)       200-500 ms
Single tool call (large org)        500-1500 ms
Multi-tool chain (3-5 calls)        2-5 seconds
Complex synthesis with reasoning    5-15 seconds

WEEKLY SMOKE TEST (2 minutes):

  1. /mcp → connected, non-empty tool list? ✓
  2. "Who am I?" → returns your user ✓
  3. "List 5 idle resources" → returns 5 ✓
  4. "Last week's spend" → matches ZopNight UI ✓
  5. "Top recommendation" → returns top ✓

  If all 5 pass: you're good for the week.
  If any fail: troubleshoot before relying on agent for cost work.

RED FLAGS that the agent is hallucinating (not calling MCP):

  Numbers too round ($50,000 exactly, $100,000)
  Generic resource names (server-1, db-2)
  No specific resource IDs (no i-0xxx... format)
  No timestamps in the output
  Refuses to drill into specific examples
  Numbers don't match dashboard within 5%
  Agent rephrases without adding detail

When you see any of these: open ZopNight UI; verify manually.

DAY 1: Initial setup (covered in L1-L3)

DAY 2: Verification: all 6 steps

$ claude
> /mcp
  ✓ zopnight: connected, 289 tools (Step 1: server starts)

> /tools zopnight
  ✓ tool list matches tier none: reads only (Step 2)

> "Who am I in ZopNight?"
  ✓ "You are jane@platform in 'Acme Corp' org" (Step 3: auth)

> "How many resources are in our prod-payments cluster?"
  ✓ "23 resources: 12 EC2, 4 RDS, 5 EBS, 2 LBs" (Step 4: real data)

> Cross-check: open ZopNight UI → resources filtered to prod-payments
  ✓ 23 resources confirmed (Step 4 verification)

> "What's the biggest growing resource this week and who owns it?"
  Chains: list_resources sorted by growth + tag lookup
  ✓ Returns: "i-0abc123 (m5.xlarge) grew $120 this week. Owner via
              tag: bob@platform" (Step 5: chained query)

> "Delete resource i-0abc123"
  ✓ "I do not have a delete tool available. To take this
     action, open ZopNight UI." (Step 6: error path)

All 6 steps pass. Verification complete.

WEEKLY FROM HERE:
  Every Monday morning: 2-minute smoke test
  Catches: stale PAT, server upgrades needed, org toggle changes

□ STEP 1: Server starts (/mcp shows zopnight connected): pass/fail
□ STEP 2: Tool list is non-empty and matches the org's write tier: pass/fail
□ STEP 3: Auth check ("Who am I?" returns your user): pass/fail
□ STEP 4: Real data check (cross-verify against UI): pass/fail
□ STEP 5: Chained query: pass/fail
□ STEP 6: Error path (ungranted tool refused): pass/fail

ANY FAILURES:
  Step: __________
  Symptom: __________
  Likely cause: __________
  Fix: __________

NUMBER VERIFICATION test:
  Ask agent: "What was our total spend last month?"
  Open ZopNight UI: same date range; compare
  Match? Yes / No / Mismatch by __%

  If mismatch >5%: investigate before trusting agent numbers

BEFORE  An account on the product you are connecting to: ZopNight, ZopDay or ZopCloud. The connection is per product, the assistant is the same.
ASK     "Which organisations can I see, and what am I allowed to do in this one?"
CHECK   permissions before you trust a write. What you can do through an assistant is exactly what your role allows, never more.