# Tocsin

Tocsin is one normalized feed of security advisories for runtimes and packages.
Each event is one advisory (schema: https://tocsin.sh/schema/advisory.v1.json).

## Read the feed

curl "https://tocsin.sh/v1/events?since=0&min_severity=high"

The answer is { "events": [...], "next_cursor": <int>, "has_more": <bool> }, oldest first.

## Cursor rule

1. Store next_cursor.
2. Send it back as since=<next_cursor> on the next call.
3. Repeat while has_more is true. When has_more is false, you are up to date.
An empty page returns your own since as next_cursor, so you never lose your place.

## Filters (all optional)

- ecosystem=<csv>  OSV ecosystem or runtime name, for example node,npm,PyPI
- component=<csv>  package or runtime name
- min_severity=critical|high|medium|low
- exploited=true   only advisories known to be exploited
- limit=1..100     default 50
- order=desc       newest first; next_cursor is the newest cursor on the page

## Caching and limits

Each page has a strong ETag. Send it back in If-None-Match; an unchanged page answers 304.
Anonymous reads of /v1/events are limited per IP per minute. A 429 carries Retry-After in seconds.

## Check your dependencies

Runtimes only, no body:

curl "https://tocsin.sh/v1/check?node=24.22.0&php=8.4.26"

One or more lockfiles, field name = file name (package-lock.json, npm-shrinkwrap.json,
pnpm-lock.yaml, yarn.lock, requirements.txt, go.sum, composer.lock, Cargo.lock, Gemfile.lock):

curl -F "package-lock.json=@package-lock.json" https://tocsin.sh/v1/check

Or JSON:

curl -H "Content-Type: application/json" -d '{"dependencies":[{"ecosystem":"npm","name":"left-pad","version":"1.3.0"}],"runtimes":{"node":"24.22.0"}}' https://tocsin.sh/v1/check

The answer is { "checked": <int>, "affected": [...], "skipped": [...], "feed_cursor": <int> }.
Each affected item has dependency, advisory_id, cve_ids, severity, exploited, fixed_in, action, url,
critical first, then exploited first. skipped lists what could not be checked; it is not a clean result.
Send feed_cursor as since=<feed_cursor> to /v1/events to get every advisory published after the check.
The body cap is 2 MB by default (413 over it). Anonymous checks are limited per IP per minute; a 429 carries Retry-After.

## One advisory

- https://tocsin.sh/v1/events/{id}
- https://tocsin.sh/v1/events/cve/{cve}

As an HTML page (send Accept: application/json to the same URL for the JSON):

- https://tocsin.sh/advisories/{id}
- https://tocsin.sh/cve/{cve}   every advisory that shares the CVE

Every page is listed in https://tocsin.sh/sitemap.xml.

## MCP

Remote MCP server (streamable HTTP): https://mcp.tocsin.sh/mcp

Claude Code:

claude mcp add --transport http tocsin https://mcp.tocsin.sh/mcp

Cursor (~/.cursor/mcp.json):

{"mcpServers":{"tocsin":{"url":"https://mcp.tocsin.sh/mcp"}}}

Claude Desktop (claude_desktop_config.json):

{"mcpServers":{"tocsin":{"command":"npx","args":["-y","mcp-remote","https://mcp.tocsin.sh/mcp"]}}}

Tools:

- tocsin_latest   newest advisories; filters ecosystem, min_severity, exploited_only, limit (1..100, default 10)
- tocsin_check    which dependencies are affected; lockfile_name + lockfile_text, and/or runtimes {"node":"24.22.0"}
- tocsin_get      one advisory by Tocsin id or CVE id
- tocsin_watchlist_events  new events on a watch list; needs an API key

Every tool result is { "human": <one line>, "data": <the API answer> }.
tocsin_watchlist_events needs the header Authorization: Bearer <your API key> on the MCP connection.
The other tools need no key.

Discovery: https://tocsin.sh/.well-known/tocsin.json