Hyros MCP Server

A small server that sits between Hyros and Claude. It holds the Hyros API key, calls Hyros's attribution endpoint, and exposes the results to Claude as tools. Once it's live, Claude can pull the REAL attributed ROAS / revenue by campaign and reconcile it against Meta's self-reported numbers from Windsor.

The whole point: there is no "Hyros MCP URL" to look up anywhere. The URL only exists once this server is deployed. Deploying it is the step that creates the URL.

---

For Mac: 3 steps

1. Install

cd hyros-mcp
npm install

2. Set the API key

Set one environment variable, HYROS_API_KEY, to Andrea's new Hyros key (the regenerated one). Either copy .env.example to .env and fill it in, or set it in your host's dashboard. The key stays server-side and is never exposed to Claude.

3. Deploy to any Node host and grab the URL

Render, Railway, Fly.io, a small VPS, or Cloudflare (with minor adaptation) all work. Start command is npm start. Node 18+.

When it deploys, the host gives you a public HTTPS URL, e.g. https://hyros-mcp.onrender.com.

The MCP URL is that URL with /mcp on the end:

https://hyros-mcp.onrender.com/mcp

That's the string Andrea pastes into Claude as a custom connector (Settings → Connectors → Add custom connector). Current click-path lives at support.claude.com if the screen has changed.

Quick health check: open the base URL in a browser. It should say "Hyros MCP server is running."

---

One thing to verify on the first live call

The Hyros docs show the attribution endpoint exists (GET /api/v1.0/attribution and GET /api/v1.0/attribution/ad-account) and list the fields it returns (roas, revenue, sales, cost, profit, refunds, etc.). The docs did not spell out the exact query-parameter names for that endpoint, so the server assumes the same convention Hyros uses on its Leads endpoint: fromDate and toDate in ISO 8601, plus a fields list.

If the first real pull returns HTTP 400, the parameter names are slightly different. That's a one-line fix, and there's a built-in hyros_raw_get tool to probe the exact contract. Run a test pull once it's connected, paste the result back into the Claude chat, and the tool mapping gets finalized in seconds.

---

Tools this server exposes to Claude

• get_ad_attribution — attributed roas/revenue/sales/cost/profit for a date range
• get_attribution_by_ad_account — same, grouped by ad account
• hyros_raw_get — setup/debug helper to call any Hyros GET path directly

Optional lockdown

Set MCP_BEARER_TOKEN to require an Authorization: Bearer header on /mcp. Fine to leave off for a private, obscure URL; turn on if you want access control.