merge-gateway-implement

name	merge-gateway-implement
description	Integrate the Merge Gateway SDK into an existing Python or TypeScript/Node project. Detects existing LLM stack, installs the SDK, migrates client constructors and API calls to Merge Gateway's unified format, sets up credentials, and verifies the integration.
metadata	{"short-description":"Integrate Merge Gateway SDK into a project"}

Merge Gateway Integration

Integrate the Merge Gateway SDK into an existing project. Supports Python and TypeScript/Node.

Prerequisites

• A Merge Gateway account with an API key (mg_...)
• An existing project with Python or TypeScript/Node.js

Step 1: Detect Existing LLM Stack

Search for existing LLM SDK usage in the project:

Language	Files to Check	Packages to Look For
Python	requirements.txt, pyproject.toml, Pipfile, setup.py	openai, anthropic, langchain, litellm, boto3, google-generativeai
TypeScript/Node	package.json	openai, @anthropic-ai/sdk, langchain, litellm, @google/generative-ai, @azure/openai, ai, @ai-sdk/*

Also search for client constructors:

• OpenAI(, new OpenAI({, Anthropic(, AzureOpenAI(, boto3.client('bedrock'
• createOpenAI(, createAnthropic(, createGoogleGenerativeAI(, createMergeGateway(
• generateText(, streamText(, embedMany( (Vercel AI SDK)

If Vercel AI SDK is detected (ai or @ai-sdk/*), recommend the native merge-gateway-ai-sdk-provider instead. The AI SDK framework stays — only the provider changes.

Report findings to the user before proceeding.

Step 2: Set Up Credentials

1. Check if MERGE_GATEWAY_API_KEY is already set in environment or .env. If yes, confirm and move on.
2. If not, the user must provide their API key or direct them to https://gateway.merge.dev to create/copy their API key (starts with mg_).
3. Ask: "Are you setting this up for local development or a deployed environment?"
   • STOP and wait for response.

Local Development Path

Add the key to .env:

echo "MERGE_GATEWAY_API_KEY=mg_YOUR_KEY" >> .env

• Verify .gitignore includes .env. If not, add it and warn the user.

Deployed / CI/CD Path

• Add MERGE_GATEWAY_API_KEY as an environment variable in the secrets manager (AWS Secrets Manager, HashiCorp Vault, Vercel/Netlify env vars, CI/CD platform secrets).
• Do NOT create a .env file.

Security: Never ask the user to paste their API key into the conversation. Give terminal commands or instructions they execute themselves.

Step 3: Install the SDK

# Python
pip3 install merge-gateway-sdk

# TypeScript/Node
npm install merge-gateway-sdk

For Vercel AI SDK projects:

npm install merge-gateway-ai-sdk-provider

Step 4: Update SDK Configuration

Client Constructor Replacement

Python:

# Before (OpenAI)
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# After (Merge Gateway)
from merge_gateway import MergeGateway
client = MergeGateway(
    api_key=os.environ["MERGE_GATEWAY_API_KEY"],
)

TypeScript:

// Before (OpenAI)
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// After (Merge Gateway)
import { MergeGateway } from "merge-gateway-sdk";
const client = new MergeGateway({
    apiKey: process.env.MERGE_GATEWAY_API_KEY!,
});

API Call Format Change

Python:

# Before (OpenAI)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user", "content": "Hello!"},
    ],
)
print(response.choices[0].message.content)

# After (Merge Gateway)
response = client.responses.create(
    model="openai/gpt-4o",
    input=[
        {"type": "message", "role": "system", "content": "You are helpful."},
        {"type": "message", "role": "user", "content": "Hello!"},
    ],
)
print(response.output[0].content[0].text)

TypeScript:

// Before (OpenAI)
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
        { role: "system", content: "You are helpful." },
        { role: "user", content: "Hello!" },
    ],
});
console.log(response.choices[0].message.content);

// After (Merge Gateway)
const response = await client.responses.create({
    model: "openai/gpt-4o",
    input: [
        { type: "message", role: "system", content: "You are helpful." },
        { type: "message", role: "user", content: "Hello!" },
    ],
});
console.log(response.output[0].content[0].text);

Model Name Format — Provider-Prefixed

Before	After
gpt-4o	openai/gpt-4o
gpt-4o-mini	openai/gpt-4o-mini
gpt-4-turbo	openai/gpt-4-turbo
gpt-3.5-turbo	openai/gpt-3.5-turbo
claude-sonnet-4-6-20250514	anthropic/claude-sonnet-4-6-20250514
claude-3-5-haiku-20241022	anthropic/claude-3-5-haiku-20241022
gemini-1.5-pro	google/gemini-1.5-pro

Step 5: Verify Integration

Create and run a test script:

Python (test_merge_gateway.py):

import os
from merge_gateway import MergeGateway

client = MergeGateway(api_key=os.environ["MERGE_GATEWAY_API_KEY"])

response = client.responses.create(
    model="openai/gpt-4o-mini",
    input=[
        {"type": "message", "role": "user", "content": "Reply with 'Merge Gateway is working!' if this works."},
    ],
)
print(response.output[0].content[0].text)

TypeScript (test_merge_gateway.ts):

import { MergeGateway } from "merge-gateway-sdk";

const client = new MergeGateway({ apiKey: process.env.MERGE_GATEWAY_API_KEY! });

const response = await client.responses.create({
    model: "openai/gpt-4o-mini",
    input: [
        { type: "message", role: "user", content: "Reply with 'Merge Gateway is working!' if this works." },
    ],
});
console.log(response.output[0].content[0].text);

Run the test and confirm the response. If it succeeds, the integration is complete.