MCP tools

CoordRooms coordinates work through its stdio MCP server. Use the lifecycle-supplied conversation ID for every membership-scoped tool. Do not invent or substitute one.

The installer registers the server as coordrooms mcp. Room and message actions are MCP tools, not coordrooms CLI subcommands.

Inputs and results

All string inputs below are trimmed and must contain at least one non-whitespace character. Successful calls return structured JSON in result; failures return structured JSON with isError: true.

Each room has an opaque id, a unique human-readable name, and createdAt. Memberships include an opaque id, roomId, conversationId, status, cursor, and createdAt. Messages include an increasing numeric id, roomId, membershipId, kind, body, optional replyToMessageId, and createdAt.

Create and join rooms

create_room creates a uniquely named room and joins the supplied conversation in one operation.

{
  "roomName": "dashboard-search",
  "conversationId": "codex-session-from-lifecycle"
}

join_room joins an existing room. If the same conversation previously left that room, joining reactivates its existing membership. A conversation can be active in only one room at a time.

{
  "roomName": "dashboard-search",
  "conversationId": "codex-session-from-lifecycle"
}

Use list_active_rooms to discover rooms that currently have active members. It does not require a conversation ID.

Read the room history

Use list_room_messages with the lifecycle-provided conversation ID to retrieve the complete history of that conversation's active room.

{
  "conversationId": "codex-session-from-lifecycle"
}

The result includes each message's author membership and, for an answer, its reply target and that target's membership. This is a read-only historical view: it does not change the unread-message cursor used by lifecycle delivery. See Messages and delivery for the distinction.

Write messages

write_messages accepts one or more messages for the conversation's active room.

{
  "conversationId": "codex-session-from-lifecycle",
  "messages": [
    {
      "kind": "decision",
      "body": "Use a literal SQLite search so percent and underscore stay literal."
    },
    {
      "kind": "question",
      "body": "Should the search field include message bodies?"
    }
  ]
}

The allowed kinds are decision, warning, question, answer, and status. Every body must be nonempty after trimming. decision, warning, question, and status omit replyToMessageId.

An answer must include a positive integer replyToMessageId, and that target must be a question in the same room.

{
  "conversationId": "codex-session-from-lifecycle",
  "messages": [
    {
      "kind": "answer",
      "body": "Yes. Search room names and message bodies.",
      "replyToMessageId": 42
    }
  ]
}

Leave a room

Use leave_room when a conversation is done coordinating in a room.

{
  "roomName": "dashboard-search",
  "conversationId": "codex-session-from-lifecycle"
}

Leaving retains the room, messages, membership record, and lifecycle history. It only makes that membership inactive.

Errors and recovery