Synorb: News & Context for AI Agents MCP Server

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.