Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Built-in Options

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")
        }
    }
}

​
Custom Implementations

Create your own by subclassing httpx.Auth: 
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")
        }
    }
}

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")
        }
    }
}
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
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

ScenarioApproach
API key in custom headerCustom ApiKeyAuth
API key in query stringCustom QueryParamAuth
Request signing (AWS, etc.)Custom signature class
Username/passwordhttpx.BasicAuth or DigestAuth
OAuth 2.0Use built-in OAuth
Static bearer tokenUse Bearer Token
When implementing custom auth:
  • Never log credentials
  • Use hmac.compare_digest for signature comparison
  • Store secrets in environment variables