Use IPMusk MCP Tools in the OpenAI Agents SDK

Who this is for

Python developers building agents with the OpenAI Agents SDK (openai-agents).

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.
Python 3.10 or later, pip install openai-agents, and an OpenAI API key for the model.

Set it up

The async with block opens the connection and closes it when the agent is done.
The agent can call every tool the key's scopes allow. Give it a key with only the scopes it needs.

agent.py

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="IPMusk",
        params={
            "url": "https://ipmusk.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['IPMUSK_API_KEY']}"},
        },
    ) as ipmusk:
        agent = Agent(
            name="Proxy assistant",
            instructions="Use the IPMusk tools to answer questions about my proxies.",
            mcp_servers=[ipmusk],
        )
        result = await Runner.run(agent, "How much residential traffic do I have left?")
        print(result.final_output)


asyncio.run(main())

Server-side alternative: hosted MCP tool

The Responses API can call IPMusk for you as a hosted MCP tool. Add a tool of type mcp with server_url set to https://ipmusk.com/mcp and pass your key in its authorization or headers field. Check the current Responses API reference for the exact field.

With a hosted tool, OpenAI's servers send your key to IPMusk. Use a key with only the scopes you need.

Tool definition (shape only)

{
  "type": "mcp",
  "server_label": "ipmusk",
  "server_url": "https://ipmusk.com/mcp",
  "authorization": "<your IPMusk API key>"
}

Check it works

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

To see the tools, call await ipmusk.list_tools() inside the async with block and print the names.

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

KeyError: 'IPMUSK_API_KEY': the variable is not set in the shell that runs the script.
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.
Import errors: upgrade with pip install -U openai-agents. MCP class names have changed between releases.

Remove access

Revoke the key in Settings → API keys (/app/settings/api-keys). It stops working at once.
Then remove the key from the environment or secret store the agent runs with.

Use IPMusk with the OpenAI Agents SDK