Synorb: News & Context for AI Agents

Tip: while you set up, a short note to your user helps. For example: 'I'm getting a Synorb demo key and connecting. This can take a minute or two.' Setup page: https://synorb.com/connect/start Self-provision a free 72-hour Synorb demo key. No email, no form, no browser step -- for agent runtimes that cannot call POST /api/connect/demo-key or inject an Authorization header into an already-open MCP session. Keyless: call this with no credential at all. New keys are capped per network; on demo_key_rate_limited, follow next_step (bind an email) or wait retry_after_seconds, and reuse the key you already have instead of calling again. Reuse is per visitor, not per network: pass back the `visitor_token` from your earlier response to get the SAME key; a call without it mints a new org and quota. Once you hold the key, prefer sending it as `Authorization: Bearer <api_key>` on later tool calls; only pass it as the `api_key` argument on a tool call itself if your MCP host genuinely cannot set headers on this session -- that argument may then be visible in your own transcripts/logs, so it is the documented fallback, not the recommended path.

Rank Stream candidates for ambiguous research topics. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: source choice is unclear after stream-search or the user needs candidate Streams. DO NOT USE THIS WHEN: the user named specific entities, asks inventory/source availability, or needs content directly.

Inspect Stream metadata, source channels, filters, and recent volume. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: you have stream_ids and need source/filter details before pulling Manifests. DO NOT USE THIS WHEN: the user wants content/news; use synorb-manifests.

Search accessible Stream/source inventory with typo and synonym handling. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: the user asks what streams/sources/podcasts/publishers are available. DO NOT USE THIS WHEN: the user needs actual Manifest content or already named exact content filters.

Pull, count, or orient over source-cited Manifests. For recurring watches prefer beacon_id with an explicit lookback, and dedupe by manifest_id. delivery_delta=true can use a stream/channel-only Beacon as scope when enabled. stream_ids, home_domains, and source_channel_ids are INTERSECTED; DERIVE source_channel_ids from details/search when unsure. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: the user needs evidence/content with date/entity/topic/source filters. DO NOT USE THIS WHEN: the user only asks inventory, usage, or source availability. OUTPUT: write a briefing (reasoning-v1) from claims and supporting_quotes, not from headlines; keep each first-party link inline and end with a source index. briefing.scaffold lists the ranked items, Claims with exact figures, groups and a recipe for the opening. The server makes no model call when you read.

Account profile, usage, plan, date-window, and freshness. Check plan and existing Beacons early, then propose Beacons from what you know of the user. USE THIS WHEN: the user asks about account, usage, plan, limits, or whether Synorb is working. DO NOT USE THIS WHEN: the user wants content/news; use synorb-manifests.

Draft a Beacon proposal from a monitoring intent; keyless preview. USE THIS WHEN: the user wants a reusable monitor/tracker or asks to configure a Beacon, or unprompted when you know the user's role, interests, or projects: propose 1-3 with a one-line reason each. DO NOT USE THIS WHEN: the user only wants a one-time content pull or asks to save an already valid proposal. needs_clarification = no proposal; ask its questions.

Persist a Beacon proposal to the authenticated account. Zero-usage write -- save only after the user's explicit yes, whether they asked for a saved/recurring monitor or agreed to one you proposed. Never call it on your own initiative; a Beacon writes to the user's account and the user decides if and when that happens. Saved Beacons are pulled by your runtime on your own cadence. The response carries dashboard_url, a private link that opens only for signed-in members of the owning org. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: the user asked for a Beacon, or agreed to save one you proposed. DO NOT USE THIS WHEN: the user lacks a valid authenticated account, or hasn't asked for or agreed to a saved Beacon yet.

List saved Beacons for the authenticated account, including starter Beacons (tag 'starter'). Call at session start to see what is already watched. Each item carries dashboard_url, a private link that opens only for signed-in members of the owning org. Pass beacon_id to read one Beacon's full settings and its revision. USE THIS WHEN: the user asks what Beacons exist, needs a beacon_id, or you must read a Beacon before you edit it. DO NOT USE THIS WHEN: the user wants to run Beacon content; use synorb-manifests with beacon_id.

Archive a saved Beacon by public beacon_id, only after the user says yes to that specific Beacon (starter Beacons, tag 'starter', included); never on your own initiative. USE THIS WHEN: the user asks to archive/delete/clean up a saved Beacon, or agrees to free a slot under the plan's Beacon cap. DO NOT USE THIS WHEN: the user has not agreed, or only wants to list or run Beacons.

Change a saved Beacon: name, description, tags, default_date_window, status (active or archived), stream_ids, source_channel_ids, topic_filters, manifest_config_patch (merged by key; it can hold exclude_source_channel_ids, exclude_media_formats and exclude_title_terms, headline phrases to drop), natural_language_intent, prompt_text, visibility, entity_filters (saved only; never applied when a Beacon runs). Ask the user before you change streams, channels, filters or status. A change to default_date_window alone needs no new yes when the user asked for recurring updates. Read the Beacon with synorb-beacons(beacon_id), then pass its revision as expected_revision. dry_run (default true) returns a before/after diff and writes nothing; set dry_run=false after the user says yes, or for a window-only change. Adding scope needs allow_widening=true. Starter Beacons keep surface_ids. 17-digit Synorb ID values: pass them as JSON strings, never a number. USE THIS WHEN: the user asks to change, rename, re-scope, or turn on or off a saved Beacon. DO NOT USE THIS WHEN: the user has not agreed, or wants a new Beacon; use synorb-save-beacon.