@stethq/mcp

Local stdio MCP server for Stet. Draft, send, and measure Slack broadcasts from any MCP-capable agent.

Stet is a Slack-first broadcasting tool: compose a message once, target it per audience, preview the real Slack render, then send or schedule it across many channels with delivery tracking. This package exposes that whole workflow as MCP tools, so an agent can draft a broadcast, preview exactly what will land, send it, and read back who replied.

You need a Stet workspace to use this. Sign up at stethq.com.

Install

Nothing to install — npx runs the server on demand.

claude mcp add stet \
  --env STET_API_KEY=bk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --env STET_API_URL=https://app.stethq.com \
  -- npx -y @stethq/mcp

Or add it to your MCP config by hand:

{
  "mcpServers": {
    "stet": {
      "command": "npx",
      "args": ["-y", "@stethq/mcp"],
      "env": {
        "STET_API_KEY": "bk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "STET_API_URL": "https://app.stethq.com"
      }
    }
  }
}

Generate an API key at Dashboard → Settings → API keys. Keys are workspace-scoped; pick the write scope for full functionality (read-only keys can list and measure, but cannot compose or send).

Requires the Growth plan or higher. The REST/MCP surface is gated: below Growth, every call returns 403 with a plan-upgrade-required problem document. If you do not have a workspace yet, start at stethq.com — mention that you want API/MCP access and we will get you on a plan that includes it.

Typical flow

list_sending_profiles        → pick who it comes from
list_channels                → find the channels to hit
create_broadcast             → returns a draft id
set_one_time_channels        → target ad-hoc channels (or pass audience_ids up front)
set_broadcast_content        → write the whole body as Markdown
preview_broadcast            → one audience_id at a time (from list_audiences or
                                the set_one_time_channels response) — see the exact
                                Slack Block Kit that will land
send_broadcast_now           → or schedule_broadcast
—— later ——
get_broadcast_sends          → who got it, who failed, and why
get_broadcast_reactions      → emoji engagement, by channel
get_broadcast_replies        → what people actually said back

Tools

Compose

Tool	Description
create_broadcast	Create a draft with a title, sending profile, and optional target audiences. Returns the new id.
set_broadcast_content	Compose (or replace) the entire body from Markdown — one string, or per-audience segments.
add_block	Append a single content block (section, header, divider, image, context, actions, rich_text_list, fields). Prefer set_broadcast_content for whole bodies.
set_block_visibility	Restrict a block to a subset of the target audiences. Empty array = visible to all.
reorder_blocks	Reorder blocks by supplying the full block-id list in the new order.

Target

Tool	Description
list_channels	List Slack channels in the connected workspace. Free-text query plus structural filters.
list_audiences	List saved audiences (named sets of channels).
create_audience	Create a saved audience from an explicit list of channel ids.
set_one_time_channels	Target a draft at an ad-hoc channel set without creating a saved audience. Empty list deletes the group.
suggest_audiences	Heuristic audience suggestions based on channel-name patterns.
list_sending_profiles	List sender identities configured in this workspace.
create_sending_profile	Create a sender identity: display name, avatar, footer, default audiences.

Check and send

Tool	Description
validate_broadcast	Check for channel-overlap conflicts (one channel in several audiences whose visible blocks differ).
preview_broadcast	Render the per-audience Slack Block Kit exactly as it will be delivered.
send_broadcast_now	Send immediately. If the broadcast is already scheduled, returns 409 with the pending send time — retry with confirm: true to discard that schedule and send now.
schedule_broadcast	Schedule for an ISO timestamp + timezone.
cancel_broadcast	Cancel a scheduled or in-flight broadcast. Already-posted messages stay posted.

Measure

Tool	Description
list_broadcasts	List broadcasts newest-first with status, counts, send time, and a content preview. Optional status filter.
get_broadcast_status	A broadcast's content and lifecycle state: row, target audiences, blocks.
get_broadcast_sends	Per-channel delivery: status, error message, Slack permalink, reply/reaction counts, plus a delivered/failed/pending summary.
get_broadcast_reactions	Emoji reaction totals — overall, by emoji, and by channel.
get_broadcast_replies	In-thread replies with the replier's display name and a permalink. Optional per-channel filter.

Reactions and replies are only captured for messages Stet itself posted — they are matched to a send by channel + timestamp. Messages posted to Slack by other means have no engagement data here.

Engagement history is limited to your plan's retention window: 30 days on Growth and Scale, unlimited on Enterprise. Rows outside the window are hidden, not deleted, and reappear if you upgrade.

Changing the tool schemas

The schemas in src/tools.ts describe a REST API that lives in a separate, private repository — there's no compiler tying the two together, so drift is possible.

Be extra careful with output schemas. Validation on the output side is deliberately fail-soft: a wrong output schema still returns usable data to the caller and only logs a warning to stderr. A mistake here does not show up as a visible failure to anyone using the server.

This repo's unit tests run against a mock and can't catch that kind of drift — the mock fabricates responses that match whatever the schema says, so it can't tell you the schema itself is wrong. The only check that verifies these schemas against the real API is a conformance suite that lives in the API repo (npm run mcp:verify). Pair any release that touches src/tools.ts with a run of it.

Environment

Variable	Required	Description
STET_API_KEY	Yes	Workspace-scoped API key (Dashboard → Settings → API keys).
STET_API_URL	Yes	Base URL of your Stet deployment, e.g. https://app.stethq.com.

License

MIT — see LICENSE.