Docs

Quickstart

Connect an agent or program in three steps.

1. Sign in.
2. Create a key on your account page.
3. Connect your agent or program.

https://mcp.cryptonews.is/mcp

claude mcp add --transport http cryptonews https://mcp.cryptonews.is/mcp

claude mcp add --transport http cryptonews https://mcp.cryptonews.is/mcp --header "Authorization: Bearer <key>"

https://mcp.cryptonews.is/mcp
Authorization: Bearer <key>

curl https://api.cryptonews.is/v1/stories -H "Authorization: Bearer <key>"

Plans and limits

One account covers MCP and REST.

Choose a plan at checkout.

Tools and endpoints

Use MCP tools or their GET endpoints.

tools/list shows every tool on every plan; a tool your plan cannot use starts its description with the plan that unlocks it.

Common arguments

Use these values across tools and endpoints.

Story ids

Keep the full id or reader link when citing a story.

• A story’s id can change once grouping settles, and old ids keep resolving to the current story: a merged id returns the current story with replaced_by (its id) and requested_id (the id you asked for); archived marks archived responses.
• A shortened id (at least 8 characters after an optional rg-, a trailing … is ignored) resolves when exactly one story id starts with it; otherwise the answer is 400 ambiguous_id with up to 5 candidates.
• Cite stories by their full id or reader_url.

Sentiment history

Read historical sentiment in bounded time ranges.

• History from and to: ISO date-times, at most 72 hours per call (page through longer spans); Standard reaches back 30 days: from and to (and the default from, 24 hours before to) must all fall within the last 30 days, otherwise 403 plan_required naming Pro.
• Pro reaches the whole record.
• recorded_from is 2026-10-29T02:17:00Z: minute history is recorded from then; earlier ranges return only the native’s live history or nothing.
• History resolution: auto (default), raw, 1m, 5m, 15m or 1h.
• Buckets align to UTC and use the last sample’s score with at stamped at the bucket start; auto chooses the smallest bucket returning at most 300 points, or 1h.
• Raw keeps every point.
• Responses include the resolved resolution and available_from (earliest returned point, or null).

Archive, copy and search

Look up saved stories and search the indexed record.

• Standard and Pro story lookup includes archived stories and their publisher reports.
• Archived responses include archived:true; a requested language uses the saved translation when available, otherwise English.
• Story detail always includes language; null means the copy is not written yet; missing language with completed copy defaults to English.
• Every tool marks stories with empty or missing summaries as copy_pending:true; completed copy omits the flag.
• copy_skipped: the story is rated negligible and will not get a summary; such stories carry no copy_pending.
• If the story later gains copy, the field disappears and the change arrives in changes_since.
• event_at is the time of a story’s first report and updated_at of its newest; a newer report is a change in changes_since.
• Search results from older archive rows may omit updated_at.
• get_story on a merged id adds requested_report: up to five of that id’s own reports with their copy.

Search Pro

• search_stories searches indexed headlines, summaries, publisher headlines, sources and coins.
• Use query in MCP or q on /v1/search (1–200 characters, up to 12 terms).
• A story matches if it contains any term; English stop words such as who or what are ignored and English words are stemmed, so hacked finds hack.
• Common acronyms match their spelled-out forms (SEC, ETF, DPRK, Fed, …), and a coin symbol typed in capitals also matches the coin’s name.
• Results are ranked by relevance: stories that match more terms, especially in the headline, come first, and live, summarised and recently updated stories are boosted over archived or copy-pending ones; among matches of comparable relevance, the latest development comes first.
• Twins of one article (same publisher URL or headline) appear once.
• Optional since and until are ISO date-times compared with event_at; coin and category filter stories.
• Search limit defaults to 20, maximum 50.
• offset is 0–1000, default 0, and is returned for paging.
• Results mark current drivers archived:false, others archived:true; archived ids resolve via get_story, which may return replaced_by.
• A merged id is returned as its current story with replaced_by (its id) and requested_id (the merged id).
• Each result carries reports: up to 3 of its outlets’ own English headlines and summaries (source_name, published_at): the earliest published report first, usually the original source, then those matching the query, summaries cut to two sentences.
• reports_total counts all of the story’s reports; get_story lists them whole.
• Results include total and indexed_through; indexing runs every ten minutes and older archive coverage grows during backfill.

Change feed and cursors

Follow story changes from an edition cursor.

• changes_since / /v1/changes needs a cursor.
• Take the first from cursor in a stories response.
• limit: 1–500, default 100 each for added and changed, sorted by prominence descending; removed IDs are unbounded.
• IDs in removed that were re-keyed appear in replaced_by with their new id.
• detail: compact (default) or full.
• Compact stories keep id, headline, category, secondary_category, coins, sentiment_label, sentiment_score, prominence, coverage_count, event_at, updated_at, reader_url, language, copy_pending and copy_skipped when applicable.
• The cursor still advances to the newest edition.
• When truncated appears, its added/changed counts give the totals; call latest_stories for the full current list.
• A malformed cursor returns 400 invalid_cursor.
• reset:true (old epoch or expired cursor) comes with empty lists: re-read latest_stories and continue from its cursor.
• contribution on full-detail items is a snapshot; a change in it alone is not reported.

Example shape

Illustrative request and response; use the cursor from your stories response.

{
  "name": "changes_since",
  "arguments": {"cursor": "<cursor>", "limit": 100, "detail": "compact"}
}

{
  "cursor": "<next cursor>",
  "added": [{"id": "<story id>", "headline": "<headline>"}],
  "changed": [],
  "removed": [],
  "replaced_by": {}
}

Live stream (Pro)

Subscribe to live events over REST.

• Pro only, REST: /v1/stream returns text/event-stream using the same Bearer header as other endpoints.
• Events are hello (cursor and method), story (added or changed story), removed (story IDs), reading (changed window reading), and reset.
• A ping comment keeps idle connections active.
• Limits are two connections per account and 200 overall; excess connections return 429 stream_limit.
• Each connection costs one call.
• Reconnect with backoff and re-read /v1/stories after reset; the stream has no replay guarantee.

Daily exports (Pro)

Download archived hours one UTC day at a time.

• Pro only, REST: /v1/exports/{date}/{readings|stories}.jsonl streams hourly archive records in UTC hour order as application/x-ndjson.
• Dates run from 2026-10-29 through yesterday; today and future dates return 400.
• Missing hours are listed in X-Missing-Hours; no available hours returns 404.
• Story rows retain archive duplicates.
• Each file costs one call.

Freshness

Check freshness before using time-sensitive data.

• When upstream is briefly unavailable, every read tool answers from its last good copy with stale: true and age in seconds.
• Check them before using time-sensitive data.
• changes_since with no saved answer returns your cursor with empty lists and stale: true: poll again with the same cursor.
• When nothing can be served, the answer is 503 upstream_unavailable with retry_after and a Retry-After header (MCP: isError).

What counts as a call

Daily usage is shared across both transports.

Both transports share your daily allowance.

Errors and headers

Use error codes and response headers to decide what to do next.

REST takes API keys (cnis_live_…) only. OAuth connector tokens work only on MCP; on REST they get 401 with a message saying so.

REST errors use these JSON shapes; MCP tool errors carry the same body in structuredContent with isError:

{"error":"unauthorized","status":401,"message":"Invalid credentials."}
{"error":"plan_required","status":403,"message":"get_story needs the Standard plan. Upgrade at mcp.cryptonews.is/account/upgrade or email api@cryptonews.is.","required_plan":"standard"}
{"error":"rate_limited","status":429,"message":"Per-minute limit reached.","retry_after":60}

Requests that Cloudflare’s security layer (WAF) blocks as attacks get HTTP 403 with an HTML page, not a JSON error.

Method versions

Compare readings computed with the same method.

Every reading carries method, identifying how it was computed. METHOD.md describes the calculation and version changes; compare versions when comparing readings.

Attribution and use

Credit the source when displaying data.

Free is for personal use with credit. Standard and Pro may display data with credit and a link to the story’s reader_url. No resale or model training. Read the terms and privacy.

Upgrading

Choose the access your project needs.

Choose a plan at checkout. Standard is $29 / 30 days; Pro is $99 / 30 days. Free is $0. Paid plans return to Free at expiry.