Point the Anthropic Python SDK at a mock server with ANTHROPIC_BASE_URL

Every other guide on this stops at the first line: the Anthropic Python SDK reads ANTHROPIC_BASE_URL, so export it and your requests go to your mock. That is true, and it is the easy 80%. The part nobody writes down is the two ways the seam fails silently, and both of them cost an afternoon if you have not seen them before.

I learned them the hard way shipping this exact mechanism in production. Fazm is an open-source macOS app that wraps Claude Code, and it lets you point the underlying agent at any Anthropic-compatible endpoint. Under the hood that is the same ANTHROPIC_BASE_URL override you use for a mock server in tests. The code that decides whether a given value is safe to forward is the most useful thing on this page, so it is below verbatim, with line numbers.

Gotcha 1: a malformed base URL bricks the client, often silently

If the value is not a complete absolute URL with a scheme and a host, you do not get a clear error at startup. You get one of two worse outcomes: the SDK treats your value as a path against the default host, so requests quietly still hit production; or it raises Invalid URL on the first call, deep inside the request path where it is easy to mistake for a network problem.

The values that bite people: a bare localhost:8083 with no scheme, a value with a stray trailing newline (you piped it through echo instead of echo -n), or a host that resolves but has no listener. The defensive move is to validate the value before you hand it to the SDK.

Here is the exact gate Fazm runs before writing anything into ANTHROPIC_BASE_URL. It lives in Desktop/Sources/Chat/ACPBridge.swift at line 301. Swift, but the rule ports to one line of Python: reject anything that is not scheme + host.

static func validCustomAPIEndpoint(_ raw: String) -> String? {
  let endpoint = raw.trimmingCharacters(in: .whitespacesAndNewlines)
  guard !endpoint.isEmpty,
    let url = URL(string: endpoint),
    let scheme = url.scheme?.lowercased(),
    scheme == "http" || scheme == "https",
    let host = url.host,
    !host.isEmpty else {
    return nil          // fall back to the default endpoint
  }
  return endpoint
}

The comment above the call site spells out the failure mode the way only production scar tissue does: a malformed value otherwise lands in ANTHROPIC_BASE_URL and makes the Anthropic SDK throw "API Error: Invalid URL" on every query, silently bricking built-in chat. The Python equivalent:

from urllib.parse import urlparse

def valid_base_url(raw: str) -> str | None:
    raw = raw.strip()
    p = urlparse(raw)
    if p.scheme in ("http", "https") and p.netloc:
        return raw
    return None  # do not pass this to the SDK

Gotcha 2: the API key is still required, and it can leak to your mock

The SDK constructor validates that a key exists before it makes any request. Point it at a mock with no ANTHROPIC_API_KEY set and you get an AnthropicError at construction time, before your mock is ever contacted. So a dummy key is not optional, it is what lets the client get far enough to call your server at all.

There is a second, sharper edge once you go past tests into a real gateway: whatever key is in the environment gets sent in the x-api-key header to whatever host ANTHROPIC_BASE_URL points at. If that host is a third-party proxy or a teammate's mock, you have just handed your real Anthropic key to it. Fazm handles this by overwriting the bundled key with a harmless placeholder the moment a custom endpoint is set (ACPBridge.swift, lines 2426 to 2433):

if let customEndpoint = Self.validCustomAPIEndpoint(rawCustomEndpoint) {
  env["ANTHROPIC_BASE_URL"] = customEndpoint
  env["FAZM_CUSTOM_API_ENDPOINT"] = "true"
  // Never send the bundled Anthropic key to a custom endpoint.
  // A placeholder keeps Anthropic-compatible gateways on the
  // API-key path instead of triggering Claude OAuth.
  env["ANTHROPIC_API_KEY"] = "sk-fazm-custom-endpoint"
}

The lesson generalizes: when the base URL is not the real Anthropic API, the key in the environment should be a throwaway, not your live credential. In tests this is automatic because you use sk-test. In any setup where the base URL is user-configurable, scrub the real key the same way Fazm does.