# 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 **105 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).
- **Fundamentals** — XBRL companyfacts: revenue, earnings, balance sheet, TTM rollups.
- **Prices** — split-adjusted daily OHLCV, ~23k US tickers, DuckDB on R2 parquet.
- **Macro** — ~104 FRED series (yields, fed funds, inflation, employment, GDP, FX, energy).
- **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), public watchlists, comments, author leaderboard, follow graph.

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

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.