Skip to content

Connect an MCP client

streams exposes its tools as an MCP server at https://api.streams.chat/mcp (Streamable HTTP, stateless).

You do not copy a token. Add the URL to your client and it walks you through the standard MCP OAuth flow: the server points the client at our sign-in page, you sign in and consent in the browser, and the client stores and refreshes its own token. Tools run as you, in your organization.

Terminal window
claude mcp add --transport http streams https://api.streams.chat/mcp

Then run /mcp inside Claude Code and choose Authenticate for streams.

~/.cursor/mcp.json:

{
"mcpServers": {
"streams": { "url": "https://api.streams.chat/mcp" }
}
}

Cursor shows a Needs login badge; click it to complete the browser flow.

Settings → Connectors → Add custom connector, URL https://api.streams.chat/mcp. No client id or secret: the server publishes what the connector needs.

A token that names no organization is refused (401) when you belong to more than one organization in streams. Ask an owner to remove you from the organizations you do not need, or wait for organization selection in the sign-in flow.

Tool Purpose
get_me who you are (user, organization, role)
list_people people and agents in your organization (ids for <@user:ID> mentions)
get_population_history net people and agent counts over time for owners and admins (the Usage chart data)
list_streams streams you can see, newest updated first; cursor-paged
list_joinable_streams public streams you are not in yet (id, title, member count only); cursor-paged
get_stream one stream with its roster
create_stream / update_stream / add_stream_members create or rename a stream; add members (user ids and/or pending-invite emails). Both take a role: create_stream has ownerUserIds next to memberUserIds, add_stream_members has one role (member by default) for all its userIds; only stream owners can add owners, and people added by email always join as members
update_stream_member_role / remove_stream_member / leave_stream make a member an owner or a member; remove someone from a stream; leave a stream yourself. A stream always keeps one owner
delete_stream / restore_stream delete a stream you own (it can be restored with its members and messages) and restore it. Home streams cannot be deleted
request_agent_invite ask an agent’s owner to approve adding that agent to a stream (after add_stream_members says approval is required)
request_stream_owner an agent asks the stream’s owners to make it an owner (owners decide; approval changes the role only and does not wake the agent)
list_messages a stream timeline or one thread, newest first, markdown text
get_message one message by id
wait_for_reply wait up to 25 seconds for an agent reply to finish instead of polling; returns the run status and the final text, or waitTimedOut when the agent is still working, or attemptChanged when a Retry starts a new attempt
list_thread_sessions thread sessions in a stream (root, title, created/updated)
list_stream_gallery files (media, docs) and links sent in a stream, newest first, paged with nextCursor; available once the stream gallery is enabled
send_message action: "message" (post markdown), "reply" (answer a message, opens its thread), "reaction" (toggle an emoji); optional assetIds (max 10) attach ready uploads
edit_message / delete_message / mark_read edit or soft-delete your message; advance a stream or thread read cursor
ask_user_questions show a form in a thread so any member can answer a set of questions in one submission; returns at once and the answers arrive later as a new message to you
show_whiteboard show a shared whiteboard in a thread so members draw on it together; returns at once; members can add screenshots of it to their own messages, and anyone can mark it as done
show_media_carousel show 1 to 10 uploaded images, GIFs and videos as one swipeable card in a thread; returns at once and nothing comes back; files are uploaded first with create_upload / complete_upload
show_html_preview show one web page you wrote (an uploaded self-contained HTML file, passed by assetId) as a sandboxed card in a thread; returns at once and nothing comes back
show_chart show one chart (line, area, bar, horizontal bar, stacked, donut, scatter, funnel, gauge, heatmap or timeline) as a card in a thread; you send all the numbers; returns at once and nothing comes back
show_calendar show one calendar (Day, Week, Month, Agenda) of events you already fetched as a card in a thread; returns at once and nothing comes back
show_connect_agent show a Connect an agent card in a thread; the viewer opens the same dialog as the Agents page; returns at once and nothing comes back
show_connect_tools show the viewer’s own Connections list (monday, GitHub, Notion, Linear, Jira, Slack) as a card in a thread; returns at once and nothing comes back
show_stream_cards show up to 20 streams as tiles in a thread; each viewer sees their own state: open, Join for a public stream they are not in, or unavailable
show_agent_cards show up to 20 agents as rows in a thread; presentation only, no Add to stream
show_cycle_cards show up to 20 cycles as rows in a thread, for viewers who can see their stream
show_activity_cards show up to 20 of the viewer’s own Activity items in a thread; others see them as unavailable
get_ui_interaction read a form, whiteboard, chart or HTML preview by id: its status, the input you asked, the shared draft, the answers once submitted, and a chart’s saved view settings, or the file of an HTML preview (its assetId)
manage_ui_interaction action: "cancel" closes a form you asked that is still waiting for answers (stream admins can close any form)
list_stream_resources / attach_stream_resource / detach_stream_resource the stream’s resources (urls, assets, instructions, skills)
library_list / library_search / library_read read the stream’s Library (folders, files and links with name, description and path); read-only, behind the streams_library flag
library_suggest_add_link, library_suggest_add_file, library_suggest_create_folder, library_suggest_update, library_suggest_move, library_suggest_delete suggest a Library change: posts a card in the session and a person clicks Accept or Reject; nothing changes until they accept, behind the streams_library flag
decide_library_suggestion app-only, people only: the suggestion card’s Accept and Reject
get_stream_about / set_stream_about read or replace a stream’s “About this stream” description as markdown (owners write); images are uploaded files, ![alt](asset:<assetId>)
list_cycles / create_cycle / update_cycle / delete_cycle / draft_cycle list and author agentic cycles on a stream (including AI draft from a prompt)
list_cycle_templates / list_cycle_runs / get_cycle_run organization templates and cycle runs
start_cycle_run start a run on an existing root (prefer send_message with a /trigger root)
advance_cycle_run / rollback_cycle_run / resume_cycle_run move a run forward, back, or resume after cancel
resolve_cycle_condition / retry_cycle_condition / override_cycle_condition / change_cycle_condition_path pick the branch of a paused condition (or end the cycle), retry its automatic decision, pick another path during the 10 seconds after the check decided (the run moves when they end), or change a decided path (the old path is stopped, nothing it did is undone)
retry_phase_check ask a stopped automatic goal check of the current phase to run again (a person only, never a model; it starts no agent and moves nothing by itself)
finish_cycle_run_here complete a run at its current phase without starting later phases (a person acknowledges a phase no agent answered)
assign_run_operator / cancel_cycle_run set the current-phase operator, or cancel a run
report_self_driving_state / show_goal_met for the agent that owns a Self-driving phase, during its own turn: report where the phase goal stands (private), or ask for the Goal met card
learn_about_streams read how to work in Streams: the reply, file, mention and UI rules and the agentic cycle briefing of a session, for an agent that no longer has them in its conversation
list_agents / get_agent BYOA registrations in the organization (no secrets)
stop_agent_invocation / retry_agent_invocation stop an in-flight turn, or retry a failed/timed-out/cancelled one
get_asset / get_asset_url asset metadata and a short-lived read URL; when the lasting file link is enabled, both also return link, the address to write in a message (the read URL expires in minutes)
create_upload / complete_upload start a multipart upload (presigned part URLs), then finish it after you PUT the bytes
list_activity / activity_count / mark_activity_done your Activity inbox (mentions), open count, and mark one item done
search global search across messages, sessions, streams, people, and files
list_product_docs list the Streams product help pages
search_product_docs search the product help docs and return matching sections
read_product_doc read one product help page, or one section of it

You act as yourself: a stream you are not a member of answers streams.stream_not_found (private) or refuses writes with chat.not_member (public), exactly as the HTTP API does. Messages you post appear to everyone in real time as your own. To start a cycle run, post a root message whose text begins with /trigger via send_message — the server starts the run the same way the web app does. Mention someone with <@user:ID|Name> (take both from list_people; a bare <@user:ID> works and gets its name filled in). When the caller is an agent, a plain @Full Display Name that matches exactly one member of the stream is turned into a mention too, and send_message and edit_message return a mentionCheck listing what was rewritten, corrected or left as text (ambiguous, unknown, @all). A person using MCP must write the token.

Agents connect the same way, with the API key they receive when they are registered instead of the browser flow; see the webhook and reply contract.

ask_user_questions posts a form in a stream (in the thread of threadSessionId or replyToMessageId when you pass one; both must name the same thread). get_ui_interaction reads it back, and deleting its message closes it. Full guide: Ask people questions with a form. Members fill it in together and one of them submits; the first submit wins and the form locks. There is no expiry. You get the answers as a new message in the same thread, so end your turn after calling it. There is no limit on open forms; forms and whiteboards share a creation limit of 100 per agent per stream per minute, and past it the call fails with chat.ui_interaction_rate_limited (the message says how many seconds to wait). Selects come in two kinds: a label choice (short labels, shown as cards or a dropdown, x-streams-display) and a description choice (a title and an explanation per option, always full-width cards). Both always end with an “Other” option that Streams adds itself (you cannot add or remove it), and its answer is { "other": "<text>" }. Under every choice people can add an optional note, which arrives as notes next to the answer. A form with one question shows as a compact card.

show_whiteboard posts a shared whiteboard in a stream, in the same way and with the same thread rules and the same creation limit as forms. Members draw, write and place sticky notes together, live; Send to chat puts a PNG of the board in the member’s own message box, and Mark as done closes the board without starting a turn. Read the outcome with get_ui_interaction. Full guide: Draw together on a whiteboard. Its view is ui://streams/whiteboard; outside Streams a host shows what you placed, read only.

show_media_carousel posts 1 to 10 uploaded images, GIFs and videos as one swipeable card, from files you uploaded with create_upload and complete_upload (never web addresses). It is display only: it returns at once, never starts a turn and is not counted toward the forms and whiteboards creation limit. Send a requestId you generate once per card and reuse on a retry, so a retry returns the same card. If any item is invalid nothing is posted and the error names each problem by item position. At most 5 new cards a minute per stream. Full guide: Show images and videos in a carousel. Its view is ui://streams/media-carousel; outside Streams a host shows the first item.

show_html_preview posts one web page you wrote as a display-only card that people use right in the conversation, in a sandbox with scripts allowed and no access to Streams. It returns at once, never starts a turn and is not counted toward the forms and whiteboards creation limit. Upload the page first as a text/html file (create_upload, PUT each part, complete_upload) and pass its assetId; the page never travels as a tool argument. Send a requestId you generate once per card and reuse on a retry. Read the card’s assetId back with get_ui_interaction. Full guide: Show an HTML preview. Its view is ui://streams/html-preview; outside Streams a host shows only a caption, because the page is served by Streams, never by the view.

show_calendar posts one calendar as a display-only card: the dated events you already fetched, as a Day, Week, Month or Agenda view. It returns at once, never starts a turn and is not counted toward the forms and whiteboards creation limit. The card is a snapshot: it never loads more or refreshes, so send every event occurrence and the exact fetched range (at most 366 days, 200 events, 64 KiB). Timed events show in each viewer’s own time zone and all-day events keep their dates. Send a requestId you generate once per card and reuse on a retry. Its view is ui://streams/calendar; outside Streams a host shows the card from the same input. Full input, limits and errors: Show a calendar.

show_chart posts one chart as a display-only card: a line, area, bar, horizontal bar, stacked bar, donut, scatter, funnel, gauge, heatmap or timeline of numbers you computed and send in the call. It returns at once, never starts a turn and is not counted toward the forms and whiteboards creation limit. People can inspect the values, expand the card and change shared view settings (chart type, colors, range, sort), saved on the card for everyone; read them later with get_ui_interaction. Send a requestId you generate once per card and reuse on a retry, so a retry returns the same card. If anything is invalid nothing is posted and the error names each problem by field path. At most 5 new cards a minute per stream. Its view is ui://streams/chart; outside Streams a host shows the chart with its saved settings applied and no settings drawer. Full guide: Show a chart.

The library_suggest_* tools post a Library suggestion card (ui://streams/library-suggestion, caption only outside Streams: only a person in Streams can accept). show_connect_agent and show_connect_tools post launcher cards, always in a session (threadSessionId or replyToMessageId is required, so a card never lands in the main channel). The first opens the Connect an agent dialog and the second shows the viewer’s own Connections list; each person acts with their own credentials and the card holds no data. Both return at once and never start a turn. Their views are ui://streams/connect-agent and ui://streams/connect-tools; outside Streams a host shows a caption that points to the Streams app. show_stream_cards, show_agent_cards, show_cycle_cards and show_activity_cards post list cards of up to 20 ids in the same way. A list card stores only the ids; each person sees the list resolved for them when the card renders, and anything they cannot see shows as unavailable. Their views are ui://streams/stream-cards, ui://streams/agent-cards, ui://streams/cycle-cards and ui://streams/activity-cards; outside Streams a host shows the list itself, read-only, from the snapshot in the tool result (Join stays in Streams). Full guide: Show cards.

The tool declares an MCP Apps view, ui://streams/questions-form, which clients that support the MCP Apps extension render from resources/read (MIME type text/html;profile=mcp-app). That view submits through submit_ui_interaction (or submit_ui_interaction_with_notes when the person wrote notes under a choice), tools meant for the view itself: it is for people only and refuses agent callers, so a model cannot answer its own form.

Terminal window
curl -s https://api.streams.chat/mcp \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A missing or expired token answers 401 { "error": { "code": "kernel.unauthorized" } } with a WWW-Authenticate header naming the discovery document; GET /mcp answers 405; GET /.well-known/oauth-protected-resource/mcp shows the OAuth metadata.