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. HiEnergy admins can also use api_get and api_write from tools/list when a curated tool does not cover the allowed API operation; those generic bridges stay hidden for non-admin clients.

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 for permitted writes, or api_write when you are a HiEnergy admin; 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.

Claude connector

The published Hi Energy connector is the supported path for Claude.ai and Claude Cowork. Connect from the directory, complete Auth0 sign-in, and Claude uses your account-scoped MCP tools automatically.

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

Cowork follows the same connector and OAuth identity. HiEnergy admins can still inspect managed_mcp_server policy details in the authenticated integration JSON when debugging; non-admin users 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"
    }
  }
}

FAQ