Hyper Solutions — Codex Plugin

A Codex plugin that teaches Codex to integrate and debug the Hyper Solutions anti-bot API (Akamai, Incapsula, DataDome, Kasada) across the Go, Python, and JavaScript/TypeScript SDKs and the raw REST API — and to debug failing requests by inspecting captured traffic.

It bundles two things:

1. A skill (skills/hypersolutions/SKILL.md + references/) with the full integration + debugging playbook, including a request-fingerprinting principles reference (references/request-rules.md) for spotting the mistakes that get request-based bots blocked (the exhaustive, always-current checks run in the har-analyzer MCP below).
2. Two MCP servers (.mcp.json):
   • powhttp — inspect your script's real wire traffic (header order + TLS fingerprint) live and apply those rules to it.
   • har-analyzer — a hosted server that runs the same rule set against an exported HAR and returns structured findings (analyze_har).

Ask Codex things like:

• "Help me set up the Akamai sensor flow in Python with tls-client."
• "My DataDome slider solve returns 403 — capture my script with powhttp and tell me what's wrong."
• "Analyze my captured requests and find why I'm getting blocked."
• "Why is my _abck cookie never becoming valid?"

Install

Requires the Codex CLI (npm install -g @openai/codex). Register this repo as a marketplace, then install the plugin — skill and both MCP servers:

codex plugin marketplace add Hyper-Solutions/hypersolutions-codex
codex plugin add hypersolutions@hypersolutions

The har-analyzer MCP server is OAuth-protected, so authenticate it once (a browser opens for a Hyper Solutions sign-in):

codex mcp login har-analyzer

Restart the Codex app afterward. The plugin then appears under Settings → Plugins, and its powhttp and har-analyzer servers under MCP servers → From plugins (you can also authenticate har-analyzer from there instead of the CLI). The skill auto-activates when your prompt matches Hyper Solutions / anti-bot integration or request-debugging work (see the description in skills/hypersolutions/SKILL.md).

The codex plugin commands are the first-party install path. The npm codex-marketplace tool registers the files but does not complete the native install, so the runtime never enables the plugin — use the commands above.

Development

To work on the plugin from a local checkout, add the repo directory as the marketplace source instead of the GitHub one:

git clone https://github.com/Hyper-Solutions/hypersolutions-codex.git
codex plugin marketplace add ./hypersolutions-codex
codex plugin add hypersolutions@hypersolutions

The bundled .agents/plugins/marketplace.json uses source: local with path: ".", so the repo root is the plugin. Re-run codex plugin add (or codex plugin marketplace upgrade) after editing to pick up changes.

Using the powhttp request debugger

The bundled MCP (.mcp.json) points at powhttp's local MCP server (http://localhost:8383/mcp). To use it:

1. Install and run powhttp; click "Run MCP server".
2. Route your failing script's traffic through powhttp's proxy (http://127.0.0.1:8080) and run the flow.
3. Ask Codex to debug it — it will query the captured requests via the powhttp MCP tools and analyze header order, TLS fingerprint, cookies, and client hints.

If powhttp isn't running the MCP simply has no tools available; you can still analyze a HAR the user exports by applying the same rules. See references/powhttp-mcp.md and references/request-rules.md.

Using the HAR analyzer

The bundled har-analyzer MCP (.mcp.json) is a hosted server (https://har-mcp.hypersolutions.co/mcp) that runs the Hyper Solutions fingerprint rule set against an exported HAR. It's the fastest way to triage a HAR a customer sends you.

Ask Codex to analyze a .har file — it calls the analyze_har tool and reports the findings (severity, category, fix) plus the detected anti-bot product. The har-analyzer server is OAuth-protected: the first time, authenticate it in Codex (click Authenticate on the server, or run codex mcp login har-analyzer) and sign in with your Hyper Solutions account. No API key needed.

A HAR lacks the true wire header order and TLS fingerprint, so a clean result doesn't rule out those — prefer powhttp for the live wire. See references/har-analyzer-mcp.md.

What's inside

.codex-plugin/plugin.json         Plugin manifest
.agents/plugins/marketplace.json  Marketplace catalog entry for this plugin
.mcp.json                         Bundled MCP servers: powhttp (local) + har-analyzer (hosted)
skills/hypersolutions/
  SKILL.md                        Entry point: mental model, requirements, routing, debugging
  scripts/sec_ch_ua.py            Compute the exact sec-ch-ua (GREASE) for a Chrome version
  references/
    authentication.md             x-api-key, JWT x-signature, organization headers
    tls-and-headers.md            TLS fingerprinting, header order, IP/proxy, Chrome version
    akamai.md                     Sensor (_abck), sec-cpt 428, SBSD 429, pixel
    incapsula.md                  reese84, reese84 dynamic, utmvc, captcha block
    datadome.md                   interstitial, slider, tags
    kasada.md                     Flow 1/2, payload/cd/botid, POW, Vercel BotID
    api-reference.md              All endpoints, fields, per-SDK signatures, raw HTTP
    powhttp-mcp.md                Live request-capture debugging via the powhttp MCP
    har-analyzer-mcp.md           Automated HAR fingerprint analysis via the har-analyzer MCP
    request-rules.md              Fingerprint principles for powhttp/live captures & writing requests
    debugging.md                  Symptom → cause → fix

Maintaining this plugin (IP boundary)

Everything shipped in this repo is public — a marketplace reader sees it without an API key. Keep the valuable, evolving detection logic out of it. The rule when editing:

• Static files (SKILL.md, references/, scripts/) hold only how to use the API and generally-known browser-fingerprinting facts (header order, sec-ch-ua GREASE, public cookie/endpoint names). This is documentation, not the moat.
• The har-analyzer MCP (server-side) holds the exhaustive and current detection rules — exact thresholds, per-product flow checks, anything that changes as detection evolves. New or updated detection logic goes there, not here.
• Don't add: reverse-engineering of an anti-bot's internals (obfuscation/VM/payload generation), exact internal thresholds, or named customer/target apps. Describe formats generically and point users to Hyper Solutions for specifics.

When in doubt: if it teaches someone to use the API, it can live here; if it reveals what HS knows or checks, it belongs in the MCP.

Links

• Dashboard / API keys: https://hypersolutions.co/keys
• Docs: https://docs.hypersolutions.co
• Examples: https://github.com/Hyper-Solutions/hypersolutions-examples
• SDKs: Go · Python · JS/TS
• Support: Discord discord.gg/akamai