Hi Energy AI MCP Server

The Hi Energy AI MCP server exposes the same authenticated affiliate data already available in your API through a focused directory built for MCP clients. Start with universal_search for an ambiguous entity, recommend_report for a reporting goal, and named search or record tools for focused work. Use api_get and api_write only when the curated tools do not cover the allowed API operation.

Why use the MCP server?

Common MCP workflows

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.

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
    }
  }
}

GraphQL through MCP

Use graphql_query for a read-only response that needs several related resources in one request, or a custom deals / clicks / transactions selection set. It calls POST /api/v1/graphql with the same API key or OAuth identity as the rest of MCP, so GraphQL applies the same Pundit-scoped visibility rules. Prefer named tools (search_deals, get_deal, search_transactions, get_transaction, get_clicks) for a single standard list or detail call.

Deals (visible by default; hidden opt-in)

{
  "name": "graphql_query",
  "arguments": {
    "query": "query($advertiserId: ID) { deals(advertiserId: $advertiserId, perPage: 10, includeTotal: true) { nodes { id name exclusive featured effectiveAt advertiser { id name } } pageInfo { totalCount hasNextPage } } }",
    "variables": { "advertiserId": "123" }
  }
}

Clicks (≤90-day window)

{
  "name": "graphql_query",
  "arguments": {
    "query": "query($from: IsoDate!, $to: IsoDate!, $advertiserId: ID) { clicks(startDate: $from, endDate: $to, advertiserId: $advertiserId, perPage: 50) { nodes { id clickDate clickCount advertiserName networkName } pageInfo { hasNextPage } } }",
    "variables": { "from": "2026-05-19", "to": "2026-05-26", "advertiserId": "123" }
  }
}

Transactions (bounded query)

{
  "name": "graphql_query",
  "arguments": {
    "query": "query($from: IsoDate!, $to: IsoDate!) { transactions(startDate: $from, endDate: $to, status: [APPROVED, PAID], perPage: 25) { nodes { id status saleAmount commissionAmount advertiser { id name } } pageInfo { hasNextPage } } }",
    "variables": { "from": "2026-04-01", "to": "2026-04-30" }
  }
}

Terms (commission terms)

{
  "name": "graphql_query",
  "arguments": {
    "query": "query($advertiserId: ID) { terms(advertiserId: $advertiserId, perPage: 10, includeTotal: true) { nodes { id cid name summary advertiser { id name } } pageInfo { totalCount hasNextPage } } }",
    "variables": { "advertiserId": "123" }
  }
}

GraphQL is read-only. Use named mutation tools or api_write for permitted writes; do not attempt GraphQL mutations. Paginated fields return at most 200 nodes and include pageInfo; deep pages beyond the 10,000-result window are rejected. Use includeTotal: true only when a total is required. deals excludes hidden deals by default (pass includeHidden: true to include authorized hidden deals); clicks requires startDate/endDate within 90 days; transactions requires advertiserId, publisherId, networkId, or both date bounds; terms returns commission terms scoped by TermPolicy (paid-account access), with optional advertiserId, campaignId, and free-text query filters.

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.

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

{
  "transport": "http",
  "url": "https://app.hienergy.ai/mcp",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
}

{
  "type": "url",
  "url": "https://app.hienergy.ai/mcp",
  "name": "hienergy",
  "authorization_token": "YOUR_AUTH0_ACCESS_TOKEN"
}

Claude Cowork approvals

Cowork uses the same remote HTTP MCP endpoint as Claude Code. Copy the managed_mcp_server object from your authenticated integration JSON rather than hand-writing a policy. HiEnergy admins receive an allow-all policy for the full MCP catalog; non-admin users automatically allow read-only tools and are prompted before writes or external actions.

Permissions and safe client setup

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.

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" }
    }
  }'

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"
  }'

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
      }
    }
  }'

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" }
    }
  }'

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"
      }
    }
  }'

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": {}
    }
  }'

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
      }
    }
  }'

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_get",
      "arguments": {
        "path": "/api/v1/domains/search",
        "query": { "domain": "nike.com", "limit": 5 }
      }
    }
  }'

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.

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).

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

{
  "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"
      }
    }
  }
}

{
  "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
      }
    }
  }
}

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

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