MCP server

over:heard exposes a standard MCP (Model Context Protocol) server: your AI assistant reads brands and stories, works with advisories (paywall respected), dispatches and validates crisis actions, adds context and creates share links — as the signed-in user, within their permissions.

Endpoint https://overheard.co/mcp · Streamable HTTP (JSON-RPC 2.0) · Auth: OAuth 2.1 + PKCE (dynamic client registration, discovery at /.well-known/oauth-authorization-server) — you sign in, no secret is ever pasted.

Connect a client

Claude / ChatGPT (remote connectors): add a custom connector with the URL https://overheard.co/mcp. Claude Desktop (claude_desktop_config.json):

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

Clients with native remote-MCP support:

{
  "mcpServers": {
    "overheard": {
      "type": "http",
      "url": "https://overheard.co/mcp"
    }
  }
}

Tools

Available on plans that include the API. The tools are generated from the same registry as the OpenAPI reference — same auth model, same scopes, same answers; exactly what tools/list answers.

`v1_list_brands` Partner

[GET /v1/brands] List the brands this key can read: the account's own monitored brands (workspaces) plus the client brands actively delegated to it (delegated: true, with the client account key). Brand-scoped keys see only their scope.

No arguments.

`v1_list_stories` Partner

[GET /v1/stories] List stories (mentions) of one scoped brand. Each row carries the working state the portal shows: severity, last activity, assessment/spread of the advisory, assignment status and whether the full advisory is unlocked.

argument	type
`brand` required	string	brand host, e.g. danone.com

`v1_get_story` Partner

[GET /v1/story] Read one story of a scoped brand (advisory fields follow the same paywall as the UI).

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_post_brand_note` Partner

[POST /v1/brand-note] Publish the official Brand Note on a story — gated: verified or delegated brands only. Never deletes: an empty or missing text is refused (use delete_brand_note).

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`text` required	string	note (600 chars max)

`v1_delete_brand_note` Partner

[DELETE /v1/brand-note] Remove the official Brand Note from a story — the ONLY way to delete it, and an explicit intent. Same gate as publishing.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_complete_phase` Partner

[POST /v1/story/phase-done] Mark one phase of the response plan done (the story auto-closes when every phase is). On a delegated brand the key holder is the operator (assignment stays in the client's portal); on your own brands assign_story exists. Requires the advisory to be unlocked. done_by records the acting key.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`phase` required	integer	1-based phase number
`comment`	string	optional completion note (500 chars)

`v1_add_story_context` Partner

[POST /v1/story/context] Add authoritative client context and regenerate the advisory WITH it (async, 40-90s): poll get_story until advisory_pending appears. NOTHING is applied without an explicit apply_advisory_proposal. Requires the advisory to be unlocked.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`context` required	string	authoritative context (2000 chars)

`v1_apply_advisory_proposal` Partner

[POST /v1/story/advisory-apply] Apply the pending advisory proposal (created by add_story_context). Owner/admin keys only — the same bar as the portal.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_dismiss_advisory_proposal` Partner

[POST /v1/story/advisory-dismiss] Dismiss the pending advisory proposal — the live advisory stays exactly as it was. Owner/admin keys only.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_assign_story` Partner

[POST /v1/story/assign] Assign a story to a teammate — OWN brands only. On a delegated brand the answer is a named 403: the assignee would live in the partner's CRM, not in over:heard, so assignment stays an act of the client's team in their portal. Same rules as the portal: a teammate of your tenant is assigned and notified; an email that belongs to another over:heard account is refused (409); an unknown email answers 404 unless invite=true, which invites them into your team (plan seat cap applies), assigns them the story and sends the invitation. To clear the slot, call unassign_story.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`assignee` required	string	teammate email to assign
`invite`	boolean	pass true to confirm inviting an unknown email into your team

`v1_unassign_story` Partner

[DELETE /v1/story/assign] Clear a story's assignment (status returns to new) — the ONLY way to unassign by API, and an explicit intent (same doctrine as delete_brand_note: a schema-valid empty value must never erase anything). OWN brands only, like assign_story.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_assign_phase` Partner

[POST /v1/story/phase-assign] Assign ONE phase of the response plan to a teammate — OWN brands only (a delegated brand answers the same named 403 as assign_story). THE same implementation as the portal (dispatch_phase_action): plan seat cap, shared email carrying the action link, unknown email refused unless invite=true. Requires the advisory to be unlocked. To clear the slot, call unassign_phase.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`phase` required	integer	1-based phase number
`assignee` required	string	teammate email to assign
`invite`	boolean	pass true to confirm inviting an unknown email into your team

`v1_unassign_phase` Partner

[DELETE /v1/story/phase-assign] Clear one phase's assignee (a done phase stays done) — the ONLY way to unassign a phase by API, an explicit intent. OWN brands only, like assign_phase.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`phase` required	integer	1-based phase number

`v1_trigger_advisory` Partner

[POST /v1/advisory] Unlock the full advisory of a story — THE unlock, the same seam as the portal button (#62/#64: one implementation, three doors). Already unlocked answers ok immediately; an included per-brand unit is consumed first; beyond the quota the unit is metered on the payer's invoice (15 EUR — for a delegated brand under an active grant the payer is the partner), and a metered-billing failure unlocks NOTHING; with no subscription to meter against, checkout_url starts an explicit one-off purchase. Never charges silently. Read the result with get_story.

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id

`v1_create_story_from_url` Partner

[POST /v1/stories/from-url] Generate a story from an article link. over:heard reads the page, then runs the same detection and advisory as for a monitored mention (usually 2-4 minutes) — the story appears in list_stories; if the article is already part of a story of this brand, the answer points at it (status=exists) and nothing is regenerated. Counts as a mention (never billed); the full advisory unlocks like any story.

argument	type
`brand` required	string	brand host
`url` required	string	the article link (http/https, public host)

`v1_list_delegations` Partner

[GET /v1/delegations] Delegation state of the brands in this key's scope.

No arguments.

`v1_drop_delegation` Partner

[DELETE /v1/delegations] Abandon YOUR delegation on one client brand — the symmetric of the client revoking you, and terminal: the grant is revoked, your webhook deliveries for that brand stop (within the 300s routing cache), your Stripe quantity drops at the next recalculation, and a client shell left with no active delegation is handed back its account (7-day reclaim trial — client_account says what happened). Owner/admin keys only.

argument	type
`brand` required	string	client brand host

`v1_create_delegation_invite` Partner

[POST /v1/delegation-invites] Generate a white-label onboarding URL for a client brand. The client signs up through it (email on the brand's own domain), consents to the delegation IN THE APP, completes onboarding, and is redirected to return_url. Idempotent: while a pending invite for the same brand is valid, the same token is returned. Requires a plan with client delegation and a full-scope key.

argument	type
`brand` required	string	client brand host, e.g. client.com
`return_url` required	string	https URL of YOUR product the client returns to right after onboarding

`v1_revoke_delegation_invite` Partner

[DELETE /v1/delegation-invites] Revoke a pending white-label invite you generated. A used, declined or expired invite cannot be revoked.

argument	type
`token` required	string	the invite token

`v1_create_share` Partner

[POST /v1/shares] Create (or retune) the share link of a story briefing — one share per story, same identity as the portal's Share panel. access 'public' is anonymous and tops out at mode 'briefing' (the response doctrine never reaches an anonymous audience — a violating combination is REFUSED, never silently corrected); access 'guests' shares the full advisory to invited guests (manage guests in the portal).

argument	type
`brand` required	string	brand host
`event_uri` required	string	story id
`access`	string	public (default) or guests One of: public, guests.
`mode`	string	compact, briefing (default) or full One of: compact, briefing, full.
`listed`	boolean	public shares only: list the page in the public index

`v1_create_api_key` Partner

[POST /v1/api-keys] Always 403: API keys are managed by Owners/Admins in the app — a key can never mint keys.

No arguments.

`v1_grant_delegation` Partner

[POST /v1/delegations] Always 403: delegation is an explicit client-side act — a key can never self-delegate.

No arguments.

MCP server

Connect a client

Tools

v1_list_brands Partner

v1_list_stories Partner

v1_get_story Partner

v1_post_brand_note Partner

v1_delete_brand_note Partner

v1_complete_phase Partner

v1_add_story_context Partner

v1_apply_advisory_proposal Partner

v1_dismiss_advisory_proposal Partner

v1_assign_story Partner

v1_unassign_story Partner

v1_assign_phase Partner

v1_unassign_phase Partner

v1_trigger_advisory Partner

v1_create_story_from_url Partner

v1_list_delegations Partner

v1_drop_delegation Partner

v1_create_delegation_invite Partner

v1_revoke_delegation_invite Partner

v1_create_share Partner

v1_create_api_key Partner

v1_grant_delegation Partner

`v1_list_brands` Partner

`v1_list_stories` Partner

`v1_get_story` Partner

`v1_post_brand_note` Partner

`v1_delete_brand_note` Partner

`v1_complete_phase` Partner

`v1_add_story_context` Partner

`v1_apply_advisory_proposal` Partner

`v1_dismiss_advisory_proposal` Partner

`v1_assign_story` Partner

`v1_unassign_story` Partner

`v1_assign_phase` Partner

`v1_unassign_phase` Partner

`v1_trigger_advisory` Partner

`v1_create_story_from_url` Partner

`v1_list_delegations` Partner

`v1_drop_delegation` Partner

`v1_create_delegation_invite` Partner

`v1_revoke_delegation_invite` Partner

`v1_create_share` Partner

`v1_create_api_key` Partner

`v1_grant_delegation` Partner