Prompt handlers returning UserList are rendered as one text message #3643

Initial Checks

• Reproduced with mcp 2.3.0, the latest release when checked.
• Searched the issue tracker for an existing report.

Release line

2.x (current stable)

Description

A prompt handler returning a collections.UserList of messages produces one user message containing a quoted Python representation of the collection. The individual messages and their roles are lost. Returning the same messages in a list or tuple works correctly.

The example below should return a user message containing Question followed by an assistant message containing Answer.

SyncPromptResult accepts Sequence returns, but Prompt.render() only treats lists and tuples as message collections. An empty UserList also returns one text message containing "[]" instead of no messages.

A local fix and regression tests are ready for a PR. The fix handles collections.abc.Sequence while keeping strings as single messages. Eight regression cases cover sync and async handlers, lists, tuples, UserList, and empty UserList results. Four cases fail before the fix; all eight pass afterwards. The full suite passes on Windows and Linux with 100% statement and branch coverage.

I'd like to contribute the fix if you're open to an outside PR.

Example Code

from collections import UserList
from collections.abc import Sequence

import anyio

from mcp import Client
from mcp.server.mcpserver import AssistantMessage, MCPServer, Message, UserMessage

server = MCPServer()


@server.prompt()
def conversation() -> Sequence[Message]:
    return UserList([UserMessage("Question"), AssistantMessage("Answer")])


async def main() -> None:
    async with Client(server) as client:
        result = await client.get_prompt("conversation")
        print([(message.role, message.content.model_dump()) for message in result.messages])


anyio.run(main)

Python & MCP Python SDK

Python 3.11.15 on Windows, mcp 2.3.0 installed from PyPI.
Also reproduced at main/v2.3.0 commit 2118f14f8a19bc158d8a1cf90af58d85d187f849.

We used AI to test and validate the issue.