Claude Desktop install + first query

Outcome

By the end of this lesson, you will be able to connect Claude Desktop to the ZopNight MCP server, verify the connection with a first query, and diagnose the three most common setup failures.


Prerequisites	M6.1 (concept) · Claude Desktop installed (macOS or Windows)
Time	9 minutes

1. Concept

Two ways to connect, and one of them is the default.

SIGN IN WITH OAUTH (default, recommended for every interactive client)
  The client opens a browser, you sign in to ZopNight and approve
  access. No token is copied, pasted or stored by you. The client
  holds a short-lived access token and refreshes it on its own.

PERSONAL ACCESS TOKEN (second path)
  You mint a PAT in ZopNight and the client sends it on every request
  as  Authorization: Bearer zn_pat_...
  Use it for CI, scripts, and clients that cannot open a browser.

Both arrive at the gateway as a bearer token, and the gateway resolves your identity, your live role and the org’s write access on every call. Neither method gives you more than your role allows.

Claude Desktop is available for macOS and Windows. Five to ten minutes if nothing goes wrong; the last part of this lesson is the handful of things that usually do.

SETUP STEPS (OAuth):
  1. Copy the Server URL from ZopNight
  2. Add ZopNight as a custom connector in Claude Desktop
  3. Sign in to ZopNight in the browser and approve access
  4. Test with a query

Step 1: Copy the Server URL

ZopNight: Settings → API & MCP
  (also shown in Settings → Organization, MCP Server section)

Server URL: https://api.zop.dev/mcp-server   (copy yours exactly)

If the MCP Server section says Inactive, an admin has to switch it on first (M6.3 covers the org toggle). Organisations created by signing up from an MCP client start with it on; every other new organisation starts with it off.

Step 2: Add the connector

Claude Desktop: Settings → Connectors → Add custom connector
  Name: ZopNight
  URL:  the Server URL from Step 1

On Team and Enterprise plans, an owner may need to add the connector for the organisation first; members then connect to it from the same Connectors screen.

Click Connect. Claude Desktop opens a browser to ZopNight’s sign-in page. Sign in, choose the organisation(s) to grant, leave write permissions unticked unless you need them, and click Authorize. The browser hands control back to Claude Desktop.

The grant then appears in ZopNight under Settings → API & MCP → Connected Apps, where you can revoke it at any time. Revoking invalidates its tokens immediately.

Step 4: Verify

TEST 1: List the available tools:
  Type in Claude Desktop: "What ZopNight tools are available?"
  Expected response: the tool list you are allowed to call
  (filtered at the gateway, so it is narrower than the full
  catalog)

TEST 2: Run a real query:
  Type: "What's our biggest idle resource right now?"
  Expected: Claude calls get_recommendations via MCP and returns
  the top idle-resource recommendation with details (resource,
  estimated saving)

TEST 3: Cross-tool chain:
  Type: "Find the biggest idle resource and draft a Slack message
        to its owner about cleanup."
  Expected: Claude calls get_recommendations, then get_resource to
  read the owner tag, and drafts a Slack message (does not send it)

If all three work: setup complete.

The PAT path (when OAuth is not an option)

Claude Desktop’s configuration file only launches local programs, so a header-authenticated remote server needs the generic mcp-remote bridge, which runs on Node.js. First mint a PAT:

ZopNight: Settings → API & MCP → API Tokens → Create Token

  Name:          my-claude-desktop-mcp
  Expiry:        30 days, 90 days (default), 1 year, no expiry,
                 or a custom date
  Organizations: the org(s) this token may act in
  Permissions:   tick no write capabilities for a read-only token

After creation, the token is shown once: zn_pat_xxxxxxxxxxxxxx
  Copy it now and store it in a password manager.

Then edit the configuration file at the path for your OS:

macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json
Windows:  %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zopnight": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.zop.dev/mcp-server",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer zn_pat_xxxxxxxxxxxxxx"
      }
    }
  }
}

mcp-remote substitutes AUTH_HEADER into the header itself (written without a space after the colon, which avoids an argument-splitting bug on Windows). ZopNight reads only the Authorization header; there is no org header to send, because the org is chosen per tool call from the orgs your token is bound to. If you already have other MCP servers configured, add the zopnight block to the existing mcpServers object without replacing them.

Claude Desktop reads this file only at startup, so quit fully and relaunch: Cmd+Q on macOS, or File → Exit on Windows. Closing the window is not enough.

Common setup failures

SYMPTOM                                FIX
──────────────────────────────────────────────────────────────────
Browser sign-in never returns           Retry Connect; if the page says
                                       the request expired, start the
                                       connection again from Claude

"No tools visible"                      OAuth: reconnect from Connectors.
                                       PAT: quit fully (Cmd+Q, not
                                       close window) and relaunch

"Unauthorized" / 401                     PAT: check the value (no leading
                                       or trailing spaces or newlines),
                                       and that it has not expired or
                                       been rotated

"Network error"                          Check connectivity to the Server
                                       URL; check corporate proxy / VPN

"Command 'npx' not found" (PAT path)    Install Node.js (LTS); npx ships
                                       with it

"MCP server is not enabled for          Org-level toggle off (see M6.3);
 this organisation"                     ask an org admin to enable it

What happens on first connection

OAuth:
  1. Claude Desktop calls the Server URL with no token
  2. ZopNight answers 401 and points the client at its sign-in
  3. You sign in and approve; the client receives an access token
     and a refresh token
  4. The gateway validates the token and returns the tool list,
     already filtered to what this caller may call

At first query:
  5. Claude selects appropriate tool(s) for the query
  6. Tool call goes to the hosted MCP server through the gateway
  7. Result returned; Claude synthesizes for user

Nothing ZopNight-specific runs on your machine. On the PAT path, only the mcp-remote bridge runs locally and forwards your tool calls to the hosted server over HTTPS.

Security considerations

OAUTH GRANT:
  Review and revoke it in Settings → API & MCP → Connected Apps

PAT IS A BEARER CREDENTIAL: treat it like a password:
  Don't commit it to git
  Don't paste it in chat
  Don't share it via email
  Store it in a password manager or OS keychain

ROTATE periodically (see M6.3):
  Default expiry: 90 days
  Rotate before expiry (Rotate keeps the token, issues a new secret)
  Revoke immediately if compromised

What you can ask once connected

EXAMPLE queries that work on day one:
  "What's our biggest idle resource?"
  "Show me the top 10 cost-saving recommendations"
  "Describe the business-hours-eu schedule"
  "Who owns prod-eks-cluster-1?"
  "Show overrides created in the last week"
  "What was our total spend last month?"
  "Compare team-platform vs team-product spend this quarter"

To turn these into saved, shareable prompts, see M6.4.

Multi-org setup

One connection covers every organisation you granted. With OAuth you pick the organisations on the consent screen; a PAT is bound at creation to the organisations you select. Either way the org is chosen per tool call, so you ask for it by name:

"Show idle resources in Acme"
"Compare Acme and Acme-Staging spend last month"

2. Demo

A clean first-time setup:

T+0:00     Open ZopNight: Settings → API & MCP
T+0:10     Copy the Server URL: https://api.zop.dev/mcp-server

T+0:30     Claude Desktop: Settings → Connectors → Add custom connector
           Name: ZopNight, URL: pasted
T+0:45     Click Connect; browser opens ZopNight sign-in

T+1:00     Sign in, select org "Acme", leave write permissions
           unticked, click Authorize
T+1:15     Browser returns to Claude Desktop; connector shows connected

T+1:30     In Claude: "What ZopNight tools are available?"
T+1:35     Claude: "I can use ZopNight read tools for resources,
                    schedules, costs and billing, recommendations,
                    teams and showback, budgets, audit logs, cloud
                    accounts, notifications, dashboards, autoscaler,
                    event readiness and governance. No write tools:
                    this org's write access is Read-only."

T+1:45     Test query: "What's our biggest idle resource?"
T+1:50     Claude calls get_recommendations via MCP
T+2:00     Returns: "i-0xyz123 (m5.2xlarge in us-east-1) has been
                     stopped 47 days. EBS attached: $69/month."

CONNECTED. Total elapsed: ~2 minutes.

On a Read-only org the list holds only read tools: most of the catalogue, but none of the write tools, and fewer still if your role cannot read everything.

3. Hands-on (5 min)

Run through the four steps:

□ STEP 1: Copied the Server URL
  URL: __________

□ STEP 2: Added the connector (or, PAT path, edited the config file)
  Connector name / file path: __________

□ STEP 3: Signed in and approved (or, PAT path, quit and relaunched)
  Visible in Connected Apps?  Yes / No

□ STEP 4: Verified
  Test 1 (list tools): pass / fail
  Test 2 (first query): pass / fail
  Test 3 (chain): pass / fail

IF FAILED at any step:
  Symptom: __________
  Likely cause (from common failures table): __________
  Fix attempted: __________

If all three tests pass, your setup is working. Onward to L2 for Cursor and Codex.

4. Knowledge check

Q1

After updating Claude Desktop’s MCP config, what’s required for it to see the change?

A. Nothing: picks up automatically
B. Reinstall the app
C. Full restart of Claude Desktop
D. System reboot

Show answer

Correct: C. Claude Desktop reads its config file only at startup. Closing the window isn’t enough: quit with Cmd+Q (macOS) or File → Exit (Windows), then relaunch.

Q2

The PAT used for MCP can be:

A. Used to write even when the org is Read-only
B. Reads, on a default-configured org
C. Elevated to Admin scope for MCP sessions
D. Both read and write

Show answer

Correct: B. A PAT carries the user’s own role plus the write capabilities ticked when it was minted, and the gateway intersects them with the org’s write access, which defaults to Read-only (M6.1.L2). Even an admin’s PAT reads and does not write on a default org. The constraint is the org setting, not the architecture.

Q3

The configuration file path on macOS:

A. /etc/claude/config.json, applied system-wide
B. /tmp/claude.json, recreated on each session
C. A custom location chosen by the user at installation time
D. ~/Library/Application Support/Claude/claude_desktop_config.json

Show answer

Correct: D. The standard macOS user-config path. On Windows the same file sits under %APPDATA%\Claude. Claude Desktop is not built for Linux.

5. Apply

Documentation: zop.dev/developer-docs/integrations/mcp-server/overview. Server URL, tokens and connected apps: Settings → API & MCP.

For team rollout: put the Server URL and the OAuth steps in your team wiki. Cover PAT generation only for the people who need it (CI, non-browser clients).

Glossary terms touched

MCP configuration · PAT · Bearer credential

Outcome

1. Concept

Step 1: Copy the Server URL

Step 2: Add the connector

Step 3: Sign in and approve

Step 4: Verify

The PAT path (when OAuth is not an option)

Common setup failures

What happens on first connection

Security considerations

What you can ask once connected

Multi-org setup

2. Demo

3. Hands-on (5 min)

4. Knowledge check

Q1

Q2

Q3

5. Apply

Related lessons

Glossary terms touched

Start with the bill.