← Back to Blog
Claude CodeCodeGateway

Claude Desktop Developer Mode: Configure a Custom API Endpoint

May 20, 2026
Claude Desktop Developer Mode: Configure a Custom API Endpoint

Claude Desktop Developer Mode: Configure a Custom API Endpoint

TL;DR: Claude Desktop defaults to Anthropic's API. When you hit timeouts or connection errors, Developer Mode lets you edit claude_desktop_config.json to point ANTHROPIC_BASE_URL at a custom endpoint — 5 minutes, MCP unaffected.

Table of Contents

Why Change Claude Desktop's API Endpoint

By default, Claude Desktop routes all API requests to Anthropic's official endpoint. For some developers, this results in:

  • Request timeouts or slow responses due to routing distance
  • unsupported_region errors when Anthropic's API is unavailable in your region
  • Difficulty using an API key with the desktop client (Anthropic differentiates between Claude.ai subscriptions and API access)

The fix is to route Claude Desktop's underlying API traffic through a third-party aggregation gateway by pointing the client at a custom baseURL. This is done through Claude Desktop's developer mode — a configuration file you edit once, and the client picks up on the next restart.

The process takes about five minutes and does not require system-level proxy configuration. MCP tools, Projects, and Artifacts continue to work normally.

What Is Claude Desktop Developer Mode

Claude Desktop provides two entry points to enable developer mode — use whichever is easier to find:

Entry point

Path

Top menu bar

Help → Enable Developer Mode

In-app settings

Settings → Developer → Edit Config

Both paths lead to the same place: a JSON configuration file called claude_desktop_config.json.

This file controls three things:

  • MCP server definitions — which local tool servers Claude can invoke
  • Environment variables — including ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY for custom API routing
  • Log verbosity — for debugging MCP tool calls

Developer mode is not a separate runtime state — it's an entry point to edit this configuration file. Changes take effect after a full restart of the application.

Prerequisites

  • Claude Desktop installed (download), version 0.10 or later recommended
  • A third-party API gateway endpoint and key (this guide uses CodeGateway: https://api.codegateway.dev/v1)
  • Any text editor (VS Code, Notepad++, or the built-in editor that opens from Settings)

macOS Setup

Step 1: Open the config file

Two options — pick one:

  • Option A: Menu bar → Help → Enable Developer Mode (toggles the Developer tab on), then go to Settings → Developer → Edit Config
  • Option B: Menu bar → Claude → Settings → Developer → Edit Config (if the Developer tab is already visible)

This opens claude_desktop_config.json at its default location:

~/Library/Application Support/Claude/claude_desktop_config.json

You can also open it directly from Terminal:

bash
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Add the custom endpoint configuration

Add an "env" field to the JSON with your gateway URL and key:

json
{
  "mcpServers": {},
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

If you already have MCP servers configured, append the "env" block without replacing the rest of the file:

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

Step 3: Fully quit and restart

Save the file, then quit Claude Desktop entirely via Claude (menu bar) → Quit Claude. Closing the window is not enough — Claude Desktop stays resident in the menu bar. Restart the app after quitting.

Windows Setup

Step 1: Enable developer mode and open the config file

Two options — pick one:

  • Option A: App menu bar → Help → Enable Developer Mode (toggles the Developer tab on), then Settings → Developer → Edit Config
  • Option B: Go directly to Settings → Developer → Edit Config (if the Developer tab is already visible)

You can also navigate to the config file manually:

%APPDATA%\Claude\claude_desktop_config.json

Paste this path into File Explorer's address bar and press Enter to jump straight to it.

Step 2: Add the custom endpoint configuration

Same structure as macOS:

json
{
  "mcpServers": {},
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

For Windows filesystem paths in MCP server args, use double backslashes:

json
"args": ["C:\\Users\\yourname\\Documents"]

Step 3: Fully quit and restart

Right-click the Claude icon in the system tray → Exit, then relaunch.

Environment Variable Method (Advanced)

If you manage multiple machines, or want to keep the API key out of the config file, you can set the variables at the OS level instead.

macOS / Linux (add to ~/.zshrc or ~/.bashrc):

bash
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
export ANTHROPIC_API_KEY="your-codegateway-api-key"

Claude Desktop must be launched from the terminal to inherit these shell variables:

bash
open -a "Claude"

Launching by double-clicking the app icon bypasses the shell environment on macOS.

Windows (System → Advanced system settings → Environment Variables):

Add as system-level variables:

  • ANTHROPIC_BASE_URL = https://api.codegateway.dev/v1
  • ANTHROPIC_API_KEY = your key

Windows environment variables are inherited by all processes, so a terminal launch is not required.

Priority: env block in claude_desktop_config.json takes precedence over system environment variables when both are set.

Verifying the Configuration

After restarting, send a message in Claude Desktop. Then check your CodeGateway Dashboard — a new request should appear in the usage log within a few seconds.

To verify the endpoint directly from the command line:

bash
curl -s https://api.codegateway.dev/v1/models \
  -H "Authorization: Bearer your-codegateway-api-key" \
  | python3 -m json.tool | head -20

A valid model list confirms the connection is working. If you get 401 Unauthorized, the key is wrong. If curl returns cleanly but Claude Desktop still fails, check the JSON for syntax errors — a trailing comma in the wrong place is the most common culprit.

Using MCP Tools Alongside a Custom Endpoint

Configuring a custom API endpoint does not interfere with MCP tools. The two are separate channels:

  • MCP tool calls (filesystem, databases, external services) go through local inter-process communication, not the API endpoint
  • Claude model inference goes through ANTHROPIC_BASE_URL

They coexist without conflict. A complete config using both looks like this:

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

In our own testing with four MCP servers active simultaneously while routing through CodeGateway, tool call latency was unchanged (P50 under 200ms). The inference path routes through Cloudflare's edge network — we measured a roughly 30% reduction in time-to-first-byte compared to the official Anthropic endpoint for the same prompt (test setup: three runs from a server in East Asia).

FAQ

The connection fails after configuring. What should I check first?

Run the curl verification command above. 401 Unauthorized means the key is wrong. A successful curl but a failing desktop client almost always means a JSON syntax error in the config file — open the file again and look for a trailing comma, mismatched braces, or missing quotes.

Does ANTHROPIC_BASE_URL need the /v1 suffix?

Yes. Claude Desktop appends the API path after the base URL, constructing requests like {ANTHROPIC_BASE_URL}/messages. Without /v1, the full path becomes api.codegateway.dev/messages, which returns 404.

Is it safe to store an API key in a local config file?

The file is readable only by the current user on a single-user machine. For personal development setups, this is standard practice. On shared machines, use the environment variable method instead — the key never touches the config file.

Can I configure different endpoints for different conversations?

Not currently. ANTHROPIC_BASE_URL is global to the Claude Desktop instance. Switching endpoints requires editing the config and restarting the application. If per-conversation model routing is important to you, Claude Code's ANTHROPIC_BASE_URL environment variable (set per shell session) gives you more granular control.

Will a Claude Desktop update wipe the config?

No. claude_desktop_config.json is user data stored separately from the application binary. Updates preserve it.

Which models does CodeGateway support in Claude Desktop?

All current Claude models — Haiku 4.5, Sonnet 4.6, and Opus 4.7 — plus OpenAI GPT models. Claude Desktop's model selector determines which model each conversation uses. CodeGateway routes based on the model field in the request and does not override it.

Do Projects and Artifacts still work?

Yes. Projects and Artifacts data is stored on the Anthropic account side and does not pass through the API. The ANTHROPIC_BASE_URL configuration only affects model inference requests. Both features continue to work normally.

Related Resources

Sources

  • Anthropic Claude Desktop documentation (2026)
  • Model Context Protocol quickstart guide (modelcontextprotocol.io)
  • Anthropic Python SDK README (github.com/anthropics/anthropic-sdk-python)

**Authoritative references:**Anthropic API getting started · Claude Code official docs

Author：CodeGateway 团队Reviewed on：2026-05-20
← Back to Blog