# 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
```bash
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.