API & MCP

Connect over MCP

Every endpoint in the playground is also an MCP tool. Point a spec-compliant client at the NQDB server and your agent calls the same labeled event→reaction dataset directly — no glue code. One credit balance is shared across MCP and REST.

The endpoint

URL	`https://mcp.newsquantified.com/mcp`
Transport	MCP Streamable HTTP (stateless)
Auth	Clerk OAuth bearer token. Dynamic client registration is on — spec-compliant clients complete the browser login automatically; no client ID to pre-register.
Access	Provisioned by News Quantified (your user must belong to the gated Clerk org). Tier `free`/`pro`/`fund` is resolved from your org plan on every request.
Health	`GET /healthz` → `{"ok":true}` — liveness only (200 whenever the server is up; does not probe the database)
Data health	`GET /healthz/data` → `{"ok":true}` / `503` — non-gating data-plane (SQL Server) reachability probe

Connect your client

Claude Code

claude mcp add --transport http nqdb https://mcp.newsquantified.com/mcp

Then run /mcp, select nqdb, finish the browser login. Tools appear as mcp__nqdb__*.

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "nqdb": { "url": "https://mcp.newsquantified.com/mcp" }
  }
}

Then click Login next to nqdb in Settings → MCP to finish the browser flow.

Codex CLI

# ~/.codex/config.toml — mint a token first, export NQDB_MCP_TOKEN
[mcp_servers.nqdb]
url = "https://mcp.newsquantified.com/mcp"
bearer_token_env_var = "NQDB_MCP_TOKEN"

Codex uses a static bearer token — see “Minting a token” below.

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "nqdb": { "httpUrl": "https://mcp.newsquantified.com/mcp" }
  }
}

Run /mcp auth nqdb if the OAuth browser flow doesn't trigger on first use.

Minting a token

For clients that take a static bearer token (Codex, OpenAI Agents SDK), complete the OAuth flow once with the MCP Inspector and copy the access token out:

npx @modelcontextprotocol/inspector
# point it at https://mcp.newsquantified.com/mcp, finish the browser login,
# copy the access token, then:
export NQDB_MCP_TOKEN="<access token>"

Access tokens are short-lived — re-mint when calls start returning 401. Stdio-only clients can bridge with npx -y mcp-remote https://mcp.newsquantified.com/mcp.

First calls

Read the nqdb://capabilities resource — the live tool catalog, chaining graph, and output contract. It and nqdb://tier-matrix are the source of truth for the current surface and limits.
methodology_search(query="how do I read a negative rank IC") answers “how do I interpret this” questions in-band — free, no market data queried.
Something real: news_reaction(symbol="NVDA", event_type="upgrades").

Performance: the heavy cross-sectional tools scan a 26M-event store — always bound from/to(12 months is the sweet spot), expect cold-cache first calls to take a while, and raise your client read timeout if it's tuned for chat-speed tools.

Tool catalog

The same surface as the playground, grouped identically. Each REST endpoint maps 1:1 to an MCP tool mcp__nqdb__<name>. Open the playground for full request/response schemas.

Core

Reaction & screeningnews_reactionfind_reactorsstock_snapshottop_moverscompare_reactionswatchlist_monitor

Analyst intelfirm_track_recordprice_target_changesanalyst_consensus

Flow & volumesmart_moneyvolume_surge

Risk, momentum & levelsreaction_speedrelative_strengthvolatility_profiletechnical_levelsownership_short_interestsector_reaction

Knowledgemethodology_search

Advanced (research & fund-tier)

Analyst driftfirm_ratings_drift (pro+)analyst_revisions_drift (pro+)

Flow & microstructureevent_block_flow (pro+)event_volume_decayparticipation_profile (pro+)unusual_block_screen (fund)

Cross-sectional researchsignal_ic_scan (pro+)novelty_split (pro+)reaction_decaypost_event_drift (pro+)earnings_drift (pro+)

Sector & attributionsector_relative_strength (pro+)provider_attribution (fund)

Tiers & credits

One tool call = credits, billed identically on MCP and REST:

Class	Cost	Examples
Lookup / customer-face	1–2 cr	stock_snapshot · news_reaction · top_movers · analyst_consensus
Pro analytics	3–5 cr	smart_money · compare_reactions · earnings_drift · novelty_split
Fund-flagship	8–10 cr	event_block_flow · post_event_drift · reaction_decay

methodology_search is free (0 credits).

Per-tier entitlement caps (the live nqdb://tier-matrix is authoritative):

	free	pro	fund
Max tickers / call	5	50	500
Reaction lookback	1 yr	Full history	Full history
Max rows	20	200	Uncapped*
Provenance (news_key)	—	—	✓
Vendor sources	—	—	✓ (license)

*Fund rows are uncapped to a 5,000 absolute ceiling.