Verifying the connection

VERIFICATION CHECKLIST (6 steps):
  ✓ MCP server connects
  ✓ Tool list is non-empty and matches your org's write tier
  ✓ Authentication works (OAuth sign-in or PAT)
  ✓ 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 the Server URL (copied exactly from Settings → API & MCP?)
  OAuth: finish or redo the browser sign-in
  PAT: check the token value and expiry, and that any env var
       the config references is set
  PAT through the mcp-remote bridge (Claude Desktop): check that
       Node.js is installed

LIST tools:
  /mcp, then select zopnight to view its tools (Claude Code);
  other clients list them in their MCP settings panel

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)
    -> irreversible actions appear

EVERY WRITE TIER needs a token bound to the organisation: an
OAuth grant or PAT that includes this org.

NEVER PRESENT AT ANY TIER: organisation deletion and
cloud-account deletion (no tool exists for either), and no
tool returns credential or secret values.
  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.
  The list is served by the hosted server, so nothing on your
  machine needs updating to change it.

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

EXPECTED:
  Agent calls get_organisation + get_my_permissions
  Returns: org name + what your role allows

IF UNAUTHORIZED:
  OAuth: sign in again from the client
  PAT: expired, rotated or invalid; rotate or create one in
       Settings → API & MCP, update the client, restart it

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:
    get_cost_by_resources for this week vs last
    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 (ask, do not run):
  "Do you have a tool that can stop i-0xyz123? Just tell me,
   do not call it."

EXPECTED (Write access below Irreversible changes):
  Agent says it has no stop tool and points you to the
  ZopNight UI to take this action

IF THE AGENT HAS stop_resource:
  Your org's Write access is set to Irreversible changes and
  your token carries that capability. Check Settings →
  Organization, MCP Server section, before going further

SYMPTOM                                FIX
──────────────────────────────────────────────────────────────────
"MCP server timeout"                    Scope queries with filters
                                       (team, account, date range)

"Tool not found"                         The tool is not granted to you:
                                       org write access, your role, or
                                       (PAT) capabilities ticked at mint.
                                       Check before re-minting

"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

"Connection drops randomly"              Network / proxy / VPN first;
                                       PAT path via mcp-remote: check
                                       Node.js is installed

"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 → Costs → Reports → Summary
  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
  Data freshness (cost data lands daily, so today's spend is
    not in yet)
  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. "Top 5 idle-resource recommendations" → 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 (Step 1: server connects)

> /mcp → zopnight → view tools
  ✓ 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: get_cost_by_resources + get_resource tag lookup
  ✓ Returns: "i-0abc123 (m5.xlarge) grew $120 this week. Owner via
              tag: bob@platform" (Step 5: chained query)

> "Do you have a tool that can stop i-0abc123? Don't call it."
  ✓ "No, I have no stop tool here. 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: expired PAT or grant, role or org toggle changes

□ STEP 1: Server connects (/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.