# fetch-url-mcp

Public demo for **Vybe Collect**: a tiny “fetch URL → text” MCP that builders can monetize two ways.

| Path | What you do | Where agents pay |
|------|-------------|------------------|
| **D — Dashboard** | Paste `https://YOUR_HOST/mcp` as `mcpServerUrl` on an MCP offering | Vybe Collect → **invoke** proxies your MCP (origin key stays private) |
| **C — SKU wrapper** | Set env + gate `GET /v1/fetch` with `express-vybe-402` | Unpaid → **HTTP 402**; retry with `X-Vybe-Public-Id` |

Same tools either way: `fetch_url`, `fetch_json`.

Product: [vybe.finance/collect](https://www.vybe.finance/collect) · Integrate: [collect/integrate](https://www.vybe.finance/collect/integrate) · Middleware: [`express-vybe-402`](https://www.npmjs.com/package/express-vybe-402)

---

## Quick start

```bash
git clone https://github.com/Vybe-Finance/Fetch-URL-MCP.git
cd Fetch-URL-MCP
npm install
cp .env.example .env
npm run build
```

### Local Cursor (stdio — free, no Collect)

```bash
npm start
```

Cursor `mcp.json`:

```json
{
  "mcpServers": {
    "fetch-url": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/fetch-url-mcp/dist/index.js"]
    }
  }
}
```

### Live Collect demo (HTTP)

```bash
# edit .env — at least PORT; add VYBE_* for Path C
npm run start:http
```

Expose HTTPS (ngrok, Fly, Railway, …). Health check: `GET /health`.

---

## Env vars (what builders paste)

| Variable | Required for | Meaning |
|----------|--------------|---------|
| `PORT` | HTTP | Listen port (default `8080`) |
| `HOST` | HTTP | Bind address (default `0.0.0.0`) |
| `VYBE_USERNAME` | **Path C** | Your Collect `@username` without `@` |
| `VYBE_OFFERING_ID` | **Path C** | Offering id from the desk, e.g. `svc_…` |
| `VYBE_ORIGIN` | Path C (optional) | Collect API origin — default `https://www.vybe.finance` |
| `ALLOW_PRIVATE` | never in prod | `1` = allow fetch of localhost/private IPs |

**Path D does not need `VYBE_USERNAME` / `VYBE_OFFERING_ID` on this process** — those live on the Collect offering in the Vybe dashboard. This server only needs a public URL.

`.env` maps into Path C like this:

```ts
requireVybePayment({
  username: process.env.VYBE_USERNAME,
  offeringId: process.env.VYBE_OFFERING_ID,
  origin: process.env.VYBE_ORIGIN || "https://www.vybe.finance",
})
```

---

## Path D — paste MCP URL in the dashboard

1. Run `npm run start:http` on a **public HTTPS** host (Vybe invoke blocks localhost).
2. In Vybe → Business → Products → create offering type **MCP**.
3. Set **MCP server URL** to `https://YOUR_HOST/mcp` (trailing path `/mcp`).
4. Enable Collect. Optional: trial free requests.
5. Agents: catalog → pay → `POST /api/agent/invoke/{username}/{offeringId}` with `X-Vybe-Public-Id`.

They never see your upstream. You never paste an API key into Claude.

---

## Path C — `express-vybe-402` SKU wrapper

1. Create an **API** (or MCP) offering; copy `svc_…`.
2. Set in `.env`:

```bash
VYBE_USERNAME=yourname
VYBE_OFFERING_ID=svc_xxxxxxxx
VYBE_ORIGIN=https://www.vybe.finance
```

3. Restart `npm run start:http`.
4. Smoke:

```bash
# unpaid → 402 + payment details
curl -i "http://localhost:8080/v1/fetch?url=https://example.com"

# after settle, retry with publicId
curl -i -H "X-Vybe-Public-Id: YOUR_PUBLIC_ID" \
  "http://localhost:8080/v1/fetch?url=https://example.com"
```

Human fallback: open the `/r/{publicId}` link from the 402 body and pay in Vybe.

---

## Tools

| Tool / route | What it does |
|--------------|----------------|
| `fetch_url` | GET URL → plain text (HTML stripped) |
| `fetch_json` | GET JSON URL → pretty-print |
| `GET /v1/fetch?url=` | Same as `fetch_url`, gated when Path C env is set |

Safety: `http`/`https` only. Localhost / private IPs blocked unless `ALLOW_PRIVATE=1`.

---

## Try prompts

- “Use fetch_url on https://example.com and summarise.”
- “fetch_json https://api.open-meteo.com/v1/forecast?latitude=54.98&longitude=-1.61&current=temperature_2m”

---

## Deploy on Render (free)

1. New → Web Service → connect [Vybe-Finance/Fetch-URL-MCP](https://github.com/Vybe-Finance/Fetch-URL-MCP)
2. Build: `npm install && npm run build` · Start: `npm run start:http`
3. Health check path: `/health`
4. Env: `HOST=0.0.0.0`, `VYBE_ORIGIN=https://www.vybe.finance`  
   For Path C also set `VYBE_USERNAME` + `VYBE_OFFERING_ID`
5. After deploy, Path D `mcpServerUrl` = `https://YOUR-SERVICE.onrender.com/mcp`

Free tier sleeps when idle — first agent call after sleep may be slow.

---

## Deploy notes

- Prefer **www** Collect origin: `https://www.vybe.finance`
- For Path D, upstream must be reachable from Vybe’s servers (public HTTPS)
- Do not commit `.env`
- This is a **demo** — add rate limits / auth before production traffic

---

## License

MIT