IPMusk MCP Server for Claude, Codex and Cursor

What this is

MCP (Model Context Protocol) lets AI assistants such as Claude, Codex and Cursor call IPMusk directly, without you copying data between the dashboard and a chat.

The server endpoint is https://ipmusk.com/mcp. It uses the Streamable HTTP transport.

It accepts the same API keys as the REST API. Apps such as claude.ai and Claude Desktop sign in with OAuth instead. See the API documentation at /docs/api for how keys, scopes and OAuth work.

Each tool needs the key scope listed under Tools below.

Endpoint

https://ipmusk.com/mcp

Before you start

1
Create a key
Sign in to the dashboard and go to Settings, then API keys (/app/settings/api-keys). Select the scopes the assistant needs.
2
Keep it in an environment variable
Store the key in an environment variable such as IPMUSK_API_KEY. The examples below read the key from there, so it stays out of config files.

Set the variable

export IPMUSK_API_KEY="ipm_live_YOUR_KEY"

Claude Code

Run this command once in your terminal. It registers the server for Claude Code.

The full guide, with a shared .mcp.json and OAuth sign-in, is at /docs/agents/claude-code.

Add the server

claude mcp add --transport http ipmusk https://ipmusk.com/mcp --header "Authorization: Bearer $IPMUSK_API_KEY"

Use double quotes so the shell expands the variable. To check the connection, run /mcp inside Claude Code, or claude mcp list in your terminal.

Codex CLI

Add the server to ~/.codex/config.toml.

The full guide, with OAuth sign-in and checks, is at /docs/agents/codex.

~/.codex/config.toml

[mcp_servers.ipmusk]
url = "https://ipmusk.com/mcp"
bearer_token_env_var = "IPMUSK_API_KEY"

Export IPMUSK_API_KEY before you start Codex. The command codex mcp add ipmusk --url https://ipmusk.com/mcp --bearer-token-env-var IPMUSK_API_KEY does the same.

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects.

The full guide, with checks and fixes, is at /docs/agents/cursor.

.cursor/mcp.json

{
  "mcpServers": {
    "ipmusk": {
      "url": "https://ipmusk.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:IPMUSK_API_KEY}"
      }
    }
  }
}

claude.ai and Claude Desktop

claude.ai and Claude Desktop connect with OAuth. You sign in to IPMusk in your browser. You do not copy a key.

Step-by-step guides are at /docs/agents/claude for Claude and /docs/agents/chatgpt for ChatGPT.

ChatGPT and other MCP clients that support OAuth connect the same way.
Access tokens last 1 hour. The client refreshes them for you for up to 90 days, without asking for consent again.
To disconnect an app, go to Settings, then API keys, then Connected AI apps (/app/settings/api-keys), and choose Disconnect. It stops working at once.

1
Add a custom connector
In claude.ai or Claude Desktop, open Settings, then Connectors, and choose Add custom connector.
2
Enter the name and URL
Set the name to IPMusk and the URL to https://ipmusk.com/mcp. Leave OAuth client ID and OAuth client secret empty. The client registers itself.
3
Connect and sign in
Choose Connect. Your browser opens the IPMusk sign-in page. Sign in to your IPMusk account.
4
Choose the permissions and approve
Tick the permissions to grant: read, connect, support and order. Grant only what the assistant needs. Then choose Approve.

Connector URL

https://ipmusk.com/mcp

Keep order unticked unless you want the assistant to create orders. An order only produces a payment link, and you still pay yourself.

Other clients

Any MCP client that supports Streamable HTTP with a custom Authorization header works.

The server is stateless. No session is kept between calls, and each request is checked on its own.

Setup guides for Windsurf, Gemini CLI, VS Code, Cline, Zed, the OpenAI Agents SDK, the Vercel AI SDK, LangChain and the MCP Python SDK are at /docs/agents.

Tools

The server offers 21 tools. The scope after each tool name is the scope the key or OAuth grant needs.

list_products (any valid key): the products and the Static ISP categories.
list_plans (any valid key): plans with prices, filtered by product and category.
list_locations (any valid key): country codes and availability for a product.
get_quote (any valid key): a price preview. It does not create an order.
get_account (read): your account details and the key in use.
get_usage (read): residential traffic used and remaining for the last 7 or 30 days.
list_static_proxies (read): your Static ISP and Datacenter proxies, without credentials.
list_orders (read): your orders, newest first.
get_order (read): one order with its status.
list_tickets (read): your support tickets.
get_ticket (read): one ticket with its replies.
get_residential_credentials (connect): gateway host and port, username, password and remaining traffic.
build_proxy_url (connect): ready-to-use residential proxy URLs for a country, state or city, rotating or sticky.
get_static_proxy (connect): one Static ISP or Datacenter proxy with host, port, username and password.
export_static_proxies (connect): the selected proxies as txt, csv or json.
create_ticket (support): opens a support ticket.
reply_ticket (support): adds a reply to one of your tickets.
create_order (order): creates an order for a Rotating Residential plan or Static ISP and Datacenter proxies and returns a payment link. Quote first with get_quote and get the user's confirmation.
resume_checkout (order): returns a fresh payment link for an order that is not paid yet.
quote_static_renewal (order): prices a renewal of your Static ISP or Datacenter proxies for 30 or 90 days. It creates nothing.
renew_static_proxies (order): creates a renewal order and returns a payment link.

Tools without a scope work with any valid key. Tools marked connect return passwords. Tools marked order never take payment: they return a payment link that the user opens and pays. Use get_order (read scope) afterwards to check the status.

Resources

The server also publishes the documentation as Markdown, so the assistant can read it without browsing.

ipmusk://docs/api: the customer API reference.
ipmusk://docs/getting-started: choosing a product and connecting.
ipmusk://docs/troubleshooting: common checks and when to contact support.
ipmusk://docs/proxy-not-connecting: finding the cause by symptom.

Example prompts

Once the server is connected, you can ask for things like these.

Give me a sticky US California HTTP proxy URL for 10 minutes.
How much residential traffic do I have left and when does it run out?
Open a technical ticket: my static proxy in Frankfurt times out since this morning.
Buy 2 GB of residential traffic. The assistant finds the plan, quotes the price, asks you to confirm, then returns a payment link. You open the link and pay.
Renew my two Static ISP proxies in Frankfurt for 30 days. The assistant quotes the renewal first and returns a payment link after you confirm.

Limits and safety

Rate limits apply per key or per OAuth connection, per minute, and count every tool call: read 60, connect 20, support 30, order 10.
Credentials tools return passwords. Grant the connect scope only to assistants that need it.
The order scope lets an assistant create orders and renewals, but never pay for them. Grant it only to an assistant you want placing orders for you.
Orders need checkout to be open and an available payment provider. Otherwise the order tools return checkout_unavailable.
The assistant acts with the full scope you granted. If an assistant misbehaves, revoke the key or disconnect the app in Settings, then API keys.
The same source-country rules as the website apply.