Use NinjaProxy with MCP Clients

If your editor or assistant supports MCP-style resource bootstrapping, point it at the NinjaProxy manifest first. That gives the client one stable entry point for our AI guide, customer OpenAPI spec, and the core docs routes.

Bootstrap manifest: /mcp.json

Understand the surfaces

• /mcp.json is a public bootstrap manifest for docs and API discovery. It helps assistants find the right NinjaProxy docs and API references.
• npx -y @ninjaproxy/mcp-server starts the local stdio MCP package published on npm. That is the standard customer setup path today.
• The local stdio package talks to the production NinjaProxy customer API by default. Most customers should not need to override the API base URL.
• A remote HTTP MCP server may exist later as a separate integration surface, but customers should not assume that a remote server URL replaces the local npm package unless the docs explicitly publish it.

What the manifest includes

• llms.txt for product rules, route selection guidance, and canonical links.
• openapi.json for the customer API surface.
• Docs routes for quick start, auth, rate limits, API, and MCP guidance.

Example client config

Some MCP-capable tools can ingest a bootstrap manifest before you configure the local package. If your client supports that flow, use the public NinjaProxy manifest as the resource root and then add a task-specific prompt.

{
  "ninjaproxy": {
    "type": "http",
    "url": "/mcp.json"
  }
}

Recommended setup prompt

Once your client can read the manifest, this prompt pattern keeps the assistant grounded in the right sequence of 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.

When to use which resource

• Use llms.txt first when you need high-level product rules or proxy-type selection.
• Use openapi.json when the task is account API auth, usage, billing, inventory, or subscription automation.
• Use Rotating proxies when the task depends on username controls, sticky sessions, or HTTP routing headers.
• Use Authentication when proxy auth or allowlisting is the likely failure point.

Local stdio fallback

The standard customer setup is the local stdio package. It keeps the MCP process on your machine and calls the production NinjaProxy customer API directly with your own credentials.

Package: @ninjaproxy/mcp-server

The current package supports NINJAPROXY_BEARER_TOKEN, NINJAPROXY_API_KEY, optional NINJAPROXY_USERNAME, and optional NINJAPROXY_BASE_URL.

Standard bearer-token example

If you already have a production portal JWT, this is the shortest path. The package uses the default production API base URL automatically.

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

API key example

If your workflow uses a production NinjaProxy API key, you can pass it directly or pair it with NINJAPROXY_USERNAME for Basic auth.

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

Codex example

codex mcp add ninjaproxy \
  --env NINJAPROXY_BEARER_TOKEN=$NINJAPROXY_BEARER_TOKEN \
  -- npx -y @ninjaproxy/mcp-server

Advanced override

NINJAPROXY_BASE_URL is an advanced override for internal testing or unusual customer environments. It is not part of the normal production setup path.

{
  "mcpServers": {
    "ninjaproxy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ninjaproxy/mcp-server"],
      "env": {
        "NINJAPROXY_BASE_URL": "https://api.ninjasproxy.com",
        "NINJAPROXY_BEARER_TOKEN": "${env:NINJAPROXY_BEARER_TOKEN}"
      }
    }
  }
}

The local stdio package mirrors the approved read-only account tool set from the remote MCP server: account, balance, usage, proxy inventory, proxy URL generation, session format help, and troubleshooting help.

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 HTTP headers, not the gateway host and port.
• Balance, whitelist mode, and concurrency limits can all fail otherwise-correct requests.