Connecting Claude Code (terminal)

WHEN CLAUDE CODE WINS:
  You live in the terminal
  You want agent + git + cost in one session
  You run automation scripts that need cost data
  You write internal tools that benefit from cost context
  You want skills (reusable commands) as a team

INSTALL (one-time):
  Option A: npm install -g @anthropic-ai/claude-code
  Option B: curl -fsSL https://claude.com/install.sh | sh

  Option B is recommended for stability (binary install)

VERIFY:
  $ claude --version
  → claude-code 1.x.x

AUTH (one-time, opens browser):
  $ claude /login
  → sign in to Anthropic account in browser
  → returns to terminal authenticated

GLOBAL config: ~/.claude/mcp.json

{
  "mcpServers": {
    "zopnight": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-zopnight-mcp-endpoint>/mcp"],
      "env": {
        "ZN_PAT": "${env:ZN_PAT}",
        "ZN_ORG": "${env:ZN_ORG}"
      }
    }
  }
}

# ~/.zshrc or ~/.bashrc
export ZN_PAT="zn_pat_xxxxxxxxxxxxxx"
export ZN_ORG="org_acme123"

$ claude

> /mcp
  Connected servers:
    zopnight (43 tools)

> "List my top 5 idle resources"
  Claude calls: list_resources(filter=idle, sort=days, limit=5)
  Returns formatted output (5 resources with details)

EDIT in repo root:
  .claude/mcp.json

  {
    "mcpServers": {
      "zopnight-prod": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://<your-zopnight-mcp-endpoint>/mcp"],
        "env": {
          "ZN_PAT": "${env:ZN_PAT_PROD}",
          "ZN_ORG": "org_prod"
        }
      }
    }
  }

GITIGNORE the .env (env vars come from environment, not committed)
COMMIT .claude/mcp.json (uses env-var references, not literal PATs)

EDIT: ~/.claude/skills/cost-summary.md

---
description: Generate this week's cost summary
---

Use the zopnight MCP server to:
1. Call get_costs filtered to last 7 days (by team)
2. Call get_cost_trends for week-over-week comparison
3. Call get_recommendation_summary for open recs
4. Call list_audit_logs for material changes

Synthesize into a markdown summary with these sections:
  Total spend (and WoW delta)
  Top changes (resource-level)
  Open recommendations (top 3 by impact)
  Material changes (audit log highlights)
  Action items (specific to this week)

Output to stdout. Don't write files unless asked.

USE the skill:
$ claude
> /cost-summary
  → Claude runs the skill, calls MCP tools, returns summary

SHARE with team:
  Commit the skill file to a team repo
  Each engineer copies to ~/.claude/skills/ or
  uses project-scoped .claude/skills/

SETUP: ~/.claude/mcp.json:
  zopnight-customer-a:
    Env: ZN_PAT=$ZN_PAT_A, ZN_ORG=org_a
  zopnight-customer-b:
    Env: ZN_PAT=$ZN_PAT_B, ZN_ORG=org_b

USE:
  > "Compare customer-a and customer-b spend last month"
  Claude calls both servers, merges results, presents comparison

  > "Show idle resources in customer-a only"
  Claude calls only zopnight-customer-a server

WHEN CLAUDE CODE RUNS in your terminal:
  Can read/write local files (with permission prompt)
  Can run shell commands (with permission prompt)
  Calls MCP tools automatically (read-only ones; no prompt)

RECOMMENDED setup:
  Don't auto-allow shell commands by default
  Review each shell command before approving
  Audit MCP calls via ZopNight audit log (M6.3.L3)

The MCP tool calls are safe (read-only), but shell commands
and file writes deserve case-by-case approval.

PROBLEM: "MCP server fails to start"
  Check: npx -y mcp-remote https://<your-zopnight-mcp-endpoint>/mcp --version
  Fix:   re-install npm package; check Node version (18+)

PROBLEM: "PAT unauthorized"
  Check: echo $ZN_PAT
  If empty: PAT not exported in shell; add to .zshrc/.bashrc
  If wrong: regenerate PAT in ZopNight settings

PROBLEM: "Tool timeout"
  Cause: org has many resources; default page size is too small
  Fix:   args: ["-y", "mcp-remote", "https://<your-zopnight-mcp-endpoint>/mcp", "--timeout=60000"]
  Or:    scope queries with filters (by team, date range)

PROBLEM: "Skill not found"
  Check: ~/.claude/skills/<name>.md exists
  Reload: claude /skills (lists currently-loaded skills)
  Verify: filename + frontmatter matches the slash command

~/.claude/skills/
  cost-summary.md          Weekly team cost summary
  anomaly-triage.md        15-min triage helper (M4.5.L1)
  postmortem-skeleton.md   Postmortem template + data (M4.5.L4)
  forecast-prep.md         Bottom-up forecast helper (M4.6.L2)
  reco-review.md           Recommendation triage

$ claude

> /mcp
  Connected servers:
    zopnight (43 tools)

> "What's my biggest unrealized recommendation?"
  Claude calls: get_recommendation_summary
  Returns: "i-0xyz123 right-sizing recommendation worth $400/mo,
            no action since 30 days. Owner via tag: bob@platform."

> "Draft a Slack message to the owner explaining the recommendation
   and asking when we can apply it."
  Claude drafts message tailored to engineer audience:
    "@bob: i-0xyz123 has a right-sizing rec open for 30 days
     ($400/mo savings). Anything blocking us from applying? Let me
     know if you want me to walk through it."

> "Save the draft to ~/cost-summary.md"
  Claude writes file (prompts for permission first)

> "Now generate this week's cost summary using the cost-summary skill"
  Claude invokes /cost-summary skill
  Skill chains 4 MCP calls
  Returns formatted summary to stdout

Engineer reviews, sends Slack, commits the cost-summary.md to a
weekly archive directory.

ELAPSED: 3 minutes of terminal time.

□ STEP 1: Install Claude Code
  Method: npm / curl install / already installed
  Verified version: __________

□ STEP 2: Authenticate
  $ claude /login
  Verified: __________

□ STEP 3: Configure MCP
  Created ~/.claude/mcp.json
  Set env vars in ~/.zshrc or ~/.bashrc
  Restarted shell

□ STEP 4: Test
  $ claude
  > /mcp
  Sees zopnight? Yes / No

□ STEP 5: First skill
  Create ~/.claude/skills/cost-summary.md (use the template above)
  $ claude
  > /cost-summary
  Runs? Yes / No

CHALLENGE for the week:
  Build a second skill for a recurring workflow you have
  Skill name: __________
  What it does: __________