Custom Auth

For authentication beyond Bearer tokens and OAuth, pass any httpx.Auth object to get full control over request authentication.

Built-in Options

Basic Auth
Digest Auth
NetRC

HTTP Basic Auth encodes username:password in Base64:

from httpx import BasicAuth
from mcp_use import MCPClient

config = {
    "mcpServers": {
        "secure": {
            "url": "https://secure.example.com/mcp/sse",
            "auth": BasicAuth("username", "password")
        }
    }
}

More secure than Basic - password never sent in cleartext:

from httpx import DigestAuth

config = {
    "mcpServers": {
        "digest": {
            "url": "https://digest.example.com/mcp/sse",
            "auth": DigestAuth("username", "password")
        }
    }
}

Load credentials from ~/.netrc:

from httpx import NetRCAuth

config = {
    "mcpServers": {
        "netrc": {
            "url": "https://example.com/mcp/sse",
            "auth": NetRCAuth()
        }
    }
}

~/.netrc:

machine example.com
login myuser
password mypassword

Custom Implementations

Create your own by subclassing httpx.Auth:

API Key in Header

import httpx

class ApiKeyAuth(httpx.Auth):
    def __init__(self, api_key: str, header_name: str = "X-API-Key"):
        self.api_key = api_key
        self.header_name = header_name

    def auth_flow(self, request: httpx.Request):
        request.headers[self.header_name] = self.api_key
        yield request

# Usage
config = {
    "mcpServers": {
        "api": {
            "url": "https://api.example.com/mcp/sse",
            "auth": ApiKeyAuth("your-api-key", "X-API-Key")
        }
    }
}

API Key in Query Parameter

import httpx

class QueryParamAuth(httpx.Auth):
    def __init__(self, api_key: str, param_name: str = "api_key"):
        self.api_key = api_key
        self.param_name = param_name

    def auth_flow(self, request: httpx.Request):
        url = request.url.copy_add_param(self.param_name, self.api_key)
        request.url = url
        yield request

# Usage
config = {
    "mcpServers": {
        "api": {
            "url": "https://api.example.com/mcp/sse",
            "auth": QueryParamAuth("your-api-key")
        }
    }
}

Request Signing (HMAC)

For APIs requiring request signatures:

import httpx
import hmac
import hashlib
import time

class SignatureAuth(httpx.Auth):
    def __init__(self, api_key: str, api_secret: str):
        self.api_key = api_key
        self.api_secret = api_secret

    def auth_flow(self, request: httpx.Request):
        timestamp = str(int(time.time()))
        message = f"{request.method}{request.url.path}{timestamp}"

        signature = hmac.new(
            self.api_secret.encode(),
            message.encode(),
            hashlib.sha256
        ).hexdigest()

        request.headers["X-API-Key"] = self.api_key
        request.headers["X-Timestamp"] = timestamp
        request.headers["X-Signature"] = signature
        yield request

Multiple Headers

Add several authentication headers at once:

import httpx

class MultiHeaderAuth(httpx.Auth):
    def __init__(self, headers: dict[str, str]):
        self.headers = headers

    def auth_flow(self, request: httpx.Request):
        for key, value in self.headers.items():
            request.headers[key] = value
        yield request

# Usage
config = {
    "mcpServers": {
        "multi": {
            "url": "https://api.example.com/mcp/sse",
            "auth": MultiHeaderAuth({
                "X-API-Key": "your-api-key",
                "X-Tenant-ID": "tenant-123"
            })
        }
    }
}

Combining with Headers

You can use both auth and headers together:

config = {
    "mcpServers": {
        "api": {
            "url": "https://api.example.com/mcp/sse",
            "headers": {
                "X-Custom-Header": "static-value"
            },
            "auth": BasicAuth("user", "pass")
        }
    }
}

The auth object handles dynamic authentication while headers adds static headers to every request.

When to Use What

Scenario	Approach
API key in custom header	Custom `ApiKeyAuth`
API key in query string	Custom `QueryParamAuth`
Request signing (AWS, etc.)	Custom signature class
Username/password	`httpx.BasicAuth` or `DigestAuth`
OAuth 2.0	Use built-in OAuth
Static bearer token	Use Bearer Token

When implementing custom auth:

Never log credentials
Use hmac.compare_digest for signature comparison
Store secrets in environment variables

Get Started

MCP Server

MCP Client

MCP Agents

Development

Built-in Options

Custom Implementations

Combining with Headers

When to Use What

​Built-in Options

​Custom Implementations

​Combining with Headers

​When to Use What

Built-in Options

Custom Implementations

Combining with Headers

When to Use What