# Toopost: full reference for AI assistants Last updated: 2026-10-15. Source of truth is the app at https://app.toopost.us; this file mirrors it. ## What Toopost is Toopost is a reader and search engine for a user's own trusted sources ("like Google, but only your context"). A user follows trusted sources; Toopost crawls them, normalizes every item into a post (title, lead, full text, source, date, author, language, kind), groups the same story across sources, and keeps everything in one searchable inbox. AI answers questions with numbered citations into those posts. AI agents can read the same inbox through a hosted MCP server, a CLI with a local MCP server and a REST API. Product principles: add trusted sources; keep everything in one inbox; read or filter fast; use AI when needed; connect AI agents to monitor and analyze your trusted sources; turn raw source material into output. Curating and editing posts is a Pro feature. The hosted MCP server (mcp.toopost.us) requires Maxi. API tokens, the CLI, its local MCP server and automations require Pro or Maxi. ## Sources Paste any URL. The resolver tries, in order: a known-host rule (instant feed), feed discovery, sitemap, article listing, JavaScript rendering (Pro/Maxi), page watching (Pro/Maxi), AI extraction (Maxi). - Feeds and websites: RSS, Atom, any site with a feed, sitemap or article listing. Private feeds with basic, bearer, header or query auth (Pro/Maxi). JavaScript-rendered listings (Pro/Maxi). Page watching: a post with a diff summary whenever a page changes (Pro/Maxi). - Platforms: Telegram channels, YouTube channels and playlists, subreddits, Bluesky, Mastodon and the Fediverse (Pleroma, Pixelfed, GoToSocial, Misskey), X, Instagram, Threads, TikTok, VK, LinkedIn company pages, Facebook pages. - Known hosts turned into feeds instantly: Hacker News, Medium, GitHub (user, repository releases/commits/tags), GitLab, Dev.to, Substack, Hashnode, Ghost, WordPress.com, Blogger, LiveJournal, Tumblr, Pinterest, Vimeo, Dailymotion, SoundCloud, Habr, Lobsters, Product Hunt, Steam, Stack Overflow and Stack Exchange, arXiv, Apple Podcasts, Spotify shows. - Push: webhook inbox sources (Maxi). - Import and export: OPML on every plan. - Discover: "For you" recommendations, a Library of about 1,900 sites, channels and podcasts in 10 languages with topic, language and country filters, and "Find sources about…" (catalog, web search and AI suggestions; respects the reader's country and languages; web searches are paid from the AI usage budget, no monthly cap). ## Reading and search - Feed: stories mode (same news grouped across sources) or all posts; day dividers; filters by folder, source, date range, unread; read-on-scroll; cursor pagination; refresh on demand. Ads only on Free. - Search: ⌘K / Ctrl+K spotlight with instant matches, then full-text results ranked by BM25 × freshness (hybrid with vectors where available). Operators: site:host, from:feed|telegram|youtube|reddit, after:YYYY-MM-DD, before:YYYY-MM-DD, quoted phrases, -exclude, natural dates such as "last week". - Ask AI: streamed answer with [n] citations that link to the posts; over one article, the whole feed, a folder, a source or saved posts. No daily cap on any plan; usage comes out of the monthly AI usage budget. Same models on every plan (Free 1×, Pro 10×, Maxi 30×). - Translation: feed-card machine translation (Free 200/day, Pro and Maxi 1,000/day) and article translation with AI on every plan. - Saved: save with a note, collections, unlimited on Pro and Maxi (100 on Free). Alerts on saved searches and views (Maxi). - Posts (Pro/Maxi): create and edit posts, rewrite with AI, translate as a version, keep versions, send to webhooks. Automations schedule digests and publishing. ## MCP server (Maxi) URL: https://mcp.toopost.us. Transport: streamable HTTP. Auth: OAuth 2.1 with dynamic client registration and PKCE S256, or an MCP token as `Authorization: Bearer`. Accepts Maxi only. Setup: - Claude / ChatGPT: add a custom connector with the URL, sign in. - Claude Code: `claude mcp add --transport http toopost https://mcp.toopost.us` - Cursor (.cursor/mcp.json): {"mcpServers":{"toopost":{"url":"https://mcp.toopost.us","headers":{"Authorization":"Bearer YOUR_MCP_TOKEN"}}}} - VS Code (.vscode/mcp.json): {"servers":{"toopost":{"type":"http","url":"https://mcp.toopost.us","headers":{"Authorization":"Bearer YOUR_MCP_TOKEN"}}}} Tools (9). Read: search(q, since, source_ids, list_id, limit, cursor), ask(question, scope{source_ids, list_id, since, saved, collection_id, document_id}, history) — AI answer with [n] citations, uses monthly AI usage, list_feed(since, until, source_ids, list_id, unread, sort, limit, cursor), get_document(id), list_sources(), list_saved(collection_id, q, limit, cursor), list_alerts(unread, limit, cursor). Write: follow_source(canonical_url, name, list_id, trust, strategy), save_document(document_id, note, collection_id). Lists return {items, cursor}. ## CLI and local MCP server (Pro/Maxi) npm package `toopost` 0.3.0, Node ≥ 18.18. Default API https://go.toopost.us. - Menu: `npx toopost` (no arguments in a terminal) opens an arrow-key menu: sign in, today's main stories, ask, feed, search, saved, sources, AI usage, install into your AI agent. - Sign in: `toopost login` prints a link and a code to approve in the browser (works over SSH and inside coding agents); `--no-browser` only prints them; `--json` prints {"step":"approve","verify_url","user_code","expires_in"} first; `--browser` uses OAuth + PKCE with a loopback redirect; `--token ` saves an API token. Headless: `TOOPOST_TOKEN=`. CLI tokens last 90 days and renew while in use. - Commands: feed [--since 24h|7d|today|ISO] [--source id|host|name] [--folder] [--unread] [--search q] [--limit] [--cursor] [--oldest]; read [--fetch]; search ; ask "" [--since] [--source] [--folder] [--saved] [--post id]; saved; save ; unsave ; sources [list|add |remove ]; alerts [--unread] [--limit]; usage; whoami; logout; skills [--mcp] [--force] [--dir]; mcp. - Global: --json (one JSON document on stdout; errors as the last stderr line {"error":{code,reason,message,status?,hint?,details?}}), --api-url, -h, -v. - Error codes and exits: 1 ERROR, 2 BAD_ARGS, 3 NOT_LOGGED_IN, 4 PLAN_REQUIRED / FORBIDDEN, 5 NOT_FOUND, 6 LIMIT, 7 NETWORK / SERVER. - Local MCP server: `toopost mcp` (stdio). Claude Code: `claude mcp add toopost -- npx -y toopost mcp`. Codex (~/.codex/config.toml): [mcp_servers.toopost] command = "npx", args = ["-y", "toopost", "mcp"]. Tools (14): toopost_login, toopost_whoami, toopost_usage, toopost_feed, toopost_search, toopost_ask, toopost_read, toopost_saved, toopost_save, toopost_unsave, toopost_sources, toopost_add_source, toopost_remove_source, toopost_alerts. toopost_login returns a link and a code at once; sign-in finishes in the background. Errors return {error, code, next}. - Agent setup: `npx toopost skills --mcp` writes .claude/skills/toopost/SKILL.md, .cursor/rules/toopost.mdc and a Toopost section in AGENTS.md, and registers the server in .mcp.json and .cursor/mcp.json. - One prompt is enough: "Log into Toopost and give me today's main stories." The agent calls toopost_login, shows the link, the user approves, the agent calls toopost_ask. ## REST API (Pro/Maxi) Base https://go.toopost.us. Create a token in the app under Connections → API (scoped or All permissions). API v2 base: https://go.toopost.us/api/user/v2 (endpoints and curl examples are in the app under Connections → API). Main groups: feed (GET /api/feed, GET /api/feed/documents/:id, POST /api/feed/documents/:id/fetch, POST /api/feed/state), search (GET /api/search/v2), ask (POST /api/ask, SSE), saved (GET /api/saved), sources (GET/POST/DELETE /api/sources, POST /api/sources/subscribe, POST /api/sources/resolve), lists, user and limits. ## Plans and limits | | Free | Pro | Maxi | |---|---|---|---| | Price | $0 | $5/mo, $50/yr | $15/mo, $150/yr | | Sources | 25 | 100 | 300 | | Updates | daily | hourly | every 15 min | | Saved posts | 100 | unlimited | unlimited | | AI usage | base (1×) | 10× | 30× | | Feed card translation | 200/day | 1,000/day | 1,000/day | | Article translation | yes | yes | yes | | Discover web searches | within AI usage | within AI usage | within AI usage | | Posts, versions, AI rewrite | — | yes | yes | | Webhooks, API tokens, CLI + local MCP, automations | — | yes | yes | | Page watching, private feeds, JS sites | — | yes | yes | | Hosted MCP, webhook inbox, alerts, AI extraction | — | — | yes | | Ads | yes | no | no | Every account starts on Free. Store prices on iOS and Android follow the store listing. ## Privacy for AI clients An MCP client or CLI only receives what the tools it calls return: titles, article text, URLs, dates, authors, sources, saved posts, alerts and AI answers from the user's sources. Write tools (follow_source and save_document on the hosted server; save, unsave, add and remove source on the local one) change only follows and saves. The AI provider processes that data under its own policy. Tokens can be revoked in Connections. Full policy: https://toopost.us/privacy. ## Links Site https://toopost.us · App https://app.toopost.us · Agents guide https://toopost.us/agents · Pricing https://toopost.us/pricing · MCP https://mcp.toopost.us · npm https://www.npmjs.com/package/toopost · iOS https://apps.apple.com/us/app/toopost/id6752561440 · Android https://play.google.com/store/apps/details?id=com.bro.toopost · Contact hello@toopost.us