Use NinjaProxy with MCP Clients

NinjaProxy runs a hosted remote MCP server at https://mcp.ninjasproxy.com/mcp. Set your NINJAPROXY_API_KEY once and any MCP-capable assistant — Claude, Cursor, Codex, Hermes, and others — gets direct access to your account, proxy inventory, usage, and billing data.

Recommended: use the hosted remote MCP server. No npm install, no local process to manage, no manual header wiring — your client and the hosted server handle the transport details for you.

Quick start

Get your API key from the portal dashboard and export it.

# 1. Copy your API key from the NinjaProxy portal.
# 2. Export it once.
export NINJAPROXY_API_KEY="np_..."

Then pick your MCP client below and paste the matching server entry. Every config below reads NINJAPROXY_API_KEY from your environment — your client and the hosted server handle the transport details internally.

Available tools

• get_profile — your account profile
• get_plan — your current plan
• list_proxy_endpoints — your assigned proxy inventory
• get_usage_summary — billing-period usage totals
• get_usage_live — same-day live usage
• get_billing_summary — balance, credits, and plan summary
• list_client_ips — your allowlisted client IPs
• add_client_ip — add a client IP to your allowlist
• remove_client_ip — remove a client IP from your allowlist

Claude Desktop

Add the following to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). With NINJAPROXY_API_KEY set in your environment, your client is connected — no further setup needed.

{
  "mcpServers": {
    "ninjaproxy": {
      "type": "http",
      "url": "https://mcp.ninjasproxy.com/mcp",
      "env": {
        "NINJAPROXY_API_KEY": "${env:NINJAPROXY_API_KEY}"
      }
    }
  }
}

Cursor

Add the following to .cursor/mcp.json in your project root, or to ~/.cursor/mcp.json for a global setup. Set NINJAPROXY_API_KEY in your environment or in Cursor’s secrets panel.

{
  "mcpServers": {
    "ninjaproxy": {
      "type": "http",
      "url": "https://mcp.ninjasproxy.com/mcp",
      "env": {
        "NINJAPROXY_API_KEY": "${env:NINJAPROXY_API_KEY}"
      }
    }
  }
}

Codex CLI

Run this once. Codex CLI stores the server config for future sessions. Make sure NINJAPROXY_API_KEY is exported in your shell first.

codex mcp add ninjaproxy \
  --url https://mcp.ninjasproxy.com/mcp \
  --env NINJAPROXY_API_KEY=$NINJAPROXY_API_KEY

Hermes

Add the following to your Hermes MCP server config. The exact config file location depends on your Hermes version — see the Hermes docs for the right path. Set NINJAPROXY_API_KEY in your environment or Hermes secrets store.

{
  "ninjaproxy": {
    "url": "https://mcp.ninjasproxy.com/mcp",
    "env": {
      "NINJAPROXY_API_KEY": "${NINJAPROXY_API_KEY}"
    }
  }
}

Recommended setup prompt

Once your client is connected, this prompt pattern keeps the assistant grounded in the right sequence of NinjaProxy resources.

Use these NinjaProxy resources in order:
1. https://ninjasproxy.com/llms.txt
2. https://ninjasproxy.com/openapi.json
3. The specific docs page for my task

Build the final copy-paste command first.
If I provide a portal-assigned endpoint, use that exact host and port.
Do not invent credentials, endpoint assignments, or billing state.

Local stdio fallback

The @ninjaproxy/mcp-server npm package runs a local stdio MCP process on your machine. Use this only when you need to keep all traffic on your own host — for example, in a locked-down or air-gapped environment where an outbound HTTPS connection to mcp.ninjasproxy.com is not allowed.

For most setups, prefer the hosted remote MCP server above.

{
  "mcpServers": {
    "ninjaproxy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ninjaproxy/mcp-server"],
      "env": {
        "NINJAPROXY_API_KEY": "${env:NINJAPROXY_API_KEY}"
      }
    }
  }
}

The local package also supports NINJAPROXY_BEARER_TOKEN, optional NINJAPROXY_USERNAME, and an optional NINJAPROXY_BASE_URL override. See the package README for the full env reference.

Important rules for assistants

• Do not invent assigned endpoint ports or alternate hostnames.
• Prefer the exact customer endpoint copied from the portal for assigned/static inventory.
• For rotating gateways, change the username controls or request parameters, not the gateway host and port.
• Balance, whitelist mode, and concurrency limits can all fail otherwise-correct requests.

Bootstrap manifest

If your client supports resource bootstrapping, point it at the NinjaProxy manifest for stable AI discovery of docs, the customer OpenAPI spec, and prompt patterns.

Manifest: /mcp.json

• llms.txt — product overview, routing rules, and canonical docs links.
• openapi.json — customer API surface.
• Docs routes for quick start, auth, rate limits, and API reference.