# How to Configure Provider Settings Server-Side in OpenMAIC: A Complete Guide

> Learn how to configure provider settings server-side in OpenMAIC by editing the config object in lib/ai/providers.ts. This guide covers metadata, endpoints, and authentication.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-12

---

**You configure provider settings server-side in OpenMAIC by editing the `config` object in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts), where each provider's metadata, endpoints, and authentication requirements are defined, and the server validates these settings at lines 1622–1631 before routing requests.**

OpenMAIC centralizes AI and web-search provider management through a server-side configuration system that controls availability, routing, and authentication without requiring client-side changes. The configuration resides in a TypeScript map that the server loads at startup and references during request validation. This guide explains how to modify these settings to add custom providers, update endpoints, or disable services entirely.

## Understanding the Server-Side Configuration Architecture

OpenMAIC stores provider definitions in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) within a `config` object typed as `Record<string, ProviderSettings>`. This map contains comprehensive metadata for each provider, including the human-readable name, service type (`web-search` or `llm`), default base URL, display icon, API key requirements, and supported model identifiers.

When the server boots, it loads this configuration—typically from static JSON or environment variables—and maintains it in memory for the application lifecycle. During request handling, the server looks up the appropriate provider settings using the `providerId` supplied in the request payload, specifically around lines 1622–1631 of [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) according to the source code.

## How to Configure Providers in OpenMAIC

### Adding a New Provider

To add a new AI or web-search provider, insert a new entry into the `config` map following the `ProviderSettings` interface structure:

```typescript
// lib/ai/providers.ts
const config: Record<string, ProviderSettings> = {
  // ...existing providers...

  awesomeSearch: {
    name: 'Awesome Search',
    type: 'web-search',
    defaultBaseUrl: 'https://api.awesome-search.com',
    icon: '🦸‍♂️',
    requiresApiKey: true,
    models: [],  // Empty for web-search providers
  },
};

```

For LLM providers, include the supported models array:

```typescript
myGpt: {
  name: 'My GPT',
  type: 'llm',
  defaultBaseUrl: 'https://api.mygpt.com/v1',
  icon: '🧠',
  requiresApiKey: true,
  models: ['gpt-4', 'gpt-3.5-turbo'],
},

```

### Modifying Existing Providers

Update existing provider configurations by modifying the specific fields within the `config` object. Use the spread operator to preserve existing properties while updating specific values:

```typescript
// Update the Exa provider endpoint
exa: {
  ...config.exa,
  defaultBaseUrl: 'https://api.exa.ai/v2',  // New endpoint version
},

```

### Disabling Providers Server-Side

To disable a provider temporarily or permanently, remove or comment out its entry from the `config` object. When a request specifies a `providerId` that lacks a corresponding configuration entry, the server returns a 403 `PROVIDER_DISABLED` error, preventing access to that service:

```typescript
// tavily: { ... }  // Removed - requests will now fail with PROVIDER_DISABLED

```

## Provider Configuration Field Reference

Each provider settings record in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) contains the following fields:

- **`name`** – Human-readable label displayed in the UI (e.g., `'MiniMax'`).
- **`type`** – Service category that determines request routing logic (`'web-search'` or `'llm'`).
- **`defaultBaseUrl`** – Fallback endpoint URL used when the client does not supply a custom URL.
- **`icon`** – Emoji or icon string shown beside the provider name in settings dialogs.
- **`requiresApiKey`** – Boolean flag indicating whether the server must validate an API key before forwarding requests.
- **`models`** – Array of supported model identifiers for LLM-type providers; optional for pure web-search services.

## Server-Side Request Validation Flow

When configuring provider settings server-side in OpenMAIC, understanding the validation pipeline ensures your changes work as expected:

1. **Request Receipt** – The server receives a request at an endpoint like `/api/web-search` containing a `providerId` parameter.

2. **Provider Lookup** – The system executes the lookup logic at lines 1622–1631 of [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) to retrieve `providerSettings = config[providerId]`.

3. **Authentication Validation** – If `providerSettings.requiresApiKey` is `true` and no valid API key is present in the request, the server aborts with a 403 `PROVIDER_DISABLED` error as demonstrated in [`tests/web-search/route.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/web-search/route.test.ts).

4. **Adapter Selection** – Based on `providerSettings.type`, the server routes the request to the appropriate handler (e.g., `searchWithMiniMaxMock` for web-search or chat adapters for LLM).

5. **Response Processing** – The provider's response is standardized and returned to the client, with error handling managed through the configuration-defined settings.

## Summary

- OpenMAIC stores server-side provider settings in the `config` object within [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts), which acts as the single source of truth for provider metadata and endpoints.
- Each provider configuration requires fields including `name`, `type`, `defaultBaseUrl`, `icon`, `requiresApiKey`, and `models` to control UI rendering and request routing.
- The server validates configurations at lines 1622–1631 during request processing, returning a 403 `PROVIDER_DISABLED` error when providers are missing or improperly authenticated.
- You can add, modify, or remove providers directly in the TypeScript configuration file, with changes taking effect after server redeployment.

## Frequently Asked Questions

### How do I add a custom LLM provider to OpenMAIC?

Add a new entry to the `config` object in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) with `type: 'llm'` and populate the `models` array with supported model identifiers like `'gpt-4'` or `'claude-3'`. Ensure you specify `defaultBaseUrl` and set `requiresApiKey` based on the provider's authentication requirements.

### What happens if the API key is missing for a provider that requires it?

The server returns a 403 status code with a `PROVIDER_DISABLED` error message. This validation occurs during the provider lookup phase (lines 1622–1631) before any external API calls are made, ensuring requests cannot proceed without proper credentials.

### Where does the server validate provider settings during request handling?

The validation occurs in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) around lines 1622–1631, where the server looks up `providerSettings = config[providerId]`. This is the critical checkpoint where the system verifies the provider exists, checks API key requirements, and determines the appropriate adapter for the request type.

### Can I configure providers without restarting the OpenMAIC server?

No, OpenMAIC loads the provider configuration at startup from the static `config` object in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts). Any changes to provider settings require rebuilding and redeploying the server, or restarting the development server, for the new configuration to take effect.