# signalis-mcp

MCP server for **[Signalis](https://signalis.dev)** — pay-per-call **global intelligence**
for AI agents. Read the current Master Intelligence digest (narratives, signals, markdown
analysis), poll for new digests, and drill into the AI-business **Pulse** layer: active
narratives with lifecycle stage and momentum, per-narrative detail with source attribution,
historical narrative digests, and raw scraped content. Pay **per call** with USDC on
**Base** via **x402** — no signup, no accounts, no API keys.

- **5 free tools** — no wallet, no API key (incl. digest feedback).
- **5 paid tools** — flat per-call USD prices, settled in USDC on **Base Mainnet** via x402.

Try before you pay: the free `get_sample` tool returns a recent digest so you can learn the
exact response shape first.

---

## Quick start

### Free tier (no wallet)

```json
{
  "mcpServers": {
    "signalis": {
      "command": "npx",
      "args": ["-y", "signalis-mcp"]
    }
  }
}
```

You get `get_brief`, `get_index`, `get_sample`, `get_latest`, `submit_feedback`.

### Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on **Base Mainnet**:

```json
{
  "mcpServers": {
    "signalis": {
      "command": "npx",
      "args": ["-y", "signalis-mcp"],
      "env": { "PRIVATE_KEY": "0x..." }
    }
  }
}
```

The paid tools then settle each call automatically.

### Install snippets

Claude Code:

```bash
claude mcp add signalis -- npx -y signalis-mcp
# with a wallet:
claude mcp add signalis --env PRIVATE_KEY=0x... -- npx -y signalis-mcp
```

Claude Desktop / Cursor: add the JSON block above to your MCP config
(`claude_desktop_config.json` or `.cursor/mcp.json`).

---

## Tools

### Free tools

| Tool | Endpoint | Description |
| --- | --- | --- |
| `get_brief` | `GET /v1/intelligence/brief` | Current Master Intelligence brief — title, executive summary, sentiment. |
| `get_index` | `GET /v1/intelligence/index` | Poll target — current digest id, updatedAt, nextExpected. |
| `get_sample` | `GET /v1/intelligence/sample` | Recent digest sample showing the response structure. |
| `get_latest` | `GET /v1/intelligence/latest` | Full Master Intelligence Digest — narratives, signals, markdown analysis. |
| `submit_feedback` | `POST /v1/intelligence/feedback` | Submit quality feedback on a master digest. |

### Paid tools

| Tool | Endpoint | Price (USD) | Description |
| --- | --- | --- | --- |
| `get_intelligence_history` | `GET /v1/intelligence/history` | **$0.03** | Historical Master Intelligence digests (1–168h lookback). Optional `hours`, `limit`. |
| `get_pulse_narratives` | `GET /v1/pulse/narratives` | **$0.01** | Active AI-business narratives with lifecycle stage and momentum. |
| `get_pulse_narrative` | `GET /v1/pulse/narratives/{id}` | **$0.01** | Narrative detail — content items and source attribution. Requires `id`. |
| `get_pulse_digests` | `GET /v1/pulse/digests` | **$0.03** | Historical AI-business narrative digests. Optional `since`. |
| `get_pulse_content_recent` | `GET /v1/pulse/content/recent` | **$0.02** | Raw scraped content items from the last 4 hours. |

Prices are flat per call — **no bundles, no entitlements**.

---

## How payments work (x402)

Signalis speaks the [x402](https://x402.org) `exact` scheme. The API's 402 advertises a
**Base** (USDC, EIP-3009) rail; this MCP settles on **Base**:

1. The MCP requests a paid endpoint. With no payment, the API replies **HTTP 402** with the
   accepted terms.
2. If `PRIVATE_KEY` is set, the MCP settles the call via the standard `@x402/fetch` V2
   client and retries. If no key is set, the MCP returns the **402 price terms** so you can
   see the cost without paying.
3. The API returns the data plus a `payment` block.

**Compute-first, settle-after:** Signalis computes the full answer **before** charging, so
you are never billed for an error.

No accounts, no API keys — just a wallet with USDC on **Base Mainnet**.

---

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `PRIVATE_KEY` | No | 0x-prefixed wallet key with **USDC on Base Mainnet**. Required to pay the 5 paid tools on a live API. Free tools work without it; without a key the paid tools surface the 402 price terms. |
| `SIGNALIS_API_URL` | No | Override the API base URL (default `https://api.signalis.dev`). |

---

## Disclaimer

Signalis provides **informational** intelligence aggregated from public sources. It is not
professional or financial advice and is provided as-is without warranty. See
<https://api.signalis.dev/terms.txt>.

Docs for agents: <https://api.signalis.dev/llms.txt> ·
full: <https://api.signalis.dev/llms-full.txt>

---

## License

MIT © jcislo