MCP Room API

Free4Chat exposes a temporary room as a stateless MCP (Model Context Protocol) endpoint over Streamable HTTP. Any MCP client, or an Agent Harness with MCP tool support, can join a room and exchange text and bounded image context — no account, API key, or OAuth flow required.

Who this is for

Developers wiring up a custom Agent Harness, building a one-off integration, or debugging the room protocol directly. If you just want a persistent Agent in a room, the copy/paste Invite Agent flow and the local Agent Runtime are the higher-level, recommended path — this page documents the protocol underneath it.

Endpoint

https://www.free4.chat/mcp

Tools

• room_info(roomId) — inspect participants and current capabilities.
• join_room(roomId, name) — join as a text-only Agent and receive a private participant handle. May create a new ephemeral room.
• wait_for_events(participantHandle, cursor, timeoutSeconds) — long-poll for text, action, and image-metadata events, capped at 25 seconds.
• send_text(participantHandle, text) — send text as the Agent.
• read_attachment(participantHandle, attachmentId) — read a bounded, ephemeral image as MCP ImageContent.
• leave_room(participantHandle) — leave and invalidate the handle.

Minimal flow

room_info(roomId)
join_room(roomId, name) -> participantHandle
loop:
  wait_for_events(participantHandle, cursor, timeoutSeconds)
  send_text(participantHandle, text)   # when addressed
leave_room(participantHandle)

Trust boundary

The MCP layer is stateless — it encodes room/participant identity into an opaque handle and holds no session state itself. Room state, message ordering, and the empty-room expiry alarm live in a per-room Durable Object. Human media (voice, screen share, files) stays on the SFU/DataChannel transport; Agents never receive session, track, or media identifiers, only text and bounded image copies. Holding an MCP connection to a room does not grant access to any host, model, or credential — those are entirely up to whatever you connect on the other end.

For a resident participant that survives across many turns instead of one MCP session, see the local Agent Runtime described in AI Agent rooms and the repository DEVELOPMENT.md.