# How to Migrate to a Different Embedding Provider in Claude Context: A Complete Guide

> Migrate embedding providers in Claude Context effortlessly. Update config with new provider details and API key. No code changes needed. Restart MCP or VS Code to complete.

- Repository: [Zilliz/claude-context](https://github.com/zilliztech/claude-context)
- Tags: migration-guide
- Published: 2026-04-22

---

**To migrate embedding providers in Claude Context, update your configuration with the new provider identifier and API key, then restart the MCP process or VS Code extension—no code changes required.**

Claude Context provides a unified interface for embedding providers that lets you switch between OpenAI, VoyageAI, Gemini, and Ollama without modifying your indexing or search logic. This guide walks you through the complete migration process using the actual source code implementation from the `zilliztech/claude-context` repository.

## Understanding the Embedding Provider Architecture

Claude Context abstracts all embedding providers behind a small, uniform interface. Each provider implements this interface in its own class—`OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, and `OllamaEmbedding`—and is instantiated through a factory that reads your current configuration.

The embedding factory in [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) creates the appropriate concrete class based on your settings. Once created, this instance is injected into the indexing and search pipelines in [`packages/mcp/src/handlers.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/handlers.ts), meaning the rest of the system works unchanged regardless of which provider you select.

## Where Configuration Is Stored

Configuration lives in different locations depending on how you use Claude Context:

| Scope | Storage Location | How It's Read |
|-------|------------------|---------------|
| **CLI / MCP** | Environment variables (`EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, `OPENAI_API_KEY`, etc.) | [`packages/mcp/src/config.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/config.ts) parses environment variables and builds a `ContextMcpConfig` object |
| **VS Code extension** | VS Code settings (`semanticCodeSearch.embeddingProvider.*`) | [`packages/vscode-extension/src/config/configManager.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/config/configManager.ts) reads settings and creates an embedding instance via `ConfigManager.createEmbeddingInstance` |

## Step-by-Step Migration Process

### Step 1: Choose Your New Provider and Obtain API Credentials

Ensure you have a valid API key for your target provider. Claude Context supports:

- **OpenAI** — requires `OPENAI_API_KEY`
- **VoyageAI** — requires `VOYAGEAI_API_KEY`
- **Gemini** — requires `GEMINI_API_KEY`
- **Ollama** — requires `OLLAMA_HOST` (typically `http://127.0.0.1:11434`)

### Step 2: Update Your Configuration

**For MCP/CLI usage**, set the appropriate environment variables:

```bash

# Example: migrate from OpenAI to Gemini

export EMBEDDING_PROVIDER=Gemini
export GEMINI_API_KEY=your-gemini-key-here
export EMBEDDING_MODEL=gemini-embedding-001  # optional — defaults defined in config.ts

```

**For VS Code extension**, open **Settings** → **Extensions → Claude Context** and modify:

- `semanticCodeSearch.embeddingProvider.provider` → set to `Gemini` (or `OpenAI`, `VoyageAI`, `Ollama`)
- `semanticCodeSearch.embeddingProvider.apiKey` → enter your new API key
- `semanticCodeSearch.embeddingProvider.model` → optionally specify a model name
- `semanticCodeSearch.embeddingProvider.outputDimensionality` → for Gemini, optionally set dimensions (3072, 1536, 768, or 256)

### Step 3: Restart to Apply Changes

Reload or restart the MCP process or VS Code extension so it reads the new configuration. The factory in [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) will then instantiate the correct concrete class.

### Step 4: Validate the Migration

Run the built-in embedding test to confirm your new provider is working:

**CLI:**

```bash
npx @zilliz/claude-context-mcp@latest --test-embedding

```

**VS Code:** Use the "Test Embedding" button in the extension UI (implemented in `semanticSearchProvider.testEmbedding`).

Successful output will show:

```

[EMBEDDING] Creating Gemini embedding instance...
[EMBEDDING] ✅ Gemini embedding instance created successfully

```

### Step 5: Re-Index If Needed

If you want existing codebase embeddings to use the new provider, re-index your files. The MCP automatically regenerates embeddings for new or changed files. Because embedding dimensions may differ between providers (Gemini supports 3072, 1536, 768, or 256), the snapshot migration routine in [`packages/mcp/src/snapshot.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/snapshot.ts) automatically stores snapshots in the latest v2 format after loading older snapshots—you don't need to manually modify snapshot files.

## Code Examples for Provider Migration

### Creating an Embedding Instance Manually

The factory pattern used internally can be replicated for custom integrations:

```typescript
import { createEmbeddingInstance } from '@zilliz/claude-context-mcp/embedding';

// Example: switch to VoyageAI at runtime
const cfg = {
  embeddingProvider: 'VoyageAI',
  embeddingModel: 'text-embedding-3-small',
  // API key is read from process.env.VOYAGEAI_API_KEY
};

const embedding = createEmbeddingInstance(cfg);
console.log(`Using ${embedding.getProvider()} with dimension ${embedding.getDimension()}`);

```

### Testing a New Provider in VS Code Extension

From [`semanticSearchProvider.ts`](https://github.com/zilliztech/claude-context/blob/main/semanticSearchProvider.ts), the test method demonstrates runtime provider switching:

```typescript
// Inside semanticSearchProvider.ts
await this.testEmbedding(
  {
    provider: 'Ollama',
    config: { model: 'mxbai-embed-large', baseURL: 'http://127.0.0.1:11434' },
  },
  webview,
);

```

### Re-Indexing After Provider Change

The handler pipeline in [`packages/mcp/src/handlers.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/handlers.ts) shows how the embedding instance is injected:

```typescript
// packages/mcp/src/handlers.ts – indexing flow
const embedding = this.context.getEmbedding();   // newly created after config change
console.log(`[BACKGROUND-INDEX] 🧠 Using embedding provider: ${embedding.getProvider()}`);
await this.indexFiles(files, embedding);

```

## Key Source Files for Embedding Migration

| File | Role | Link |
|------|------|------|
| [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) | Factory that builds the concrete embedding class from configuration | [embedding.ts](https://github.com/zilliztech/claude-context/blob/master/packages/mcp/src/embedding.ts) |
| [`packages/mcp/src/config.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/config.ts) | Reads environment variables, provides defaults, and logs chosen provider/model | [config.ts](https://github.com/zilliztech/claude-context/blob/master/packages/mcp/src/config.ts) |
| [`packages/vscode-extension/src/config/configManager.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/config/configManager.ts) | Manages VS Code settings for embedding provider and creates instances | [configManager.ts](https://github.com/zilliztech/claude-context/blob/master/packages/vscode-extension/src/config/configManager.ts) |
| [`packages/vscode-extension/src/webview/semanticSearchProvider.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/webview/semanticSearchProvider.ts) | UI-side testing of embedding connections | [semanticSearchProvider.ts](https://github.com/zilliztech/claude-context/blob/master/packages/vscode-extension/src/webview/semanticSearchProvider.ts) |
| [`packages/mcp/src/handlers.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/handlers.ts) | Shows how embedding instances are injected into indexing and search pipelines | [handlers.ts](https://github.com/zilliztech/claude-context/blob/master/packages/mcp/src/handlers.ts) |
| [`packages/mcp/src/snapshot.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/snapshot.ts) | Handles automatic migration of snapshots to v2 format when dimensions change | [snapshot.ts](https://github.com/zilliztech/claude-context/blob/master/packages/mcp/src/snapshot.ts) |
| [`python/test_context.ts`](https://github.com/zilliztech/claude-context/blob/main/python/test_context.ts) | Example script demonstrating embedding creation and usage | [test_context.ts](https://github.com/zilliztech/claude-context/blob/master/python/test_context.ts) |

## Summary

- **Embedding provider migration in Claude Context requires only configuration changes** — no code modifications needed due to the uniform interface abstraction in [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts).

- **Update environment variables for CLI/MCP** or **VS Code settings for the extension**, supplying the new provider identifier, API key, and optional model name.

- **Validate your migration** using the built-in embedding test before re-indexing your codebase.

- **Snapshot files auto-migrate** to v2 format when dimensions differ between providers, handled transparently in [`packages/mcp/src/snapshot.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/snapshot.ts).

- **Supported providers**: OpenAI, VoyageAI, Gemini, and Ollama — each with dedicated implementation classes following the same factory pattern.

## Frequently Asked Questions

### What happens to my existing embeddings when I switch providers?

Existing embeddings stored in snapshots are automatically handled. When you load an older snapshot with [`packages/mcp/src/snapshot.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/snapshot.ts), the system detects the format and migrates it to the latest v2 format upon saving. If embedding dimensions differ between your old and new providers, the MCP will regenerate embeddings for new and changed files automatically. For a complete re-embedding of your entire codebase, trigger a full re-index after switching providers.

### Can I use different embedding providers for different projects?

Yes, but with constraints. For the **CLI/MCP**, each running process reads from environment variables, so you can set different providers per terminal session or project by exporting different values before starting the MCP. For the **VS Code extension**, the settings are workspace-scoped by default, allowing per-project provider configuration through [`.vscode/settings.json`](https://github.com/zilliztech/claude-context/blob/main/.vscode/settings.json). The factory in [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) instantiates the provider at startup based on whatever configuration is active.

### Why does my embedding test fail after changing providers?

The most common causes are **missing or incorrect API keys** and **unreachable endpoints**. Verify that your environment variable or VS Code setting contains the exact key name expected by [`packages/mcp/src/config.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/config.ts)—for example, `GEMINI_API_KEY` for Gemini, not `GOOGLE_API_KEY`. For Ollama, ensure the server is running at the configured `OLLAMA_HOST`. Check the logs from [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) which outputs the provider name and dimensionality on successful instantiation—absence of this log indicates a factory failure.

### Do I need to modify my code when migrating embedding providers?

No code modifications are required. The [`packages/mcp/src/embedding.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/embedding.ts) factory creates the appropriate concrete class (`OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, or `OllamaEmbedding`) based solely on configuration. This instance is then injected into indexing and search pipelines in [`packages/mcp/src/handlers.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/mcp/src/handlers.ts). The uniform interface ensures that `getEmbedding()`, `embedTexts()`, and `getDimension()` methods work identically regardless of which provider is active.