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

# Configuration

> Configure the MutagenT TypeScript SDK

# SDK Configuration

## Client Options

```typescript theme={null}
import { Mutagent } from '@mutagent/sdk';
import type { SDKOptions } from '@mutagent/sdk';

const client = new Mutagent({
  // Authentication (optional if MUTAGENT_API_KEY env var is set)
  security: {
    apiKey?: string,       // API key (sends x-api-key header)
    bearerAuth?: string,   // OAuth token (sends Authorization: Bearer header)
  },

  // Optional configuration
  serverURL?: string,      // Custom API URL (default: https://api.mutagent.io)
  serverIdx?: number,      // Server index (0 = default)
  timeoutMs?: number,      // Request timeout in ms
  retryConfig?: RetryConfig,

  // Advanced
  httpClient?: HTTPClient, // Custom HTTP client
  debugLogger?: Logger,    // Debug logging
});
```

## Authentication

The SDK supports two authentication methods. The `apiKey` is tried first; if present, `bearerAuth` is skipped.

<Mermaid>
  flowchart TD
  Start\["SDK Request"] --> Check{"apiKey present?"}
  Check -->|"Yes"| ApiKey\["Send x-api-key header"]
  Check -->|"No"| CheckBearer{"bearerAuth present?"}
  CheckBearer -->|"Yes"| Bearer\["Send Authorization: Bearer header"]
  CheckBearer -->|"No"| EnvVar{"MUTAGENT_API_KEY env var?"}
  EnvVar -->|"Yes"| ApiKey
  EnvVar -->|"No"| Fail\["SecurityError"]

  style Start fill:#7C3AED,color:#fff
  style ApiKey fill:#06B6D4,color:#000
  style Bearer fill:#06B6D4,color:#000
  style Fail fill:#EF4444,color:#fff
</Mermaid>

### API Key (Recommended)

```typescript theme={null}
import { Mutagent } from '@mutagent/sdk';

// Simplest: SDK auto-reads MUTAGENT_API_KEY env var
const client = new Mutagent();

// Explicit: pass API key directly
const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY },
});

// With custom server
const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY },
  serverURL: 'https://api.mutagent.io',
});
```

### Bearer Auth (OAuth)

For OAuth flows, use `bearerAuth`:

```typescript theme={null}
const client = new Mutagent({
  security: { bearerAuth: 'your-oauth-token' },
});
```

For dynamic token refresh, pass a `security` function:

```typescript theme={null}
const client = new Mutagent({
  security: async () => ({
    bearerAuth: await refreshToken(),
  }),
});
```

## Environment Variables

The SDK automatically reads these environment variables:

| Variable               | Header Sent             | Purpose                    |
| ---------------------- | ----------------------- | -------------------------- |
| `MUTAGENT_API_KEY`     | `x-api-key`             | API key authentication     |
| `MUTAGENT_BEARER_AUTH` | `Authorization: Bearer` | OAuth token authentication |

```bash theme={null}
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
```

```typescript theme={null}
import { Mutagent } from '@mutagent/sdk';

// No explicit auth needed -- env var is auto-read
const client = new Mutagent();
```

## Timeout Configuration

```typescript theme={null}
const client = new Mutagent({
  timeoutMs: 60000, // 60 seconds
});
```

## Retry Configuration

```typescript theme={null}
const client = new Mutagent({
  retryConfig: {
    strategy: 'backoff',
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      exponent: 1.5,
      maxElapsedTime: 300000,
    },
    retryConnectionErrors: true,
  },
});
```

## Per-Request Options

Override configuration for individual requests:

```typescript theme={null}
const prompts = await client.prompt.listPrompts(
  { limit: 50 },
  {
    timeoutMs: 120000,  // 2 minute timeout for this request
    retries: {
      strategy: 'none', // No retries for this request
    },
  }
);
```

## Debug Logging

```typescript theme={null}
const client = new Mutagent({
  debugLogger: console, // Log all requests and responses
});
```

## Custom HTTP Client

For advanced use cases (proxies, custom TLS, request interceptors), provide your own HTTP client:

```typescript theme={null}
import { Mutagent, HTTPClient } from '@mutagent/sdk';

const customClient: HTTPClient = {
  async request(input, init) {
    // Add custom headers, logging, etc.
    return fetch(input, init);
  },
};

const client = new Mutagent({
  httpClient: customClient,
});
```