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

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 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, 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 parses environment variables and builds a ContextMcpConfig object
VS Code extension	VS Code settings (semanticCodeSearch.embeddingProvider.*)	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:

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

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

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, the test method demonstrates runtime provider switching:

// 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 shows how the embedding instance is injected:

// 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	Factory that builds the concrete embedding class from configuration	embedding.ts
packages/mcp/src/config.ts	Reads environment variables, provides defaults, and logs chosen provider/model	config.ts
packages/vscode-extension/src/config/configManager.ts	Manages VS Code settings for embedding provider and creates instances	configManager.ts
packages/vscode-extension/src/webview/semanticSearchProvider.ts	UI-side testing of embedding connections	semanticSearchProvider.ts
packages/mcp/src/handlers.ts	Shows how embedding instances are injected into indexing and search pipelines	handlers.ts
packages/mcp/src/snapshot.ts	Handles automatic migration of snapshots to v2 format when dimensions change	snapshot.ts
python/test_context.ts	Example script demonstrating embedding creation and usage	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.

• 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.

• 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, 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. The factory in 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—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 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 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. The uniform interface ensures that getEmbedding(), embedTexts(), and getDimension() methods work identically regardless of which provider is active.

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