# ClawTerminal — agent setup skill

You are an AI assistant helping the user connect **ClawTerminal**, a markets-data MCP server, to their environment. Walk them through these steps in order. Be concise — one short paragraph per step. Confirm before moving on.

## What ClawTerminal is

ClawTerminal exposes **190+ markets-research tools** over MCP. Surfaces:

- **SEC filings** — 8-K, 10-K, 10-Q, 20-F / 40-F (foreign private issuers), Form 4 (insider trades), Schedule 13D / 13G (5%+ owners), Form 13F-HR (institutional managers), N-PORT-P (fund holdings + monthly returns), DEF 14A (proxies, executive comp, voting), S-1 / 424B (IPO prospectuses).
- **Fundamentals** — XBRL companyfacts: revenue, earnings, balance sheet, TTM rollups, cross-company comparisons.
- **Screener** — multi-rule equity and ETF screens over ~5k US issuers, with safe custom ratios, trailing risk metrics (vol / Sharpe / Sortino / max drawdown / beta) and saveable screens.
- **ClawRating** — a daily three-axis rating on every non-financial issuer: quality (letter AAA..D), valuation (0-100, higher = cheaper) and flow (-100..+100), each with its full breakdown.
- **Prices & technicals** — split-adjusted daily OHLCV, ~23k US tickers, DuckDB on R2 parquet; SMA / EMA / RSI / MACD / Bollinger / ATR and 52-week position in one call.
- **Options** — EOD chains, implied-volatility history and IV rank, ATM term structure and 25-delta skew, straddle-implied moves, and an earnings IV radar.
- **Macro** — ~104 FRED series plus EIA energy and World Bank commodity prices (yields, fed funds, inflation, employment, GDP, FX); the full Treasury yield curve on one date; USDA crop progress and world supply & demand; CFTC COT positioning.
- **Health** — openFDA drug approvals and recalls, with event studies and pre-event insider-activity joins.
- **Influence** — US Senate LDA lobbying filings, by bill or by company.
- **News & estimates** — a ticker-tagged news tape assembled from issuer press releases and public-domain government feeds, plus analyst-consensus history and revisions.
- **Prediction markets** — Polymarket + Kalshi via pmxt.
- **Crypto** — Hyperliquid perps (core + Ventuals pre-IPO OpenAI/Anthropic/SpaceX + trade.xyz traditional assets like WTI/Gold/TSLA + other HIP-3 builder dexes) + ~268 CEX spot pairs.
- **Community** — Ideas board (trade ideas scored mechanically vs SPY), portfolios with full risk analytics and a long-only optimizer, public watchlists that scan every surface above, comments, author leaderboard, follow graph.
- **Live SEC retrieval** — full-text search across every filing ever made, the last-24h filings firehose, and read-any-filing-by-accession, for anything outside the indexed corpus.

It's a **database for your AI**, not a chatbot. Agents call tools directly; the assistant composes the answer.

## Step 1 — get an API key

Ask the user:

> Do you already have a ClawTerminal API key? It looks like `sk-live-…` (about 50 characters).

- **If yes:** ask them to paste it. Continue to Step 2.
- **If no:** instruct them:
  1. Open <https://clawterminal.ai>
  2. Enter their email in the sign-in card and click "Send link"
  3. Click the magic link in their inbox (valid 30 min)
  4. After verifying, their personal `sk-live-…` key is shown on the dashboard
  5. Come back here and paste it

Do **not** make up a key. The user must provide it.

## Step 2 — register the MCP server

Pick the right command for the user's environment. Ask them which they're using if it isn't obvious.

### Claude Code (CLI in a terminal)

Run:

```bash
claude mcp add --transport http clawterminal https://mcp.clawterminal.ai \
  --header "Authorization: Bearer <KEY>"
```

Replace `<KEY>` with the user's actual key. Then run `claude mcp list` to confirm it appears.

### Claude Desktop (macOS / Windows app)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Add or merge:

```json
{
  "mcpServers": {
    "clawterminal": {
      "type": "http",
      "url": "https://mcp.clawterminal.ai",
      "headers": { "Authorization": "Bearer <KEY>" }
    }
  }
}
```

Save and restart Claude Desktop. The server appears in the tools menu.

### OpenAI Codex (CLI)

```bash
export CLAWTERMINAL_API_KEY=<KEY>
codex mcp add clawterminal \
  --url https://mcp.clawterminal.ai \
  --bearer-token-env-var CLAWTERMINAL_API_KEY
codex mcp list
```

Persist the `export` line in `~/.zshrc` or `~/.bashrc` so it survives reboots.

### ChatGPT (web, Developer Mode)

ChatGPT's connector dialog does **not** accept custom Bearer headers. Use this exact URL pattern instead — the key goes in the path and Caddy rewrites it:

```
https://mcp.clawterminal.ai/k/<KEY>/mcp
```

1. Settings → Advanced → enable **Developer Mode**.
2. Settings → Connectors → **Create**.
3. Name: `ClawTerminal`. URL: the URL above with `<KEY>` substituted. Auth: **No authentication** / **Sin autenticación**.
4. In any chat: `+` → Developer Mode → select **ClawTerminal**.

Warn the user: the URL itself is the credential — never paste it in public.

### Cursor

Cursor Settings → MCP → Add. URL `https://mcp.clawterminal.ai`. Header `Authorization: Bearer <KEY>`. Save and reload.

### Custom MCP client (Python)

```python
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://mcp.clawterminal.ai",
    headers={"Authorization": "Bearer <KEY>"},
) as (read, write, _):
    async with ClientSession(read, write) as s:
        await s.initialize()
        result = await s.call_tool("top_insider_buyers", {"days": 14})
```

## Step 3 — verify

After registering, ask the user to run a probe query — for example:

> "Use ClawTerminal to show the top 5 insider buyers in the last 14 days."

- If the assistant returns a list with names, tickers and dollar amounts → **connected**. Stop here.
- If the assistant says the tool isn't available → the MCP server isn't registered. Re-check Step 2.
- If the response is `401 Unauthorized` → the key is wrong, expired, or revoked. Have the user issue a new key from <https://clawterminal.ai> and retry Step 2.

## Useful follow-up tools to demo

Once connected, suggest one of these to give the user a feel for the surface. Start with **`whats_new`** — it's the best single-shot smoke test (one call returns 8-K, periodic filings, top insider buys/sells, fresh 13D/G, and DEF 14A across the last 7 days).

- `whats_new` — cross-source recency feed; optionally scope to a ticker
- `resolve_entity` — universal id resolver (ticker / CIK / fund / manager / accession / CUSIP / ISIN / holder name); call this first whenever the input is ambiguous
- `entity_timeline` — chronological merge of every filing + insider txn + 13D/G + DEF 14A + large price moves for one issuer
- `list_recent` — last N 8-Ks, optionally filtered by form/ticker
- `top_insider_buyers` / `top_insider_sellers` — Form 4 ranked by dollar value
- `cluster_insider_buys` — coordinated insider buying within a window (multi-officer signal)
- `top_buyers_of` — which 13F managers added the most of a ticker
- `search_narrative` — semantic search across 10-K / 10-Q / 20-F / 40-F sections
- `compute_price_features` — gap, pre/post returns, vol, drawdown, 52w distance around any anchor date
- `top_crypto_funding` — Hyperliquid perps ranked by funding APR
- `search_prediction_markets` — Polymarket / Kalshi event search
- `list_ideas` / `top_authors` — community trade ideas, sortable by `new` / `top` / `score`; leaderboard by median excess return vs SPY
- `screen_equities` — multi-rule screens with custom ratios; scores a whole basket in one call instead of looping per ticker
- `get_rating` / `top_rated` — ClawRating quality, valuation and flow, with the pillar breakdown
- `get_technical_indicators` — every indicator for up to 25 names in one call
- `get_yield_curve` — all 11 tenors on ONE date, plus named spreads and the change vs 1w / 1m / 3m / 1y
- `earnings_iv_radar` — upcoming earnings ranked by the move options are already pricing in
- `news_feed` / `search_news` — the ticker-tagged tape in publication order
- `analyze_positions` — full risk analytics on an ad-hoc basket without saving it
- `full_text_search` — EFTS across every filing ever made, not just the indexed corpus

Full tool catalog: <https://clawterminal.ai/setup#tools>.

## Troubleshooting

- `421 Misdirected Request`: hostname mismatch. The official endpoint is `https://mcp.clawterminal.ai` — ensure no typos.
- `429 Too Many Requests`: beta rate limits. Back off and retry after a minute.
- Tools missing: the agent may need a reload (close + reopen Claude Desktop, or `claude mcp list` to confirm). MCP servers are loaded once per session.
- Key looks valid but `401`: paste it without leading/trailing whitespace; ensure no quotes around `Bearer`.

That's the whole skill. Confirm with the user that it works before doing anything else.