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

You configure provider settings server-side in OpenMAIC by editing the config object in 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 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 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:

// 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:

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:

// 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:

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

Provider Configuration Field Reference

Each provider settings record in 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 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.

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, 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 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 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. Any changes to provider settings require rebuilding and redeploying the server, or restarting the development server, for the new configuration to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}