How to Configure Proxies and Custom HTTP Transports in the Anthropic Python SDK

Configure proxies in the Anthropic Python SDK by setting standard environment variables (HTTP_PROXY, HTTPS_PROXY) for automatic detection, or pass a custom DefaultHttpxClient with explicit proxy and transport arguments for fine-grained control.

The anthropic-sdk-python repository provides a robust HTTP client wrapper that simplifies proxy configuration and custom transport setup. Whether you are operating behind a corporate firewall or need to bind to specific local network interfaces, the SDK's DefaultHttpxClient class—implemented in src/anthropic/_base_client.py—exposes the necessary hooks to configure proxies and HTTP transports without modifying low-level networking code.

Understanding the Default HTTP Client Architecture

The Anthropic SDK does not use a raw httpx.Client directly. Instead, it wraps the client in DefaultHttpxClient, which adds two critical capabilities for enterprise networking:

1. Environment-variable proxy parsing: Automatically reads HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY via the get_environment_proxies() utility in src/anthropic/_utils/_httpx.py.
2. Custom transport injection: Accepts pre-configured httpx.HTTPTransport or httpx.AsyncHTTPTransport objects via the transport argument, bypassing HTTPX's default proxy auto-discovery.

When the SDK constructs a client, it builds a proxy mount map that associates URL schemes (e.g., http://, https://) with dedicated HTTPTransport instances configured for those proxies. Hosts listed in NO_PROXY are explicitly mapped to None, ensuring direct connections bypass the proxy entirely.

Method 1: Environment Variable Proxy Configuration

The simplest way to route Anthropic API calls through a proxy is to set standard environment variables before importing the SDK. The get_environment_proxies() function in src/anthropic/_utils/_httpx.py parses these variables and returns a mapping that the SDK uses to configure httpx.Proxy objects.

Set the variables in your shell:

export HTTP_PROXY="http://proxy.corp.example.com:3128"
export HTTPS_PROXY="http://proxy.corp.example.com:3128"
export NO_PROXY="localhost,127.0.0.1,.internal.corp"

Then instantiate the client normally:

from anthropic import Anthropic

client = Anthropic()

# The SDK automatically detects the proxy configuration from the environment

response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, world"}]
)

Behind the scenes, the SDK constructs a proxy_mounts dictionary where "http://" and "https://" point to HTTPTransport instances configured with the proxy URL, while patterns matching NO_PROXY are set to None to force direct connections.

Method 2: Explicit Proxy and Transport Configuration

For scenarios where environment variables are insufficient—such as when you need to bind to a specific local IP address, use custom SSL certificates, or programmatically switch proxies—pass a configured DefaultHttpxClient to the http_client argument.

This approach disables HTTPX's built-in proxy auto-discovery and uses your supplied transport verbatim:

import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    http_client=DefaultHttpxClient(
        proxy="http://proxy.corp.example.com:3128",
        transport=httpx.HTTPTransport(
            local_address="10.0.0.10",  # Bind to specific network interface

            verify="/path/to/custom-ca-bundle.crt"
        )
    ),
)

response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=500,
    messages=[{"role": "user", "content": "Summarize the benefits of custom transports"}]
)

The DefaultHttpxClient class, defined in src/anthropic/_base_client.py, merges your custom transport and proxy settings with the SDK's default timeouts and retry policies, ensuring consistent behavior while allowing network-level customization.

Method 3: Per-Request Proxy Overrides

When you need different proxy settings for a single API call without affecting the global client configuration, use the .with_options() helper. This method returns a new client instance with the specified HTTP client, leaving the original client unchanged:

from anthropic import Anthropic, DefaultHttpxClient

anthropic = Anthropic()

# Use a different proxy just for this specific request

response = anthropic.messages.with_options(
    http_client=DefaultHttpxClient(proxy="http://other.proxy:3128")
).create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

This pattern is particularly useful in multi-tenant applications where different users require different egress routes, or when calling the Anthropic API through rotating proxy pools for high-availability scenarios.

Async Client Configuration

The Anthropic SDK provides AsyncAnthropic for asynchronous applications. The proxy and transport configuration works identically to the sync client, using httpx.AsyncHTTPTransport:

import httpx
from anthropic import AsyncAnthropic, DefaultHttpxClient

async_client = AsyncAnthropic(
    http_client=DefaultHttpxClient(
        proxy="http://proxy.corp.example.com:3128",
        transport=httpx.AsyncHTTPTransport(local_address="0.0.0.0")
    ),
)

async def main():
    response = await async_client.messages.create(
        model="claude-3-5-sonnet-20240620",
        max_tokens=200,
        messages=[{"role": "user", "content": "Explain quantum entanglement"}],
    )
    print(response.content)

# Run with asyncio

The DefaultHttpxClient wrapper automatically detects whether it is being used with Anthropic or AsyncAnthropic and applies the appropriate transport type.

Key Implementation Files

Understanding the source code helps debug complex networking issues. These files contain the core proxy and transport logic:

File	Purpose	Location
src/anthropic/_base_client.py	Constructs DefaultHttpxClient, builds proxy mount maps, and handles custom transport injection	View source
src/anthropic/_utils/_httpx.py	Contains get_environment_proxies() which parses HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY	View source
tests/test_utils/test_proxy.py	Unit tests verifying proxy parsing and bypass behavior	View source

Summary

• Environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) are automatically detected by the SDK's get_environment_proxies() utility in src/anthropic/_utils/_httpx.py, requiring no code changes.
• Explicit configuration via DefaultHttpxClient allows you to set specific proxy URLs, custom HTTPTransport settings (like local_address or SSL verification), and bypass environment variable detection.
• Per-request overrides using .with_options() enable temporary proxy switches for individual API calls without affecting the global client state.
• Async support mirrors the sync API using AsyncAnthropic and httpx.AsyncHTTPTransport.

Frequently Asked Questions

Does the Anthropic SDK support standard HTTP_PROXY environment variables?

Yes. The SDK automatically reads HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY through the get_environment_proxies() function in src/anthropic/_utils/_httpx.py. When these variables are set, the SDK constructs httpx.HTTPTransport instances with the appropriate proxy configuration for each scheme, while hosts listed in NO_PROXY are mapped to None to ensure direct connections.

Can I use a custom SSL certificate bundle with the proxy configuration?

Yes. When explicitly configuring a custom transport via DefaultHttpxClient, pass the verify parameter to httpx.HTTPTransport (or httpx.AsyncHTTPTransport). This accepts a path to a CA bundle file or a ssl.SSLContext object. The SDK will use this transport verbatim, applying your custom SSL settings to all requests routed through the proxy.

How do I bypass the proxy for specific internal hosts?

Use the NO_PROXY environment variable to specify comma-separated hostnames, domains, or IP addresses that should connect directly. The SDK's get_environment_proxies() utility parses NO_PROXY and creates a mapping where matching hosts are set to None, preventing the proxy from being used. Alternatively, when using explicit configuration, you can construct separate HTTPTransport instances with and without proxy settings and mount them to specific URL patterns using the mounts parameter.

Is there a difference between sync and async proxy configuration?

The configuration API is identical for both sync and async clients. Use Anthropic with httpx.HTTPTransport for synchronous applications, and AsyncAnthropic with httpx.AsyncHTTPTransport for asynchronous applications. Both accept the same DefaultHttpxClient wrapper with proxy and transport arguments, and both respect the same environment variable conventions for automatic proxy detection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}