Stream tokens | MySpec Docs

Let a script or an agent follow a project's live events, such as new revisions, comments and finished sessions, without a full sign-in.

A stream token lets a client follow one project’s events as they happen: new spec file revisions, comments, sessions starting and finishing, and more. The client needs nothing else to connect: no sign-in and no API token.

Use one when something should react to changes in MySpec, for example a coding agent that waits for a session to finish, or a script that posts a message when a spec file gets a new revision.

A stream token can only read events. It cannot change anything in MySpec.
It covers one project and only the event types you choose.
It expires after 24 hours by default, and after 7 days at most.

Create a stream token

Create one with the create_stream_token tool, from either MCP server. For example, ask your agent:

Create a stream token that follows spec file and session events in my
"Checkout redesign" project for the next two hours.

The tool takes these arguments:

Argument	Required	Meaning
`resource_type`	No	What to follow. `project` is the only option and the default.
`resource_id`	Yes	The project’s id.
`event_types`	Yes	The event types to receive, or `["*"]` for all of them. An empty list is refused.
`ttl_seconds`	No	How long the token lasts, in seconds. The default is 24 hours and the maximum is 7 days. A value outside the allowed range is adjusted rather than refused, so check `expires_at` in the result.
`label`	No	A short name, so people can recognize the token in a list.

The result describes the token (id, label, project, event types, expires_at) and contains everything a client needs to connect, with a note on how to connect. Pass it straight to the client that will follow the events.

["*"] means every event type that exists when you create the token. Event types added to MySpec later are not added to existing tokens.

Who can create one:

Any member who can see the project.
A Read only API token can create stream tokens, because a stream token only reads.
On the remote server, a connector (such as Claude or ChatGPT) connected without write access is asked to reconnect with write access first.

You can only have a limited number of stream tokens per person and per project, and creating them is rate limited. Revoke the ones you no longer need.

Event types

Event type	Sent when
`project.updated`	The project’s name, description, type or status changes, including archive and unarchive.
`project.deleted`	The project is deleted. This ends the token, so it is the last event it sends.
`spec_file.created`	A spec file is added.
`spec_file.updated`	A file gets a new revision, an older revision is restored, or the file is moved to or restored from the Trash Bin.
`spec_file.deleted`	A file is deleted permanently.
`spec_file.lock`	Someone starts, renews, releases or takes over editing a file.
`spec_file_comment.created`	Someone starts a comment thread or replies to one.
`spec_file_comment.updated`	A comment is edited or deleted.
`spec_file_comment.thread_state_changed`	A thread is resolved or reopened.
`spec_file_comment.anchors_updated`	Comment threads move to follow changed text, after a save or after someone re-attaches a thread. One event covers every thread that one save moved.
`attachment.created`	An attachment is uploaded.
`attachment.deleted`	An attachment is removed.
`spec_session.created`	A session starts.
`spec_session.updated`	A session is completed, archived, unarchived or renamed, or its status changes.
`spec_session.deleted`	A session is deleted.
`*`	All of the above.

Events say what happened, not the full content. They never include the text of comments, and new chat messages in a session are not sent as events. To get the details, read the project, file or session with the other MCP tools.

What a client receives

Each message is one line of JSON text:

First, a message that confirms what the token covers: the project, the event types and the expiry. Check it to be sure you connected to the right feed.
Then one message per event, with its type, its time, the project, a sequence number (seq) and the event’s details.
About a minute before the token expires, a warning, so the client can create a new token in time instead of mistaking the end for a network problem.
Before the server ends a connection, an error message with a reason, such as an expired or revoked token.

A new connection receives only events that happen from then on. Every event carries a sequence number, so a client that reconnects can ask for everything after the last event it saw and miss nothing. The note in the create_stream_token result explains how. Events are kept only for as long as the token lives.

Handle closed connections

When the server closes a connection, the close code tells the client what to do:

Close code	Meaning	What to do
`4001`	The token no longer works: it is unknown, expired or revoked, or its project was deleted. The error message before the close says which.	Stop, or create a new token.
`4008`	The connection could not keep up and was dropped.	Reconnect, resuming after the last event you saw.
`4009`	The token already has as many open connections as it allows.	Wait for another connection to close. The token is still good.
`1013`	The feed is unavailable for a moment.	Wait a little, then retry with the same token.

List stream tokens

list_stream_tokens lists the stream tokens in your organization: label, project, event types, who created it, when it expires, whether it still works, how many times it was used and when it was last connected. It never shows the secret, only a short prefix to tell tokens apart.

Argument	Meaning
`resource_id`	Only tokens for this project.
`live_only`	Hide expired and revoked tokens.
`mine_only`	Only tokens you created. Off by default, so you can find any token in your organization.
`limit`, `offset`	Paging. The default page size is 50 and the maximum is 200.

Revoke a stream token

revoke_stream_token takes the token’s id from the create result or from list_stream_tokens, never the secret. Revoking takes effect at once: open connections are closed and the events kept for the token are deleted. A revoked token cannot be turned back on.

You can always revoke a token you created.
To revoke a token someone else created, you need the Owner or Admin role in the organization. Otherwise, ask an owner or admin.
A stream token cannot be extended. When it expires, create a new one.