Setting up Cursor and Codex · ZopDev University

Outcome

By the end of this lesson, you will be able to connect ZopNight MCP to Cursor and to OpenAI Codex with OAuth sign-in, keep a PAT out of config files when you need one, and verify the connection with three tests.


Prerequisites	M6.1 · M6.2.L1
Time	9 minutes

1. Concept

Cursor is a code editor built around an assistant. Codex is OpenAI’s coding agent, available as an app, an IDE extension and a CLI.

Both speak MCP over HTTP, so both connect straight to ZopNight’s hosted server: no bridge, nothing to install. As in L1, sign in with OAuth is the default; a PAT in a bearer header is the fallback for CI and non-browser use.

PREREQUISITES:
  ZopNight org with the MCP Server switched on (covered in M6.3)
  The Server URL from Settings → API & MCP
  Cursor or Codex installed
  Engineer wants cost data inline in their dev workflow

Cursor setup (OAuth)

1. Open Cursor → Customize → MCPs → New MCP Server
   (this opens ~/.cursor/mcp.json, which applies to every project;
    use .cursor/mcp.json in a repo for that project only)
2. Paste this config and save:
     {
       "mcpServers": {
         "zopnight": {
           "url": "https://api.zop.dev/mcp-server"
         }
       }
     }
3. Cursor opens a browser to sign in to ZopNight and grant access
4. Test in Cursor chat: "what are my top idle-resource recommendations?"
   → Cursor calls ZopNight MCP; returns the top items

Codex setup (OAuth)

CONFIG FILE (~/.codex/config.toml), shared by the Codex
CLI, IDE extension and app:
     [mcp_servers.zopnight]
     url = "https://api.zop.dev/mcp-server"

OR register it with the CLI, which writes the same entry:
     codex mcp add zopnight --url https://api.zop.dev/mcp-server

THEN sign in from the terminal (opens a browser):
     codex mcp login zopnight

CHECK it is registered:
     codex mcp list

Test in Codex chat: "what are my top idle-resource
recommendations?"

The Codex app can also add the server from its own MCP settings (Type: Streamable HTTP, URL as above). The menu label for that screen may vary by app version; editing config.toml works the same everywhere.

Grok build setup

Grok build (xAI’s coding agent) also talks to remote MCP servers directly, so it registers the URL from the terminal:

1. Open a terminal
2. Register the server:
     grok mcp add --transport http zopnight https://api.zop.dev/mcp-server
3. Grok build opens a browser to sign in to ZopNight
4. Test in Grok build chat: "what are my top idle-resource recommendations?"

The PAT path: keep the token out of the file

When OAuth is not an option (a shared CI runner, a headless box), mint a PAT (L1 and M6.3) and send it as Authorization: Bearer <PAT>. Both clients can read the token from an environment variable, so the config file never holds the secret. The variable name is yours to choose; the client expands it, ZopNight never sees it.

CURSOR (~/.cursor/mcp.json or .cursor/mcp.json):
{
  "mcpServers": {
    "zopnight": {
      "url": "https://api.zop.dev/mcp-server",
      "headers": {
        "Authorization": "Bearer ${env:ZOPNIGHT_PAT}"
      }
    }
  }
}

CODEX (~/.codex/config.toml):
[mcp_servers.zopnight]
url = "https://api.zop.dev/mcp-server"
bearer_token_env_var = "ZOPNIGHT_PAT"

  or: codex mcp add zopnight --url https://api.zop.dev/mcp-server \
        --bearer-token-env-var ZOPNIGHT_PAT

CODEX APP (its MCP settings; the menu label may vary):
  prefer the "Bearer token env var" field, which takes a
  variable NAME (ZOPNIGHT_PAT), not the token itself

GROK BUILD:
  grok mcp add --transport http zopnight https://api.zop.dev/mcp-server \
    --header "Authorization: Bearer <your-PAT>"

Set the variable in your shell profile, then restart the shell and the tool:

# ~/.zshrc or ~/.bashrc
export ZOPNIGHT_PAT="zn_pat_xxxxxxxxxxxxxx"

Security: never commit PATs

DO:
  Prefer OAuth: there is no token to leak
  Reference the PAT through an environment variable in config files
  Store the PAT in a secrets manager or your shell profile
  Add .env to .gitignore

DON'T:
  Hardcode a PAT in mcp.json or config.toml
  Commit a config file containing a PAT value
  Share a PAT via Slack/email
  Use the same PAT for multiple machines (one per device)

Verification: three tests

After setup, run these three:

TEST 1: Server registered:
  In chat: "What MCP servers are connected?"
  Expected: list includes zopnight

TEST 2: Tool call works:
  In chat: "List my top idle-resource recommendations"
  Expected: real items from your ZopNight org

TEST 3: Chained query:
  In chat: "What's my total monthly spend on EC2 across all accounts?"
  Expected: Chains multiple MCP calls; synthesizes a total

If all three pass, you’re connected. If any fails, see common setup failures below.

Common setup failures

PROBLEM: Server shows "needs login" or never connects
  CAUSE: OAuth sign-in not finished, or the request expired
  FIX:   Start the sign-in again from the client (Cursor: the MCP
         settings entry; Codex CLI: codex mcp login zopnight)

PROBLEM: "Unauthorized"
  CAUSE: PAT invalid, expired or rotated, or the env var is unset
  FIX:   echo $ZOPNIGHT_PAT in the shell that launched the tool;
         rotate or create a PAT in Settings → API & MCP if needed

PROBLEM: "No tools available"
  CAUSE: Org has the MCP Server toggled off, or your role reads
         nothing in this org
  FIX:   Check with an org admin (M6.3)

PROBLEM: "Tool calls time out"
  CAUSE: Very broad query against a large org
  FIX:   Scope the question (team, account, date range)

PROBLEM: "Permission denied" (file system)
  CAUSE: Config file location not writable
  FIX:   Check directory permissions; create parent dir if missing

What a token can and cannot be scoped to

A PAT carries YOUR identity and live role. At creation you choose:
  Organizations   which of your orgs it may act in
  Permissions     which write capabilities it carries, named
                  category:operation (e.g. budget:create,
                  schedule:update, resource:delete)

Reads are never token-scoped: a PAT reads whatever your role can
read. Ticking no permissions gives a read-only token.

Every call is the intersection of three things: your live role, the org’s write access setting, and (for a PAT) the capabilities ticked at creation. M6.3 covers PAT management in detail.

Multi-org setup

Engineers working across several ZopNight orgs (e.g., one per customer in MSP / consulting roles) need only one entry. With OAuth you pick the orgs on the consent screen; a PAT is bound at creation to the orgs you select. The org is chosen per tool call:

"List idle-resource recommendations for Customer A"
"Compare Customer A and Customer B spend last month"

Use separate entries only if you deliberately want separate credentials per customer.

Team quick-start template

For teams adopting MCP, publish a starter template:

# In team's internal docs / wiki

SERVER URL: https://api.zop.dev/mcp-server  (from Settings → API & MCP)

CURSOR (.cursor/mcp.json, safe to commit: no secret in it):
{
  "mcpServers": {
    "zopnight": { "url": "https://api.zop.dev/mcp-server" }
  }
}

CODEX (~/.codex/config.toml):
[mcp_servers.zopnight]
url = "https://api.zop.dev/mcp-server"

FIRST RUN: sign in to ZopNight in the browser when the tool asks.

Document team-shared config in the repo; each engineer signs in with their own account.

2. Demo

ENGINEER OPENS Cursor for the first time after setup:

Step 1: Cursor reads ~/.cursor/mcp.json on startup
Step 2: Connects to the Server URL; ZopNight asks for sign-in
Step 3: Engineer signs in and approves in the browser
Step 4: Cursor receives the tool list the gateway
        filtered for this caller

ENGINEER queries:
  "list my top 5 idle-resource recommendations"

Cursor (via MCP):
  Calls get_recommendations
  Returns 5 recommendations with resource and estimated saving

ENGINEER follow-up:
  "schedule the top one for nights and weekends"

Cursor (via MCP):
  Recognizes mutation request
  Responds: "I do not have a schedule-creation tool available.
             To schedule i-0xyz123, open ZopNight:
             https://zop.dev/zopnight/app/schedules/new
             Want me to draft the schedule config you'd paste?"

ENGINEER: "Yes, draft the schedule."

Cursor drafts cron-style schedule + resource group assignment.
ENGINEER copies, opens ZopNight UI, pastes, saves.

Engineer's time: 60 seconds
Without MCP: would require switching to ZopNight UI to find
             the resource + 5 minutes of dashboard navigation

The contract surfaces appropriately: on a Read-only org create_schedule is never advertised, so the agent recognises it cannot act and redirects to the UI.

3. Hands-on (5 min)

Set up MCP in your preferred AI tool:

TOOL: Cursor / Codex / both

□ STEP 1: Copied the Server URL from Settings → API & MCP

□ STEP 2: Config added
  Location: __________
  Method: OAuth / PAT via env var

□ STEP 3: Signed in to ZopNight in the browser (OAuth)
  or set the env var in your shell profile (PAT)

□ STEP 4: Restarted tool (if it did not pick up the change)

□ STEP 5: Verification tests
  Test 1 (server registered): pass / fail
  Test 2 (tool call): pass / fail
  Test 3 (chained query): pass / fail

ANY FAILURES:
  Symptom: __________
  Likely cause (from common failures): __________
  Fix: __________

If you cannot get all three tests to pass, M6.2.L4 covers deeper verification.

4. Knowledge check

Q1

PAT for MCP should be stored:

A. Hardcoded directly in the mcp.json config file
B. Shared in the team chat channel so everyone can use it
C. Read from an environment variable the client expands
D. Committed to the repository alongside the config

Show answer

Correct: C. The config file can go in version control; the PAT value stays in the shell environment or a secrets manager. Never commit PATs to source control. Better still, use OAuth where the client supports it, and there is no token to store.

Q2

After MCP setup, verify with:

A. Both: server registered AND a test tool call returns real data
B. Just checking that the MCP server shows up as registered
C. Skipping verification and simply using it directly
D. Checking the advertised tool count matches the docs

Show answer

Correct: A. Without the tool call, you don’t know if the credential works. Server-registered alone is necessary but not sufficient: run all three tests (server registered, tool call, chained query) before relying on the connection.

Q3

What does ticking write capabilities on a PAT control?

A. Which write tools it may call, within your role and the org setting
B. Which read tools it may call, such as costs or resources
C. Your role in the organisation for every session that uses it
D. Nothing: the org’s write access alone decides what is allowed

Show answer

Correct: A. Capabilities are named category:operation (for example budget:create) and only narrow writes. Reads are never token-scoped, the token never exceeds your role, and the org’s write access still applies on top.

5. Apply

Configure MCP for your team’s chosen AI tool. Document the team setup in your wiki. M6.3 covers PAT management at scale.

For team rollout: publish a template config with the Server URL; each engineer signs in with OAuth, and only CI or headless use gets its own PAT.

Outcome

1. Concept

Cursor setup (OAuth)

Codex setup (OAuth)

Grok build setup

The PAT path: keep the token out of the file

Security: never commit PATs

Verification: three tests

Common setup failures

What a token can and cannot be scoped to

Multi-org setup

Team quick-start template

2. Demo

3. Hands-on (5 min)

4. Knowledge check

Q1

Q2

Q3

5. Apply

Related lessons

Start with the bill.