list_conversations
Retrieve and filter user conversations in Canvas LMS by scope, IDs, or participants to organize and access message threads.
Instructions
List conversations for the current user.
Args:
scope: Conversation scope ("unread", "starred", "sent", "archived", or "all")
filter_ids: Optional list of conversation IDs to filter by
filter_mode: How to apply filter_ids ("and" or "or")
include_participants: Include participant information
include_all_ids: Include all conversation participant IDs
Returns:
List of conversations
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | unread | |
| filter_ids | No | ||
| filter_mode | No | and | |
| include_participants | No | ||
| include_all_ids | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The core handler function for the 'list_conversations' tool. It validates input parameters, constructs API parameters, calls the Canvas conversations API endpoint, and returns formatted results or errors.
@mcp.tool() async def list_conversations( scope: str = "unread", filter_ids: list[str] | None = None, filter_mode: str = "and", include_participants: bool = True, include_all_ids: bool = False ) -> dict[str, Any]: """ List conversations for the current user. Args: scope: Conversation scope ("unread", "starred", "sent", "archived", or "all") filter_ids: Optional list of conversation IDs to filter by filter_mode: How to apply filter_ids ("and" or "or") include_participants: Include participant information include_all_ids: Include all conversation participant IDs Returns: List of conversations """ valid_scopes = ["unread", "starred", "sent", "archived", "all"] if scope not in valid_scopes: return {"error": f"scope must be one of: {', '.join(valid_scopes)}"} try: params = { "scope": scope, "include_participants": include_participants, "include_all_conversation_ids": include_all_ids } if filter_ids: params["filter[]"] = filter_ids params["filter_mode"] = filter_mode response = await make_canvas_request("get", "/conversations", params=params) if "error" in response: return response return { "success": True, "conversations": response, "count": len(response) if isinstance(response, list) else 0 } except Exception as e: print(f"Error listing conversations: {str(e)}", file=sys.stderr) return {"error": f"Failed to list conversations: {str(e)}"} - src/canvas_mcp/server.py:54-54 (registration)The registration call within register_all_tools that invokes register_messaging_tools(mcp), which defines and registers the list_conversations tool via @mcp.tool() decorator.
register_messaging_tools(mcp) - src/canvas_mcp/tools/messaging.py:11-11 (registration)The registration function that contains the @mcp.tool() decorator and definition for list_conversations.
def register_messaging_tools(mcp: FastMCP) -> None: - Parameter type hints and docstring defining the tool schema for input validation and documentation.
async def list_conversations( scope: str = "unread", filter_ids: list[str] | None = None, filter_mode: str = "and", include_participants: bool = True, include_all_ids: bool = False ) -> dict[str, Any]: """ List conversations for the current user. Args: scope: Conversation scope ("unread", "starred", "sent", "archived", or "all") filter_ids: Optional list of conversation IDs to filter by filter_mode: How to apply filter_ids ("and" or "or") include_participants: Include participant information include_all_ids: Include all conversation participant IDs Returns: List of conversations