Skip to content

Show events in a calendar

When your agent has a schedule to show, post it as a calendar instead of a list in text. People switch between Day, Week, Month and Agenda, browse inside the range you fetched, open an event’s details and use Full screen. The tool is show_calendar, part of the Streams MCP server.

show_calendar posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card (older apps, search, push notifications). The caption holds the event count and the date range only, never a title or a location.

  • A snapshot. The card never loads more events and never refreshes. Fetch the events first, then send every occurrence and the exact range you fetched. A recurring event arrives as separate occurrences with unique ids. Dates outside the range show as “not supplied”, never as free time.
  • Display only. Nothing is answered and nothing comes back. The call returns at once and viewing the card never starts a turn.
  • Everyone in the session sees the details. Only post a calendar where the person agreed to share it with that audience.
  • Time zones. Timed events show in each viewer’s own time zone. All-day events keep their dates.
  • All or nothing. If anything is invalid, nothing is posted and the error lists each problem with the path of the field to fix.
  • Safe to retry. requestId is a UUID you generate once per card. Calling again with the same requestId and the same content returns the card already posted (created: false). The same requestId with different content is refused with 409 chat.calendar_request_conflict, and so is a retry after the card’s message was deleted.
  • Rate limit. At most 5 new cards per minute per stream and agent: 429 chat.calendar_rate_limited with the seconds to wait. Retries of an existing card do not count.
Field Type Notes
requestId UUID Generate once per card; reuse it on a retry.
streamId UUID The stream to post in. Your agent must be a member.
threadSessionId UUID, optional Put the card in that thread, by its session id.
replyToMessageId UUID, optional Put the card in the thread of that message. With threadSessionId too, both must name the same thread.
heading string, optional Up to 200 characters.
timeZone string The IANA zone the range and all-day dates are in, for example Europe/Berlin.
range object { start, end }, offset-bearing ISO timestamps, half-open, at most 366 days.
events array Up to 200 events. Every event must overlap the range. The whole input is at most 64 KiB.
initialView string, optional day, week (the default), month or agenda.
initialDate date, optional YYYY-MM-DD, the date the card opens on.
labels object, optional Plain strings that replace the card’s English text.

A timed event is { id, kind: "timed", title, start, end } with offset-bearing timestamps such as 2026-11-17T09:00:00+01:00. An all-day event is { id, kind: "all_day", title, startDate, endDateExclusive } with YYYY-MM-DD dates and an exclusive end. Every event may also carry:

Field Type Notes
description string, optional Up to 2000 characters of plain text.
location string, optional Up to 200 characters.
url string, optional An https link, up to 2048 characters, without credentials.
color string, optional blue, purple, green, orange, red, pink, teal or gray.

The event id is a unique lowercase slug (letters, digits, - or _, at most 40 characters). Titles are at most 200 characters.

{
"requestId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e",
"streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2f",
"heading": "Team week",
"timeZone": "Europe/Berlin",
"range": { "start": "2026-11-16T00:00:00+01:00", "end": "2026-11-23T00:00:00+01:00" },
"initialView": "week",
"events": [
{
"id": "standup",
"kind": "timed",
"title": "Standup",
"start": "2026-11-17T09:00:00+01:00",
"end": "2026-11-17T09:15:00+01:00",
"color": "blue"
},
{
"id": "offsite",
"kind": "all_day",
"title": "Offsite",
"startDate": "2026-11-19",
"endDateExclusive": "2026-11-21"
}
]
}

{ interactionId, messageId, created }. Nothing is returned to you about viewing: browsing, opening details and full screen never create a response or start another turn. You can read the stored card back with get_ui_interaction and its interactionId; the result is the input you posted.

400 chat.calendar_invalid_request lists each problem with the path of the field, for example events.0.url or range.end. Common causes: a time without an offset, an unknown time zone, an event outside the range, a duplicate event id, a range longer than 366 days, more than 200 events, an http link, and input over 64 KiB. Fix the listed fields and call again.