How to Integrate DBX with AI Providers Like Claude, OpenAI, and Ollama

DBX ships a built-in AI assistant that normalizes configuration across Claude, OpenAI, and Ollama, using a Rust core engine to handle provider-specific endpoints, authentication headers, and payload formatting.

The open-source DBX database explorer (t8y2/dbx) includes a native AI assistant capable of querying multiple large language model providers. Whether you need cloud-based models from Anthropic and OpenAI or local inference via Ollama, DBX unifies these integrations behind a single configuration interface and a high-performance Rust backend.

Architecture of the DBX AI Integration

The integration spans three distinct layers that transform user preferences into executed HTTP requests.

UI and Settings Management

The desktop application exposes an AI configuration panel at Settings → AI, where users select from predefined provider presets and enter endpoint URLs, API keys, and model names. This interface binds to the Pinia settings store defined in apps/desktop/src/stores/settingsStore.ts, which manages the reactive state and persists changes via the backend API.

Configuration Normalization

When saving settings, the store invokes normalizeAiConfig (lines 37–50 of settingsStore.ts) to validate required fields, inject defaults, and infer the provider type from the endpoint pattern. This ensures that even partial user input resolves into a complete AiConfig struct before reaching the core engine.

Core AI Engine

The Rust crate dbx-core receives the normalized configuration in crates/dbx-core/src/ai.rs. The resolve_endpoint function (lines 88–104) maps provider strings to specific API paths—such as /v1/messages for Claude or /v1/chat/completions for OpenAI-compatible services. The complete function (lines 1246–1252) orchestrates the request construction, applying the correct authentication method (Bearer token or x-api-key header) and payload shape before streaming responses back to the frontend.

Provider-Specific Setup

Each supported provider follows a standardized AiConfig schema while requiring distinct endpoint and authentication patterns.

Anthropic Claude

Claude integration uses the Messages API endpoint at https://api.anthropic.com/v1/messages. The engine sends the x-api-key header and structures requests according to Claude's messages format. Set authMethod to "api-key" and specify a model such as claude-sonnet-4-20250514.

OpenAI

For OpenAI, DBX targets the standard Chat Completions endpoint at https://api.openai.com/v1/chat/completions. The configuration uses Bearer token authentication (authMethod: "bearer") and works with models like gpt-4o-mini.

Ollama (Local Models)

Local inference via Ollama defaults to http://localhost:11434/v1. Since Ollama often runs without authentication, the configuration sets requiresApiKey: false but retains authMethod: "bearer" with an empty token. This allows the call_openai_compatible function in ai.rs to treat Ollama as an OpenAI-compatible endpoint while skipping header injection.

Implementation Examples

Adding a Provider via the Settings Store

Configure a new provider programmatically using the Pinia store:

import { useSettingsStore } from "@/stores/settingsStore";

function addOllamaProvider() {
  const store = useSettingsStore();

  store.updateAiConfig({
    provider: "ollama",
    endpoint: "http://localhost:11434/v1",
    model: "llama3.1",
    apiStyle: "completions",
    authMethod: "bearer",
    enableThinking: false,
  });
}

The updateAiConfig method (lines 91–118 of settingsStore.ts) automatically persists the configuration to disk and validates the schema.

Programmatically Querying the AI Assistant

Invoke the backend directly from your frontend code to generate SQL or receive completions:

import * as api from "@/lib/backend/api";

async function askSql(question: string) {
  const response = await api.callAiAssistant({
    systemPrompt: "You are an expert SQL assistant.",
    messages: [{ role: "user", content: question }],
    maxTokens: 1024,
  });
  return response;
}

This calls the /api/ai/complete route, which forwards to the Rust complete function in ai.rs and automatically injects the active AiConfig from the settings file.

Integrating with External AI Agents via MCP

For autonomous coding agents like Claude Code or Cursor, DBX exposes a Model Context Protocol (MCP) server in packages/mcp-server. The server reads the existing AiConfig and exposes database connection metadata via an HTTP endpoint.

Query the MCP server to enable external agents to access DBX connections:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "provider":"claude",
    "model":"claude-sonnet-4-20250514",
    "apiKey":"<your-anthropic-key>"
  }'

The response provides connection schemas that allow agents to execute SQL queries against your DBX instance without manual configuration.

Summary

• Unified Configuration: The AiConfig interface in settingsStore.ts normalizes settings for Claude, OpenAI, and Ollama into a single schema.
• Rust Core Engine: The dbx-core crate handles provider-specific endpoints, authentication headers, and payload formatting in ai.rs.
• Local Inference: Ollama runs as an OpenAI-compatible endpoint with optional authentication disabled via requiresApiKey: false.
• External Agent Support: The MCP server in packages/mcp-server bridges DBX with autonomous coding assistants using the same configuration layer.

Frequently Asked Questions

Does DBX support API keys for all providers?

No. While Claude requires a valid api-key or x-api-key header and OpenAI requires a Bearer token, Ollama typically runs locally without authentication. Set requiresApiKey: false in the AiConfig for local deployments.

Where does DBX store AI configuration settings?

Settings persist through the Pinia store in apps/desktop/src/stores/settingsStore.ts, which writes to the backend via api.saveAiConfig. The Rust core reads this configuration from the normalized settings file at runtime.

Can I use custom OpenAI-compatible endpoints?

Yes. The resolve_endpoint function in crates/dbx-core/src/ai.rs treats any endpoint string as valid if it follows the standard OpenAI Chat Completions format. Select the "openai" preset or manually configure the endpoint URL and apiStyle: "completions".

What is the MCP server used for?

The MCP server, located in packages/mcp-server, implements the Model Context Protocol to expose DBX database connections to external AI coding assistants like Claude Code and Cursor. It reads the active AiConfig and returns connection metadata that allows agents to query your databases directly.

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