Mocking the Anthropic Python SDK for local development with ANTHROPIC_BASE_URL

How base_url actually resolves in the Python SDK

The constructor signature on anthropic.Anthropic declares base_url: str | httpx.URL | None = None. When the argument is None, the SDK falls through to the environment lookup. When the environment is also empty, it uses the built-in production default. The same chain runs for AsyncAnthropic. Three states, one resolution order.

The frozen step is the one that matters for tests. A pytest fixture that calls monkeypatch.setenv AFTER constructing the client will not change the base URL the client uses. You either construct the client inside the patched scope, or you pass the mock URL explicitly through the base_url argument. Both are clean. The mistake to avoid is patching at module level and assuming a module-scoped client picked it up.

What a mocked request actually looks like

Nothing on the wire changes. The SDK still sends POST /v1/messages with x-api-key and anthropic-version headers, still expects a Messages API JSON body or an SSE stream. The mock just has to answer that. The host changes, the shape does not.

The host on line 2 is whatever you set in base_url or ANTHROPIC_BASE_URL. Mock that host and the SDK never knows the difference. The auth header is still sent even though it is meaningless, so your stub server can ignore it or assert on it depending on what you want to test.

Four ways to mock that actually work

You can stop at the cheapest one that answers the question your tests are asking. They are not interchangeable.

The pytest pattern, end to end

Two snippets that fit in any conftest.py. The first one boots a mock server in a thread and exposes its URL through a fixture. The second one constructs a client against that fixture and runs an assertion. The pattern works with Prism, fakellm, or a hand-rolled stub by swapping out the boot step.

# conftest.py
import socket
import threading
import pytest
import uvicorn
from fastapi import FastAPI

def _free_port() -> int:
    with socket.socket() as s:
        s.bind(("127.0.0.1", 0))
        return s.getsockname()[1]

@pytest.fixture(scope="session")
def anthropic_mock_url():
    app = FastAPI()

    @app.post("/v1/messages")
    def messages():
        return {
            "id": "msg_test",
            "type": "message",
            "role": "assistant",
            "model": "claude-test",
            "content": [{"type": "text", "text": "ok"}],
            "stop_reason": "end_turn",
            "usage": {"input_tokens": 1, "output_tokens": 1},
        }

    port = _free_port()
    cfg = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning")
    server = uvicorn.Server(cfg)
    thread = threading.Thread(target=server.run, daemon=True)
    thread.start()
    while not server.started:
        pass
    yield f"http://127.0.0.1:{port}"
    server.should_exit = True
    thread.join(timeout=2)

# test_my_app.py
from anthropic import Anthropic

def test_my_handler(anthropic_mock_url):
    client = Anthropic(api_key="test-key", base_url=anthropic_mock_url)
    msg = client.messages.create(
        model="claude-test",
        max_tokens=8,
        messages=[{"role": "user", "content": "hi"}],
    )
    assert msg.content[0].text == "ok"

Pass base_url explicitly so the test does not depend on whatever ANTHROPIC_BASE_URL happens to be set in CI. If you prefer the env-var form, use monkeypatch.setenv inside the test and construct a fresh client inside the patched block so the frozen-base-url rule from the resolution section does not bite you.

The footgun no Python tutorial mentions

The SDK does not validate base_url at construction time. It stores the string, hands it to httpx on the first request, and httpx is the layer that decides whether the string is a real URL. The values that bite:

• localhost:8000 (no scheme). httpx treats this as a relative URL with localhost as the scheme and 8000 as the path, then fails when it tries to send to it.
• 127.0.0.1:8000 (no scheme). Same problem. Looks valid because that is exactly how every README writes a port, but the SDK needs the scheme.
• http:// with no host. Sometimes ends up in env files because of a botched template substitution. Scheme present, host empty, httpx rejects.
• Trailing whitespace. A copy-paste from a wiki ends with a newline, httpx is strict about it. Always trim before forwarding a user-provided value.

The Python equivalent of that guard is twelve lines. If you read a base URL from a settings file or an env var, validate it once at startup rather than at the first request:

from urllib.parse import urlparse

def safe_base_url(value: str | None) -> str | None:
    if not value:
        return None
    value = value.strip()
    parsed = urlparse(value)
    if parsed.scheme not in ("http", "https"):
        return None
    if not parsed.netloc:
        return None
    return value

# usage: pass None to let the SDK fall back to its built-in default
base_url = safe_base_url(os.environ.get("ANTHROPIC_BASE_URL"))
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"],
                   base_url=base_url)

When to mock vs when to use the real API on a cheap model

Mocks are right for everything that exercises your code. Mocks are wrong for anything that exercises the model. If a test asserts that your prompt produces a particular shape of output, a mock that returns canned text will pass even when the prompt is broken. For that class of test, point the real SDK at the real API with a small model like claude-haiku-4-5-20251001, set a tight token cap, and run the test sparingly. The boundary is whether the test is about your code or the model. If it is about your code, mock. If it is about the model, do not.

The other case where the real endpoint earns its keep is streaming. The SSE protocol the SDK consumes is non-trivial, and a hand-rolled stub that misses one event type will hang the .text_stream iterator with no obvious error. Prism is good at this because it generates the stream from the spec. If you do roll your own, write a 5-line script that calls the real API once, captures the raw SSE, and replays it from a file. Replay is more honest than fabrication.

One env var, every SDK

ANTHROPIC_BASE_URL is read by the Python SDK, the TypeScript SDK, Claude Code, and any well-behaved wrapper that follows the same convention. Setting it in your shell before launching anything reroutes the whole ecosystem to the same mock host. That is convenient and dangerous. Convenient because one env in a .envrc covers everything you run during local dev. Dangerous because a forgotten export keeps biting until you notice that a real script is hitting a stale port.

The pattern that survives a year of use: scope the env var to the directory with direnv or set it explicitly per test run via monkeypatch, never put it in your login shell. The same rule applies to Claude Code when you use it from the same machine: a global export will quietly redirect it too. Read more on that resolution lifecycle in Claude Code and ANTHROPIC_BASE_URL.

Frequently asked questions