Use IPMusk with the Vercel AI SDK

Who this is for

TypeScript developers building with the Vercel AI SDK (the ai package).

What you need

• An IPMusk account with a verified email address.
• An IPMusk API key. Create it in Settings → API keys (/app/settings/api-keys). For typical use tick read and connect. Add support only if the assistant should open tickets, and order only if it should create orders that end in a payment link.
• The key in an environment variable named IPMUSK_API_KEY, for example export IPMUSK_API_KEY="ipm_live_YOUR_KEY" in your shell profile. The examples below read it from there.
• Node.js 18 or later, the ai and @ai-sdk/mcp packages, and a model provider package.

Set it up

• client.tools() returns every tool the key's scopes allow. Pass them to generateText or streamText.
• Always call client.close() when you are done, also after streamText finishes.
• Older AI SDK versions import experimental_createMCPClient from ai instead. Check the AI SDK docs for your version.

import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic"; // or any provider you use

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://ipmusk.com/mcp",
    headers: { Authorization: `Bearer ${process.env.IPMUSK_API_KEY}` },
  },
});

try {
  const tools = await client.tools();
  const { text } = await generateText({
    model: anthropic("YOUR_MODEL_ID"),
    tools,
    stopWhen: stepCountIs(5),
    prompt: "How much residential traffic do I have left?",
  });
  console.log(text);
} finally {
  await client.close();
}

Check it works

Run the script. It should print an answer based on your real traffic balance.

To see the tools, log Object.keys(tools).

Try these prompts

• Which IPMusk account am I connected as?
• How much residential traffic do I have left?
• Build a rotating US residential proxy URL.

If it fails

• Bearer undefined in the header: IPMUSK_API_KEY is not set in the process environment.
• 401 authentication_required: the key is missing, wrong, revoked or expired. Check that IPMUSK_API_KEY is set where the client starts. echo ${#IPMUSK_API_KEY} prints its length without showing the key.
• 403 forbidden on one tool: the key lacks that tool's scope, or your email is not verified. Scopes cannot be added to a key, so create a new key with the scope and swap it in.
• 429 rate_limited: too many calls in one minute (read 60, connect 20, support 30, order 10). Wait a minute and try again.
• The model answers without calling a tool: allow more than one step, for example stopWhen: stepCountIs(5).

Remove access

• Revoke the key in Settings → API keys (/app/settings/api-keys). It stops working at once.
• Then remove the key from your deployment's environment variables.