# SubSignal — full reference for AI assistants

> Reddit monitoring, lead generation and Reddit analytics. This file is the long-form companion to https://subsignal.ai/llms.txt and is written for language models and agents that need to set up or use the SubSignal Reddit MCP server or REST API. Human-readable pages: https://subsignal.ai/reddit-mcp-server and https://subsignal.ai/api/docs

## 1. Reddit MCP Server

SubSignal hosts a remote Model Context Protocol server. It exposes SubSignal's Reddit intelligence — real-time brand mentions with sentiment, subreddit analytics, AI-content rankings and Reddit account profiles — as tools for Claude.ai, Claude Desktop, Claude Code, Cursor and any MCP-capable client.

- Endpoint: `https://api.subsignal.ai/mcp`
- Transport: Streamable HTTP, stateless. Every POST is one JSON-RPC 2.0 request answered with `application/json`. GET returns 405 (no server-initiated streams). No session ids. Batching is not supported (one message per POST).
- Protocol versions: 2025-06-18 (preferred), 2025-03-26, 2024-11-05.
- Capabilities: `tools` only. No resources, no prompts, no sampling.
- Short URL for humans: https://subsignal.ai/mcp → https://subsignal.ai/reddit-mcp-server

### 1.1 Setup per client

Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → paste `https://api.subsignal.ai/mcp` → sign in to SubSignal → Allow.

Claude Code (OAuth):
```
claude mcp add --transport http subsignal https://api.subsignal.ai/mcp
```

Cursor (`.cursor/mcp.json`):
```json
{ "mcpServers": { "subsignal": { "url": "https://api.subsignal.ai/mcp" } } }
```

Any client with an API key instead of OAuth (CI, headless):
```json
{ "mcpServers": { "subsignal": { "url": "https://api.subsignal.ai/mcp", "headers": { "Authorization": "Bearer sk_live_…" } } } }
```

Local stdio alternative (API key in env):
```
npx -y subsignal-mcp        # needs SUBSIGNAL_API_KEY
```

### 1.2 Authentication (OAuth 2.1)

The server follows the MCP authorization specification.

- Unauthenticated requests get `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.subsignal.ai/.well-known/oauth-protected-resource"`.
- Protected resource metadata: `GET https://api.subsignal.ai/.well-known/oauth-protected-resource` (also `/.well-known/oauth-protected-resource/mcp`). `authorization_servers: ["https://api.subsignal.ai"]`.
- Authorization server metadata: `GET https://api.subsignal.ai/.well-known/oauth-authorization-server`.
- Dynamic client registration (RFC 7591): `POST https://api.subsignal.ai/oauth/register` with `client_name`, `redirect_uris` (https, or http on localhost/127.0.0.1), `token_endpoint_auth_method` = `none` (public client, default) or `client_secret_post`.
- Authorization: `GET https://api.subsignal.ai/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge`, `code_challenge_method=S256` (PKCE is mandatory), optional `scope=subsignal`, optional `resource=https://api.subsignal.ai/mcp`. The browser is sent to the SubSignal consent page; after approval the client's redirect_uri receives `code` and `state`.
- Token: `POST https://api.subsignal.ai/oauth/token` (form-encoded or JSON) with `grant_type=authorization_code`, `code`, `code_verifier`, `client_id`, `redirect_uri`. Returns `access_token` (prefix `ss_oat_`, 1 hour), `refresh_token` (prefix `ss_ort_`, 30 days), `token_type=Bearer`, `expires_in`, `scope`.
- Refresh: `grant_type=refresh_token`. Both tokens rotate; the old refresh token is invalid immediately.
- Revoke: `POST https://api.subsignal.ai/oauth/revoke` with `token`. Users can also disconnect in Settings → Connected apps.
- A presented-twice authorization code revokes the whole grant.
- Each grant is backed by a connection-scoped API key on the user's account; plan gating and monthly quota apply exactly as for the REST API.
- Plan requirement: Growth or Professional. The consent screen refuses to connect accounts whose plan has no API access.

### 1.3 Tools

All tools return a single text content block containing pretty-printed JSON — the same payload the corresponding REST endpoint returns. Errors (validation, plan, quota) come back as tool results with `isError: true` and a readable message such as `SubSignal API 403: Your plan (free) does not include api access — please upgrade.` They are not JSON-RPC protocol errors.

search_reddit — full-text search over the SubSignal post archive for ANY brand, product or phrase. No tracking needed.
- Arguments: `q` (2–64, required; multi-word terms match as a phrase, whole words only), `days` (1–365, default 90), `limit` (1–50, default 20), `subreddit` (one sub), `subreddits` (list, max 40), `scope` (`all` or `founders` — 31 founder/dev/payments subs; use it for B2B brands whose names are common words like paddle, polar, stripe), `cursor`.
- Returns: `query`, `source: "archive"`, `window_days`, `total_matches`, `by_day[{date,count}]`, `avg_sentiment` (per-post score in [-1,1] over scored posts), `sentiment_n`, `intent_matches`, `intent_share` (share of matched posts (title or body) that read like a purchase decision: alternative / recommend / switching / which provider / merchant of record), `subreddits[[name,count]]`, `sample[{type:"post",subreddit,title,snippet,permalink,created_at,sentiment}]`, `next_cursor`.
- Very broad terms over long windows may exceed the 20 s query budget and return a 422 asking to narrow `days` or add `subreddit`.
- Prefer this over search_mentions for any "what are people saying about X" question.

compare_brands — 2–6 brands over the same window. Arguments: `brands` (array), `days` (default 90), `scope` (`all` | `founders`), `subreddits` (array). One archive search per brand; credits are the sum of the per-brand credits. Returns `brands[{brand,mentions,intent_share,avg_sentiment,top_subreddits}]` sorted by mentions.

search_mentions — real-time mentions of a keyword this account tracks (posts AND comments, plus removal tracking).
- Arguments: `q` (string, 2–64, required), `days` (1–90, default 30), `limit` (1–50, default 20), `cursor` (opaque, from `next_cursor`).
- Returns: `query`, `tracked`, `window_days`, `total_matches`, `by_day[{date,count}]`, `avg_sentiment`, `subreddits[[name,count]]`, `removed_stats{checked_n,removed_n,removed_share}`, `sample[{type,subreddit,snippet,permalink,created_at,sentiment}]`, `next_cursor`.
- If `tracked` is false the keyword is not tracked by anyone yet; the response includes `how_to_track`. Call `track_keyword` and expect data to accrue from that moment — there is no historical backfill.
- Samples are ≤200-character snippets plus a Reddit permalink; content since deleted on Reddit is excluded from samples (aggregate counts may include it).

track_keyword — start real-time tracking. Argument: `keyword` (2–64). Same keyword pool and per-plan keyword limit as the dashboard.
list_keywords — no arguments. Returns the account's active tracked keywords with `tracking_since`.
untrack_keyword — Argument: `keyword`. Hard-deletes the tracking row; existing mentions are kept.

subreddit_intel — Argument: `name` (without r/). Returns AI-content ratio, promoted products and link domains, and top link-promoters (shill candidates) from SubSignal's tracked data. `found: false` if the subreddit is not in the index.
subreddit_timeseries — Arguments: `name`, `grain` (`day`|`month`, default month), `days` (1–365, default 180). Returns post volume, average sentiment and AI-content share per bucket, from precomputed daily stats.
ai_content_rankings — no arguments. Static ranking of subreddits by share of AI-generated posts from the July-2026 SubSignal study (20,777 long-form posts scored with an AI-text detector); includes a dataset download link (CC BY 4.0).
reddit_user_profile — Arguments: `username` (without u/), `include_summary` (bool, default false). Returns a shadow profile from SubSignal's data: activity, subreddits, promoted products, suspicion signals. With `include_summary`, adds a 1–2 sentence AI "who is this" (one extra metered call).

Deliberately not exposed: `POST /v1/user/{username}/expose` (publishes a public 48-hour report and runs an LLM call).

### 1.4 Behaviour an agent should know

- Credits: most tools cost 1 per call; search_reddit / compare_brands cost 3 per 1,000 matching posts per brand (min 1, max 100), 2 per further page, reported as `credits_charged`. 500 credits/month on Growth, 10,000 on Professional. Exhaustion returns a 429 inside the tool result.
- Rate limits on the MCP endpoint are per connection, not per IP.
- search_reddit / compare_brands answer for any term from the archive. Tracking is only needed for real-time alerts and comment coverage (search_mentions).
- Sentiment in `sample[].sentiment` is a label encoded as −1 (negative), 0 (neutral) or 1 (positive); `avg_sentiment` is the mean of those labels over the window, so 0.18 means "more positive than negative", not a VADER score.
- Pass subreddit names in Reddit's own casing (`SaaS`, not `saas`) — `subreddit_intel` matches the stored name exactly. The `r/` and `u/` prefixes are stripped automatically.

## 2. Developer API (REST)

- Base URL: `https://api.subsignal.ai/api/v1`
- Auth: `Authorization: Bearer sk_live_…` (also `X-Api-Key` header or `?api_key=`; Bearer recommended). Keys are created in Settings → API Keys and shown once.
- Plans: Growth (500 credits/month) and Professional (10,000 credits/month). Most endpoints cost 1 credit per call; /search costs 3 credits per 1,000 matching posts (min 1, max 100), 2 per further page, returned as `credits_charged`, with `credits_remaining` and `credits_reset_at` alongside. Free and trial plans have no API access.
- Endpoints:
  - `GET /search?q=&days=&limit=&subreddit=&cursor=` — archive search, any term, up to 365 days (see search_reddit above).
  - `GET /mentions?q=&days=&limit=&cursor=` — real-time mentions of tracked keywords (see search_mentions above).
  - `POST /keywords {"keyword": "..."}`, `GET /keywords`, `DELETE /keywords/{keyword}`.
  - `GET /subreddit/{name}` — subreddit intelligence.
  - `GET /subreddit/{name}/timeseries?grain=&days=` — time series.
  - `GET /rankings/ai-content` — AI-content rankings.
  - `GET /user/{username}/quick` — quick shadow profile. `GET /user/{username}/summary` — AI summary. `POST /user/{username}/expose` — public 48h exposé report (rate-limited hard).
- Errors are JSON `{"detail": "..."}` with 401 (missing/invalid key), 403 (plan), 422 (validation), 429 (quota or burst limit), 404.
- Full reference with response schemas: https://subsignal.ai/api/docs

## 3. Product summary

SubSignal monitors Reddit 24/7 for keywords, surfaces high-intent leads scored by buying intent, tracks brand sentiment, detects shill accounts and AI-generated content, profiles Reddit users, finds Reddit threads ranking on Google, and (on Professional) automates personalised Reddit DMs via OAuth. Archive: 50M+ posts, ~280k new posts ingested daily across ~200k subreddits. Research published from this data includes a 20,000-post study of how much of Reddit is AI-written and studies on post deletion and payment-provider sentiment. Built by a solo founder.

Pricing: Starter free; Growth $29/month (7-day trial, no card); Professional $129/month; yearly ~45% off. Details: https://subsignal.ai/#pricing

## 4. Links

- Reddit MCP Server page: https://subsignal.ai/reddit-mcp-server
- MCP endpoint: https://api.subsignal.ai/mcp
- npm (local stdio server): https://www.npmjs.com/package/subsignal-mcp
- API landing: https://subsignal.ai/api — reference: https://subsignal.ai/api/docs
- Blog and studies: https://subsignal.ai/blog
- Free Reddit tools: https://subsignal.ai/free-reddit-tools
- Comparisons: https://subsignal.ai/alternative
- Contact: contact@subsignal.ai