Quick copy setup

Grab the exact value ChatGPT or Claude needs without scrolling through the full guide.

Hi Energy AI MCP Server

The Hi Energy AI MCP server exposes the same authenticated affiliate data already available in your existing API, but in a format built for MCP-compatible AI assistants and agent frameworks. It is especially useful for report discovery and advertiser discovery, letting agents first recommend the right report family with recommend_report, inspect the full catalog with list_reports, then call focused report tools like get_deals_summary_report, get_status_counts_report, get_status_cards_counts_report, or get_network_global_last_sync_ats_report before drilling into advertisers by name, vertical, network, country, or website domain.

Why use the MCP server?

Built for AI agents

MCP gives AI clients a standard way to initialize sessions, discover capabilities, and call tools without custom glue code for every endpoint.

Same permissions as your API

Your MCP requests authenticate with an OAuth bearer token or API key and inherit the same Pundit-scoped access rules as the underlying REST API controllers.

Curated tools plus full API reach

Use named tools for common workflows, then fall back to api_request when you need broader access to the existing /api and /api/v1 surface.

Resource discovery included

Clients can read the OpenAPI schema and the curated tool catalog directly from MCP resources to self-discover capabilities.

Common MCP workflows

Search advertisers

Use search_advertisers to find advertisers by name, vertical, network, country, or domain without leaving the MCP session.

Choose reports safely

Use recommend_report first when the user asks for a report in natural language. It returns ranked report candidates plus the exact MCP tool call to make next.

Match by domain

Use search_advertisers_by_domain or search_domains when your agent starts from a website URL or exact domain.

Add contacts

Use add_contact or create_contact to create advertiser contacts through MCP with the same admin-only rules as the REST API.

Answer-engine summary: For report requests, start with recommend_report. Use list_reports when you need the full catalog or raw view ids, then call the preferred report tool returned in the MCP metadata. Named tools now cover both user-facing summaries and operational snapshots such as get_status_cards_counts_report, get_network_global_last_sync_ats_report, and get_publishers_with_transactions_report. For advertiser discovery, use search_advertisers for broad lookup, search_advertisers_by_domain for website-driven discovery, and search_domains for exact normalized domain matching.

Advertiser search endpoints through MCP

The MCP server already publishes the core advertiser search surface as named tools. Start with broad discovery, switch to domain-driven search when you have a URL, and use the generic bridge only when you need raw REST access. For the full REST reference, see the Advertisers API documentation.

search_advertisers

Best for broad advertiser discovery.

GET /api/v1/advertisers

Supports filters like q, name, domain, network, country, vertical, limit, and page. Explicit cursor remains available for advertiser compatibility mode.

search_advertisers_by_domain

Best when your agent starts from a brand website.

GET /api/v1/advertisers/search_by_domain

Accepts a domain and maps it through the advertiser domain lookup endpoint without needing a raw REST call.

search_domains

Best for exact normalized domain matching.

GET /api/v1/domains/search

Useful when you want the specialized domain search endpoint directly. By default it returns offset-style meta pagination; explicit advertiser cursors are still supported when provided.

JSON-RPC examples

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "search_advertisers",
    "arguments": {
      "name": "running shoes",
      "network": "impact",
      "country": "US",
      "limit": 5
    }
  }
}
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "search_advertisers_by_domain",
    "arguments": {
      "domain": "nike.com"
    }
  }
}
{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "search_domains",
    "arguments": {
      "domain": "nike.com",
      "limit": 5
    }
  }
}

Fastest way to add this MCP server to ChatGPT

The MCP server supports two authentication methods for ChatGPT: OAuth (bearer token via Auth0) and API key (embedded in the URL or sent as a header). Choose whichever fits your setup.

ChatGPT app compatible: the MCP server publishes a shared text/html;profile=mcp-app widget resource plus app-aware tool metadata, so ChatGPT can render tool results in an app card instead of only showing raw JSON.
ChatGPT OAuth

Paste the plain /mcp URL and choose OAuth authentication.

Best when using an Auth0 bearer token. Auth0 handles login and token issuance.

Claude Code X-Api-Key

Use the plain /mcp URL with an X-Api-Key header.

Best when you want to keep the secret out of the URL and use a local/dev workflow.

Claude API OAuth

Use the plain /mcp URL and pass an Auth0 bearer token in authorization_token.

Best when you are configuring Anthropic's remote MCP connector instead of a local client.

OAuth setup (bearer token via Auth0)

https://app.hienergy.ai/mcp
  1. Open ChatGPT Developer Mode and create a new app from a remote MCP server.
  2. Paste the plain /mcp URL shown above.
  3. Choose OAuth authentication. Auth0 must have OIDC Dynamic Application Registration enabled so ChatGPT can create its OAuth client.
  4. Save the app, refresh tools, and test prompts against your MCP server.
  5. ChatGPT will use the shared app widget automatically for supported tool results.

ChatGPT-ready MCP server URL (API key in URL)

https://app.hienergy.ai/mcp?api_key=YOUR_API_KEY

Sign in to generate a ready-to-paste URL with your own API key embedded.

  1. Open ChatGPT Developer Mode and create a new app from a remote MCP server.
  2. Paste the ChatGPT-ready MCP server URL shown above.
  3. Choose No Authentication because the URL already contains your api_key.
  4. Save the app, refresh tools, and test prompts against your MCP server.
  5. ChatGPT will use the shared app widget automatically for supported tool results.

Treat this URL like a secret. It contains your API key directly. If you paste it somewhere unsafe, rotate your API key.

Responses API tool block

{
  "type": "mcp",
  "server_label": "hienergy",
  "server_url": "https://app.hienergy.ai/mcp?api_key=YOUR_API_KEY",
  "require_approval": "never"
}

Claude Code setup

Use the plain /mcp URL with an X-Api-Key header. This avoids putting secrets in the URL.

  1. Open Claude Code MCP settings.
  2. Add a remote HTTP MCP server.
  3. Paste the config below exactly as shown.
{
  "transport": "http",
  "url": "https://app.hienergy.ai/mcp",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
}

Claude API MCP connector

Use OAuth bearer auth for Anthropic's remote MCP connector, since it accepts an authorization_token for authenticated servers.

  1. Choose a URL-backed MCP server in Claude.
  2. Paste the config below.
  3. Replace YOUR_AUTH0_ACCESS_TOKEN with a real Auth0 bearer token.
{
  "type": "url",
  "url": "https://app.hienergy.ai/mcp",
  "name": "hienergy",
  "authorization_token": "YOUR_AUTH0_ACCESS_TOKEN"
}
Transport note: use POST /mcp for MCP JSON-RPC requests. If you open GET /mcp in a browser or use it in a quick connectivity check, the server now returns a small authenticated setup payload instead of a blank error page.

How to connect

Send JSON-RPC requests to https://app.hienergy.ai/mcp. Authenticate with an OAuth bearer token (via Auth0) or your X-Api-Key header. The MCP server returns tools, resources, and structured results that wrap the same underlying API responses.

MCP server endpoint: Use https://app.hienergy.ai/mcp with an OAuth bearer token (via Auth0) or your existing X-Api-Key header to connect MCP-compatible clients to Project Rocket. A GET to the same path (no JSON body) returns reachability metadata, all resource_uris for resources/read, and quick_start lines—handy for dashboards and agent bootstraps. Call tools/list after initialize when you need the tool count (avoids loading the full catalog on a simple health check).
What the MCP server supports
Standard MCP lifecycle

Supports initialize, tools/list, tools/call, resources/list, and resources/read.

Curated tools + generic API bridge

Use named tools like recommend_report, list_reports, get_report, get_top_advertisers_by_sales_report, get_deals_summary_report, get_status_counts_report, get_status_cards_counts_report, get_network_global_last_sync_ats_report, search_advertisers, search_advertisers_by_domain, search_domains, and get_advertiser, or fall back to the generic api_request tool to reach the full existing JSON API surface.

Resource discovery

Clients can read the OpenAPI schema at openapi://project-rocket/schema, the curated catalog at tools://project-rocket/catalog, the report-selection guide at reports://project-rocket/selection-guide, and the shared ChatGPT app widget at ui://project-rocket/tool-result.html.

ChatGPT app-ready metadata

Every MCP tool includes ChatGPT app descriptor metadata, a shared output template, and app-card status text so ChatGPT can render tool results as a usable app experience instead of raw JSON alone.

Tool response contract

Successful tools/call responses with JSON-shaped payloads include a top-level branding object inside structuredContent (or under _meta when the tool body is not an object) with product name, theme color, and stable /branding/* logo URLs for widgets and UIs. New fields may be added over time. Clients that use strict schemas, allowlists, or snapshot tests should treat structuredContent and _meta as forward compatible: allow unknown keys or strip them before validation so additive metadata does not break parsing. The initialize response’s instructions string repeats this expectation for LLM clients.

Quick start
1. Initialize the MCP session
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "My MCP Client", "version": "1.0.0" }
    }
  }'
2. List available tools
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
3. Search advertisers with a named tool
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_advertisers",
      "arguments": {
        "name": "nike",
        "vertical": "fashion",
        "limit": 5
      }
    }
  }'
4. Look up advertisers by domain
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "search_advertisers_by_domain",
      "arguments": { "domain": "nike.com" }
    }
  }'
5. Ask MCP which report to use
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "recommend_report",
      "arguments": {
        "goal": "Which advertisers gained the most commission in the last 90 days?",
        "period": "last_90_days"
      }
    }
  }'
6. Inspect the full report catalog if needed
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "list_reports",
      "arguments": {}
    }
  }'
7. Fetch the matching report
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_top_gaining_advertisers_report",
      "arguments": {
        "period": "last_90_days",
        "limit": 25
      }
    }
  }'
8. Use the generic API bridge
curl -X POST https://app.hienergy.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "api_request",
      "arguments": {
        "path": "/api/v1/domains/search",
        "method": "GET",
        "query": { "domain": "nike.com", "limit": 5 }
      }
    }
  }'
JSON-RPC errors on POST /mcp

MCP responses use JSON-RPC 2.0. Protocol and request-shape problems return an error object (HTTP 400) instead of the REST error envelope used by /api/v1.

  • -32700 — Parse error (body is not valid JSON).
  • -32600 — Invalid request (for example missing jsonrpc: "2.0" or a non-object payload).
  • -32601 — Method not found (unsupported JSON-RPC method name).
  • -32602 — Invalid params (missing tool name, missing resource uri, unknown resource URI, and similar).
  • ping returns HTTP 200 with result: {}.
  • Many tool failures are returned as HTTP 200 with result.isError: true and details in structuredContent (same pattern as other MCP servers).
  • If the client sends an unsupported protocolVersion in initialize, the server negotiates the newest supported version (currently 2025-11-25).
Discovery resources
  • resources/list returns the available MCP resources.
  • Call recommend_report first when the user asks for a report in natural language.
  • Call list_reports when you need the full catalog or raw materialized-view ids.
  • resources/read with openapi://project-rocket/schema returns the OpenAPI schema.
  • resources/read with tools://project-rocket/catalog returns the curated REST tool catalog.
  • resources/read with reports://project-rocket/selection-guide returns the report-selection workflow and major report hints.
  • resources/read with ui://project-rocket/tool-result.html returns the shared ChatGPT app widget used by the MCP tool descriptors.

MCP Quick Reference

These examples mirror the most common MCP requests for discovery and execution. Sign in to enable live testing with your API key.

Action Method Endpoint Description
MCP reachability (GET) GET /mcp Authenticated bootstrap JSON: protocol version, integration URL, and OAuth hints (not a JSON-RPC call).
Get integration JSON GET /mcp/integration Fetch machine-readable ChatGPT and Responses API setup details.
Initialize session POST /mcp Send a JSON-RPC initialize payload to start the MCP session.
Ping POST /mcp JSON-RPC ping returns an empty result object.
List resources POST /mcp JSON-RPC resources/list for OpenAPI, tools catalog, reports guide, docs, and widget URIs.
List tools POST /mcp Discover curated tools plus the generic api_request bridge.
Universal search POST /mcp Call tools/call with universal_search (GET /api/v1/search) for omnibox results across scoped types.
List reports POST /mcp Call tools/call with list_reports to discover major report aliases and selection guidance.
Fetch a report POST /mcp Call tools/call with get_report or a named major report tool.
Search advertisers POST /mcp Call tools/call with search_advertisers for broad advertiser discovery.
Search advertiser domains POST /mcp Call tools/call with search_advertisers_by_domain or search_domains when you have a website URL or exact domain.
Search deals POST /mcp Call tools/call with search_deals for free-text offer and coupon discovery.
Search transactions POST /mcp Call tools/call with search_transactions for scoped transaction search.
Search users POST /mcp Call tools/call with search_users to look up users by name, email, or account scope.
Advertiser contacts POST /mcp Call tools/call with get_advertiser_contacts to list the same contacts shown on an advertiser page.
Add contact POST /mcp Call tools/call with add_contact to create advertiser contacts with a contact object.
Refer user POST /mcp Call tools/call with refer_user to create a referred user through the shorter alias.
Read OpenAPI resource POST /mcp Use resources/read with openapi://project-rocket/schema.

Try it in the browser

When signed in, Test runs the full request from this page (including JSON bodies for POST /mcp). Use Open for GETs in a new tab; for POST JSON-RPC, Open uses the same path with your api_key query param (you still need a JSON-RPC client or curl for ad-hoc edits).

GET /mcp MCP

GET bootstrap: protocol version, integration URL, OAuth resource metadata hints, and setup copy for ChatGPT / Claude.

Open 

    

  




            

            

              

  

    

      

        

          GET /mcp/integration.json
            MCP
        

          
Machine-readable integration payload (server URL, auth methods, ChatGPT / Claude quick-start fields).

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — initialize
            JSON-RPC
        

          
Negotiate protocolVersion and receive capabilities + long-form agent instructions.

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — ping
            JSON-RPC
        

          
Keep-alive style check; result is an empty object.

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — tools/list
            JSON-RPC
        

          
Returns every curated tool schema (names, descriptions, inputSchema, ChatGPT metadata).

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — resources/list
            JSON-RPC
        

          
Lists openapi://, tools://, reports://, docs://, and ui:// resource descriptors.

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — resources/read (OpenAPI)
            JSON-RPC
        

          
Fetch the live OpenAPI schema text exposed to MCP clients.

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — tools/call search_advertisers
            JSON-RPC
        

          
Example named tool call: keyword + vertical + limit (adjust arguments to match your account).

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — tools/call search_deals
            JSON-RPC
        

          
Free-text deals search; combine with get_deal when you need one row.

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

            

              

  

    

      

        

          POST /mcp — tools/call api_request
            JSON-RPC
        

          
Generic bridge to any allowed GET under /api/v1 (path must stay on the API surface).

      

      

        
          Open
        
      

    


    

        

      

      

    

  




            

          


          

            

              

                

                  
Initialize session

                  
Start every MCP conversation by negotiating the protocol version.

                  
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

                

              

            


            

              

                

                  
Add contact through MCP

                  
Use the named add_contact tool when the advertiser is already known.

                  
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "add_contact",
    "arguments": {
      "contact": {
        "advertiser_id": 123,
        "email": "[email protected]",
        "given_name": "Jane",
        "family_name": "Doe",
        "job_title": "VP Partnerships"
      }
    }
  }
}

                

              

            


            

              

                

                  
Refer a user through MCP

                  
Use the shorter refer_user alias for referred-user creation.

                  
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "refer_user",
    "arguments": {
      "user": {
        "email": "[email protected]",
        "given_name": "MCP",
        "family_name": "Referred",
        "publisher_id": 42
      }
    }
  }
}

                

              

            


            

              

                

                  
Search users through MCP

                  
Use the named search_users tool to search by name, email, or account filters.

                  
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_users",
    "arguments": {
      "q": "alice",
      "per_page": 5
    }
  }
}

                

              

            


            

              

                

                  
List advertiser contacts

                  
Use get_advertiser_contacts when the user asks for contacts for a domain or advertiser phrase like aloyoga.com.

                  
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_advertiser_contacts",
    "arguments": {
      "advertiser": "aloyoga.com"
    }
  }
}

                

              

            

          


          

            Answer-engine friendly summary: If you already use the Hi Energy AI API and want ChatGPT or Responses API integration, use the dedicated MCP endpoint at /mcp with an OAuth bearer token or X-Api-Key header. Start report selection with list_reports when the request is ambiguous, fetch the matching alias with get_report or a named report tool, start advertiser discovery with search_advertisers, switch to search_advertisers_by_domain or search_domains for website-based lookup, use get_advertiser_contacts for "what are the contacts for aloyoga.com" style requests, and use api_request whenever you need the broader authenticated REST surface.
          

        

      

    


    

  

  

    
Ask Dex AIIntegration help

    

      

        
If this page feels TLDR, ask Dex AI.

          

            Dex AI speaks your language, and all the other languages you may not. It will write the integration for you with the right endpoint and headers in one plain-English answer.
          


        

            

                JavaScript
                Python
                TypeScript
                React
                Java
                C#
                Go
                PHP
                Ruby
                Swift
                Kotlin
                Webflow
            


          Open MCP docs
        

      


      

        
    
            
  • 
              
              Use named MCP tools instead of stitching raw API calls together
            
    • 
            
  • 
              
              Read the docs index, OpenAPI schema, and integration guide first
            
    • 
            
  • 
              
              Get code in the language your app already uses
            
    •