> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomajordomo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Your Code

> Point any SDK at the Majordomo gateway with one config change.

Change the base URL. Add the `X-Majordomo-Key` header. Nothing else.

## OpenAI SDK

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://gateway.gomajordomo.com/v1",
      api_key="your-openai-api-key",
      default_headers={"X-Majordomo-Key": "mdm_sk_your_key_here"},
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
  )
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://gateway.gomajordomo.com/v1',
    apiKey: process.env.OPENAI_API_KEY,
    defaultHeaders: { 'X-Majordomo-Key': 'mdm_sk_your_key_here' },
  });

  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
  ```

  ```bash curl theme={null}
  curl -X POST https://gateway.gomajordomo.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "X-Majordomo-Key: mdm_sk_your_key_here" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}]}'
  ```
</CodeGroup>

Streaming works unchanged — the gateway proxies the SSE stream transparently.

***

## Anthropic SDK

<CodeGroup>
  ```python Python theme={null}
  import anthropic

  client = anthropic.Anthropic(
      base_url="https://gateway.gomajordomo.com",
      api_key="your-anthropic-api-key",
  )

  response = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello!"}],
      extra_headers={"X-Majordomo-Key": "mdm_sk_your_key_here"},
  )
  ```

  ```javascript Node.js theme={null}
  import Anthropic from '@anthropic-ai/sdk';

  const client = new Anthropic({
    baseURL: 'https://gateway.gomajordomo.com',
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  const response = await client.messages.create(
    {
      model: 'claude-sonnet-4-6',
      max_tokens: 1024,
      messages: [{ role: 'user', content: 'Hello!' }],
    },
    { headers: { 'X-Majordomo-Key': 'mdm_sk_your_key_here' } },
  );
  ```

  ```bash curl theme={null}
  curl -X POST https://gateway.gomajordomo.com/v1/messages \
    -H "Content-Type: application/json" \
    -H "X-Majordomo-Key: mdm_sk_your_key_here" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```
</CodeGroup>

Prompt caching tokens (`cache_read_input_tokens`, `cache_creation_input_tokens`) are tracked and priced separately.

***

## Pydantic AI

No adapter needed — point Pydantic AI's underlying provider client at the gateway and add the `X-Majordomo-Key` header. The same pattern works for any framework that lets you configure the base URL and headers of its HTTP client.

```python theme={null}
from anthropic import AsyncAnthropic
from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.providers.anthropic import AnthropicProvider

# Route the underlying client through the gateway
client = AsyncAnthropic(
    base_url="https://gateway.gomajordomo.com",
    api_key="your-anthropic-api-key",
    default_headers={"X-Majordomo-Key": "mdm_sk_your_key_here"},
)

model = AnthropicModel(
    "claude-sonnet-4-6",
    provider=AnthropicProvider(anthropic_client=client),
)

agent = Agent(model=model, system_prompt="You are a helpful assistant.")
result = await agent.run("Summarize this document: ...")
```

Add per-request metadata by passing extra headers through the model settings — for example `AnthropicModelSettings(extra_headers={"X-Majordomo-Feature": "document-summarizer"})` on the `agent.run(...)` call.

***

## majordomo-llm

A unified async Python client for OpenAI, Anthropic, Gemini, and more — with built-in cost tracking, structured output, and multi-provider cascade. Route it through the gateway by passing `base_url` and `default_headers` to `get_llm_instance`.

```bash theme={null}
pip install majordomo-llm
```

```python theme={null}
from majordomo_llm import get_llm_instance, LLMCascade

GATEWAY = "https://gateway.gomajordomo.com"
HEADERS = {"X-Majordomo-Key": "mdm_sk_your_key_here"}

# Basic completion
llm = get_llm_instance(
    "anthropic",
    "claude-sonnet-4-6",
    base_url=GATEWAY,
    default_headers=HEADERS,
)
response = await llm.get_response("Summarize this document: ...")
print(response.content)
print(f"Cost: ${response.total_cost:.6f}")

# Structured output
from pydantic import BaseModel

class Sentiment(BaseModel):
    label: str
    score: float

result = await llm.get_structured_json_response(
    response_model=Sentiment,
    user_prompt="Analyze: 'This product is excellent'",
)
print(result.content.label)   # "positive"
print(result.content.score)   # 0.95

# Multi-provider cascade — falls back on failure
cascade = LLMCascade(
    [("anthropic", "claude-sonnet-4-6"), ("openai", "gpt-4o")],
    base_url=GATEWAY,
    default_headers=HEADERS,
)
response = await cascade.get_response("Hello!")
```

[GitHub →](https://github.com/go-majordomo/majordomo-llm)

***

## Metadata tagging

Add any `X-Majordomo-*` header to tag requests for cost attribution. Works with all SDKs above.

```python theme={null}
# OpenAI
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_headers={
        "X-Majordomo-Feature": "document-review",
        "X-Majordomo-Team": "legal",
        "X-Majordomo-User-Id": "user_123",
    },
)

# Anthropic — same pattern, add to extra_headers
response = client.messages.create(
    ...,
    extra_headers={
        "X-Majordomo-Key": "mdm_sk_your_key_here",
        "X-Majordomo-Feature": "contract-analysis",
        "X-Majordomo-Team": "legal",
    },
)
```

See [Cost Attribution](/guides/cost-attribution) for how to query this data.