Body
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
- Go to https://claude.com/download.
- 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.
- Run the installer and follow the prompts. If you're asked for admin
permission, approve it with your usual account.
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.
🪟 PC
Click the menu (☰) → Help → Troubleshooting → Enable Developer Mode, then
Developer → Configure third-party inference.
Then open Developer → Configure third-party inference:
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 |
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.
Step 4 — Let Claude reach the web
Open the Workspace section and, under General restrictions, set
Allowed egress hosts to *.
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.
Step 6 — Apply and confirm
- Click Apply and restart Claude Desktop when prompted.
- On relaunch, the app should take you straight into Cowork — no personal
sign-in.
- Ask it something simple, like
Say hello.
On relaunch, the app confirms it's running through the gateway with no Claude.ai
account:
…and drops you straight into Cowork:
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.
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.
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. |