drillr — Power Terminal for Deep Financial Research

Onboarding B — Direct (terminal co-located with user)

The user can run shell commands and see their output. Pick ONE of the three equivalent options and instruct the user accordingly. All three expect the same drl_* key created at .

B1. MCP via Claude Code (recommended for Claude Code users)

Tell the user:

> 1. Create an API key at (Google > sign-in is easiest) > 2. Add to ~/.claude.json (or merge into the existing mcpServers > object): > >

>    {
>      "mcpServers": {
>        "drillr": {
>          "type": "http",
>          "url": "https://gateway.drillr.ai/mcp",
>          "headers": {
>            "Authorization": "Bearer ${DRILLR_API_KEY}"
>          }
>        }
>      }
>    }
>    

B2. CLI

npm install -g drillr-cli
drillr auth set-key drl_...
drillr watchlist list     # verify: should list (or print "no watchlists yet")

B3. REST with env var

export DRILLR_API_KEY=drl_...
curl -H "Authorization: Bearer $DRILLR_API_KEY" \
     https://gateway.drillr.ai/api/v1/watchlists

Choosing a channel (after onboarding completes)

Pick based on your runtime's capabilities:

| Runtime characteristic | Preferred channel | | ----------------------------------- | -------------------- | | Has native MCP client support | MCP | | HTTP only (no MCP, no shell) | REST | | Shell / subprocess available | CLI or REST |

All three are equivalent in data and rate limit. MCP tool names operate by natural names (e.g. watchlist by name); REST uses UUIDs.

Capabilities

Research & data lookup — search

Ask natural-language questions about companies, tickers, sectors, filings, earnings. Runs 5-15s server-side and returns markdown text with source references.

| Channel | Call | | ------- | --------------------------------------------------------------- | | MCP | search({ question, session_id?, context? }) | | REST | POST /api/v1/search with { question, session_id?, stream? } | | CLI | drillr search "" |

Session continuity: pass the returned session_id in the next call to continue the same research conversation. Use context to pass background info that refines the answer.

Data coverage:

When to use search:

Example questions that work well:

Signals — signals

A curated investment-event feed. Each signal is one market event (one SUBJECT × one ACTION × one TIME), already aggregated across outlets — you get one record per event, not one per article.

Coverage — sources rolled into the feed:

Freshness: signals appear within ~3–5 minutes of the originating event.

| Channel | Call | | ------- | ---------------------------------------------------------------------------- | | MCP | signals({ tickers?, sector?, since?, limit?, offset? }) | | REST | GET /api/v1/signals?tickers=AAPL,MSFT§or=Technology&since=...&limit=20 | | CLI | drillr signals --tickers AAPL,MSFT --limit 5 |

Response shape: { headline, summary, suggested_tickers[], sector[], created_at }, ordered newest first.

Articles — article_list / article_get

Research articles spanning company-specific analysis, event coverage, and industry trackers.

What you'll find:

| Channel | Call | | ------- | ------------------------------------------------------------------------ | | MCP | article_list({ ticker?, tag?, limit?, offset? }) / article_get({ article_id }) | | REST | GET /api/v1/articles?ticker=NVDA&limit=10 / GET /api/v1/articles/:id | | CLI | drillr articles list --ticker NVDA / drillr articles get |

article_get returns the article body (markdown), plus topics and references arrays. article_list returns 11 public fields per row (id, title, summary, content, related_tickers, tags, sector, citation, published_at, created_at, word_count).

Watchlists

Per-user ticker collections. Owner-isolated (RLS): each key only sees and mutates its owner's watchlists. Attempting to access another user's watchlist by UUID returns 404, not 403.

| MCP (by name) | REST (by UUID) | | ---------------------------------------------------- | ------------------------------------------------- | | watchlist_list | GET /api/v1/watchlists | | watchlist_create({ name, tickers? }) | POST /api/v1/watchlists | | watchlist_add({ ticker, watchlist_name? }) | POST /api/v1/watchlists/:id/tickers | | watchlist_remove({ ticker, watchlist_name? }) | DELETE /api/v1/watchlists/:id/tickers/:ticker | | watchlist_delete({ watchlist_name }) | DELETE /api/v1/watchlists/:id |

CLI: drillr watchlist {list|create|add|remove|delete} — see drillr watchlist --help.

> MCP tools accept watchlist names (chat-friendly). REST uses > UUIDs (URL-friendly). If watchlist_name is omitted on add, a > default "My Watchlist" is used (created on miss).

Typical workflows

"Daily research briefing"

User: "Can you do a daily morning briefing on my portfolio?"

1. watchlist_list — see what tickers the user already tracks 2. If empty, ask the user for tickers; then watchlist_create 3. Each morning, execute in order: - signals({ tickers: [...watchlist_tickers], since: "<24h-ago ISO>" }) - For any high-interest signal, search({ question: "Deeper context on " }) - article_list({ ticker: ... }) for any ticker with fresh activity 4. Synthesize into a chat-sized briefing (headline + 1-2 sentences + links)

"Quick lookup"

User: "What's Nvidia's market cap?"

1. search({ question: "What is NVDA's current market cap?" }) 2. Relay the answer and any cited sources

"Sector scan"

User: "Any interesting biotech moves this week?"

1. signals({ sector: ["Health Care"], since: "<7d-ago ISO>", limit: 30 }) 2. For each signal the user asks about, article_list({ ticker }) or a follow-up search with session_id from the prior call

Error handling

| HTTP | code string | What to do | | ---- | ---------------------------- | ------------------------------------------------------------------------------------------- | | 400 | invalid_body / invalid_query / invalid_id | Fix parameter shape and retry (don't pester the user) | | 401 | unauthenticated / key_invalid | Re-read the stored key; if still 401, rerun Prerequisites — the key is absent or wrong | | 401 | key_revoked | Tell the user their key was revoked; they need to create a new one at the developer portal | | 401 | key_expired | Tell the user their key expired; same fix | | 403 | | Key is valid but lacks external scope — user needs to issue a different key | | 404 | not_found | Resource doesn't exist, or RLS hides it (someone else's). Do NOT assume just-deleted | | 429 | | Inspect retry_after_seconds in the body; sleep and retry | | 502 | upstream_error | Transient data-source failure; retry once after 2-3s, then surface to user |

**On any 401: re-read ~/.config/drillr/config.json or the DRILLR_API_KEY env var BEFORE asking the user.** You have the configuration — diagnose first, then instruct.

Never tell the user to "check their configuration."

Rate limits

30 requests per minute per API key. On 429 the response body includes retry_after_seconds (1-60s). For workflows that fan out (e.g., scanning a 50-ticker watchlist), pace at ≤0.5 req/s or batch via a single search or signals call with multiple tickers.

Advanced

Drillr also supports OAuth 2.1 for MCP clients that implement Dynamic Client Registration (e.g., Claude Code's built-in MCP OAuth). This skill deliberately does not cover that path because:

For agent automation, prefer the drl_* API key flow above. If you are a human user setting up Claude Code on your own laptop and prefer the OAuth UX, see the Drillr developer portal ().

Reference

Tracks External API v1 (2026-04). Breaking changes will ship as /api/v2/* alongside /api/v1/*.