Appendix: Manual Claude Desktop Setup on Cornell's AI Gateway

This article configures Claude Desktop to use the Cornell AI Gateway by hand — the same data protections, billing model, and vetted tools as the managed install, set up manually.

Most people should not need this. On a Cornell-managed device, the standard install does everything below for you, including the secure tools — see Installing Claude Desktop on macOS (Pilot) or Installing Claude Desktop on Windows (Pilot). Use this article for the occasional case where that managed install is not available to you, most commonly because you have no assigned Cornell-managed device.

This is a pilot deployment run by JCB IT with AI at Cornell and IT@Cornell. Details may change as it develops.

Before you start

1. Get your gateway key — Getting Your Cornell AI Gateway Key. You'll enter it partway through setup, so you cannot finish without it.

2. Enroll in Secure Connect — if your device is not Cornell-managed, using the gateway from it still requires enrollment in Secure Connect.

Step 1 — Install Claude Desktop

  1. Go to https://claude.com/download.
  2. Download the installer for your computer — Mac gets a .dmg, PC gets a .msix. On the download page, Windows lists two builds: pick Windows for a standard Intel/AMD PC, or Windows (arm 64) for an ARM device (e.g. a Surface or Snapdragon laptop). If unsure which you have, choose Windows.
  3. Run the installer and follow the prompts. If you're asked for admin permission, approve it with your usual account.

claude.com/download page with the correct download button for each OS

Step 2 — Open the gateway configuration screen

Launch Claude Desktop. Do not sign in to a personal account. Instead:

🍎 Mac

Help → Troubleshooting → Enable Developer Mode, then Developer → Configure third-party inference.

Mac: the Help → Troubleshooting menu with Enable Developer Mode highlighted

🪟 PC

Click the menu (☰) → Help → Troubleshooting → Enable Developer Mode, then Developer → Configure third-party inference.

PC: the ☰ → Help → Troubleshooting menu with Enable Developer Mode highlighted

Then open Developer → Configure third-party inference:

the Developer menu with Configure Third-Party Inference highlighted

Step 3 — Fill in the Connection settings

In the configuration window, open the Connection section and enter:

Field What to enter
Connection Gateway
Credential kind Static API key
Gateway base URL https://api.ai.it.cornell.edu
Gateway API key your personal key (the sk-… value)
Gateway auth scheme bearer

Configure third-party inference window, Connection section, with each field labeled and the key field highlighted

You can press Test connection (top-right of the credentials card) to confirm the key and URL work before continuing.

You don't need to list the models by hand. Scroll to the Models section and leave Model discovery turned on — Claude Desktop reads the available models from the gateway at launch. Press Test model discovery to confirm; you should see the Cornell models appear.

Models section with Model discovery enabled, showing the Cornell models discovered from the gateway

Step 4 — Let Claude reach the web

Open the Workspace section and, under General restrictions, set Allowed egress hosts to *.

Configure third-party inference window, Workspace section, with Allowed egress hosts set to an asterisk

Without this, Claude's web-fetch tool cannot retrieve any webpage, so anything that depends on reading a link fails silently. The field controls which hostnames Claude's tools may reach from Cowork and Code sessions. It is unrelated to telemetry, which you turn off in the next step.

ℹ️ You may see this field twice. The same setting is also surfaced under Egress Requirements. Setting it in either place is the same setting; there is no second list to fill in.

Step 5 — Block telemetry to Anthropic

Open the Telemetry & updates section and turn on all three toggles (each one blocks that category of data from leaving your computer):

Toggle What it blocks
Block nonessential telemetry Product and usage analytics.
Block nonessential services Cosmetic web fetches. ⚠️ Also stops artifact previews and connector icons from rendering in conversations.
Block essential telemetry Crash and error reports.

⚠️ All three are required, not optional. Cornell's approval to use this app with Moderate Risk data depends on all three being on. The managed install applies the same three for you.

The trade-off of the third one is worth knowing: with crash reporting blocked, there is no remote crash visibility if you ever need support on a gateway-specific failure. It stays on regardless.

See Privacy — What We Turned Off and Why for what each one means in plain language.

Telemetry & updates section with the recommended toggles enabled

Step 6 — Apply and confirm

  1. Click Apply and restart Claude Desktop when prompted.
  2. On relaunch, the app should take you straight into Cowork — no personal sign-in.
  3. Ask it something simple, like Say hello.

On relaunch, the app confirms it's running through the gateway with no Claude.ai account:

Welcome screen confirming Claude is set up to run through a custom inference gateway, no account needed

…and drops you straight into Cowork:

Claude Desktop open in Cowork mode after restart, with the "You're using Gateway" banner

How do I know it worked?

  • After restart, you land directly in Cowork without a claude.ai sign-in screen.
  • Claude answers your prompt.
  • The Cornell models are available in the model picker.

If anything failed, see Claude on Cornell's Gateway — Troubleshooting.

Optional — add the Cornell secure tools

This adds one connector, cornell_secure_tools, carrying the same vetted gateway tools the managed install gets. It reaches Claude over the Model Context Protocol (MCP). It is the same connector that provides Cornell's web search; the mapping tools were added to it rather than as a second connector.

Inside it, tool names are prefixed by the upstream service:

Prefix Tools
google_enterprise_search- web_search
google_maps- search_places, compute_routes, lookup_weather, resolve_names, resolve_maps_urls

Your gateway key is scoped for these tools already, so there is nothing to request first. If Claude connects but no tools appear, that's a key-scope problem rather than a configuration problem — email itrequests@business.cornell.edu rather than editing the config again.

Requires Node.js (LTS) on your machine, because the bridge runs through npx.

ℹ️ Why a local bridge instead of a connector? Claude Desktop can add remote MCP servers as custom connectors, but that path doesn't work for Cornell's gateway. Connectors are brokered through a Claude account, so the connection originates from Anthropic's servers rather than your machine, and they authenticate by OAuth only — meaning they cannot send the x-litellm-api-key header the gateway requires. Account-brokered connectors are also unavailable while the app is in third-party inference mode. So the gateway is attached as a local MCP server that bridges to it, which also keeps the connection on your own machine.

1. Open the config file

In Claude Desktop's settings, choose Developer under Desktop app, then click Edit config.

Claude Desktop settings, Developer pane, showing Local MCP servers and the Edit config button

That button always opens the file the app actually reads — which matters here, because third-party inference mode uses a different profile directory than Anthropic's docs describe. The Where the config file lives table below has the paths if you need them.

Before you add anything, this pane reads No servers added. After the steps below it lists cornell_secure_tools.

2. Paste the server definition

Merge this into any mcpServers you already have, and replace sk-YOUR-GATEWAY-KEY with your key secret. Keep the Bearer prefix.

The Mac and Windows versions are different. Use the one for your platform — the Windows form is not optional styling, and the Mac form fails on Windows.

🍎 Mac

{
  "mcpServers": {
    "cornell_secure_tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://api.ai.it.cornell.edu/mcp/",
        "--header",
        "x-litellm-api-key:Bearer sk-YOUR-GATEWAY-KEY"
      ]
    }
  }
}

🪟 PC

{
  "mcpServers": {
    "cornell_secure_tools": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote@0.1.38",
        "https://api.ai.it.cornell.edu/mcp/",
        "--header",
        "x-litellm-api-key:Bearer sk-YOUR-GATEWAY-KEY"
      ]
    }
  }
}

⚠️ Windows: why cmd /c instead of just npx? On Windows, npx is a .cmd shim that normally lives at C:\Program Files\nodejs\npx.cmd. Claude Desktop resolves npx to that full path and hands it to the command interpreter unquoted, so the space in Program Files splits the command and you get 'C:\Program' is not recognized as an internal or external command. Making cmd the command avoids this, because its own path contains no spaces and it resolves npx from your PATH itself. This is a general Windows pitfall for any MCP server launched through npx, not something specific to Cornell's tools.

Two details that will break it if you "tidy" them:

  • No space after the colon in x-litellm-api-key:Bearer sk-…. That's the header form the bridge expects on a command line. The space inside Bearer sk-… is required.
  • The version pin is deliberate. mcp-remote@0.1.38 is the version Cornell tested against the gateway. Dropping the pin picks up whatever is newest.

3. Fully quit and reopen Claude Desktop

Cmd+Q on macOS, or Quit from the tray on Windows. Closing the window is not enough — MCP servers are only loaded at startup.

4. Confirm the tools are there

In the message box, open the attachment menu, hover Connectors, and confirm cornell_secure_tools is listed with its toggle on.

The message box's Connectors submenu listing cornell_secure_tools with its toggle enabled

Then try a prompt like "search the web for the Cornell academic calendar." Claude asks you to approve the first tool call.

The toggle is per-connector, so you can switch the Cornell tools off for a conversation without touching the config file. Browse connectors and Manage connectors in that same submenu do not add anything on this setup — there is no catalogue to pick from in third-party inference mode, which is why the config file is the only way in.

If you want to be certain, check the MCP log — the path is in the table further down. A healthy startup ends with a tools/list round trip, and contains no not recognized line:

[pid] Connecting to remote server: https://api.ai.it.cornell.edu/mcp/
[pid] Connected to remote server using StreamableHTTPClientTransport
[pid] Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport
[Local→Remote] tools/list
[Remote→Local] 1

⚠️ "Server started and connected successfully" is not enough. That line can appear immediately before the server crashes, so treat the completed tools/list exchange as the real signal.

Keeping your key out of the process list

In the block above, your key is a command-line argument, so it is visible to anyone who can list processes on the machine (ps aux on macOS, the Details tab of Task Manager on Windows). To avoid that, put the key in an env block and reference it instead — the bridge substitutes ${VAR} in header values from the environment at launch. Keep the command and args shape for your platform from step 2 — only the header value and the new env block change.

{
  "mcpServers": {
    "cornell_secure_tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://api.ai.it.cornell.edu/mcp/",
        "--header",
        "x-litellm-api-key:${CORNELL_GATEWAY_KEY}"
      ],
      "env": {
        "CORNELL_GATEWAY_KEY": "Bearer sk-YOUR-GATEWAY-KEY"
      }
    }
  }
}

On Windows, keep "command": "cmd" with "/c", "npx" at the front of args, and add the same env block.

This keeps the key out of the process list. It does not encrypt it — the key still sits in the config file in plain text, so the file itself is as sensitive as the key.

Where the config file lives

In third-party inference mode the app runs from a separate profile directory with a -3p suffix, so the path in Anthropic's own documentation is not the file being read — editing it appears to do nothing. Using Developer → Edit config in settings avoids the problem entirely.

Mode macOS Windows
Normal (signed in to Claude) ~/Library/Application Support/Claude/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
Third-party inference (Cornell's gateway) ~/Library/Application Support/Claude-3p/claude_desktop_config.json %LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
MCP logs ~/Library/Logs/Claude-3p/, file mcp-server-cornell_secure_tools.log logs folder inside the profile directory above

What these tools cost

Tool calls run through the gateway under the same data-handling posture as your model calls, are logged the same way, and bill against your key's spend cap.

Tool Cost per request
Google enterprise web search $0.05
Google Maps tools $0.00007

⚠️ Both carry attribution requirements from Google. Complying with them is your responsibility as the user, not Cornell's.

Secure-tools troubleshooting

Symptom Cause and fix
Server connects, but no tools appear Your key isn't scoped for the MCP server. Nothing in the config will fix this — email itrequests@business.cornell.edu. Same applies if only some expected tools appear.
401 … Malformed API Key passed in. Ensure Key has 'Bearer ' prefix. The header value must be Bearer sk-…, not the bare key.
Windows: 'C:\Program' is not recognized as an internal or external command You used the Mac form. Switch to the cmd /c form in step 2. Do not "fix" it by substituting the absolute path to npx — the space in C:\Program Files is the cause, so that makes it worse.
Mac: server fails to start, or ENOENT in the log Claude Desktop was launched from Finder and didn't inherit your shell PATH, so npx isn't found. Replace "command": "npx" with the absolute path from which npx, and add an env block setting PATH if needed.
Edits to the config have no effect You edited the wrong profile's file (see the path table above), or didn't fully quit and reopen the app.
Was this helpful?
0 reviews
Print Article