Return Messages, Not Just Text
Shape prompt output as structured chat messages.
Return Messages, Not Just Text is a free MCP Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Beyond a Single String
A prompt can do more than return one line. It can return a list of messages to seed a richer, multi-turn opener. 🗂️
Messages Have Roles
Each message carries a role, usually user or assistant. Roles let you stage a short back-and-forth before the user even types.
The Message Helpers
The SDK gives you UserMessage and AssistantMessage helpers so you can build chat turns without hand-writing the raw structure.
from mcp.server.fastmcp.prompts import base
@mcp.prompt()
def ask() -> list[base.Message]:
return [base.UserMessage("Help me debug.")]Return a List
To send several turns, return a list of these message objects. The host replays them in order as the conversation's start.
return [
base.UserMessage("Explain this error."),
base.AssistantMessage("Sure, paste it in.")
]A Single String Still Works
Returning a plain string is just shorthand: the SDK wraps it as one user message. Lists give you finer control over the setup.
Stage the Assistant
An AssistantMessage can prime the model's persona or remind it of rules, so the conversation begins already on the right track.
Set Up Context
Use opening messages to plant context, like coding standards or a role, that the model should keep in mind throughout the task.
Mix Arguments In
You can still slot arguments into any message in the list. The user's inputs flow into a structured conversation, not just one line.
@mcp.prompt()
def debug(error: str) -> list[base.Message]:
return [base.UserMessage(f"Fix this error:\n{error}")]Order Matters
The list order is the turn order. Lead with context or a system-style note, then the user's request, so the model reads it naturally.
Why Use Messages
Structured messages shape a better starting point than one blob of text, especially for tasks that need setup before the real ask.
Keep It Lean
A couple of well-placed turns beat many. Each extra message costs tokens, so include only what truly improves the result.
Quick Check
Let's pin down the richer return type.
Recap: Message Output
Well done! Prompts can return a list of role-tagged messages built with UserMessage and AssistantMessage to stage a richer opener. ✅
Frequently asked questions
Is the “Return Messages, Not Just Text” lesson free?
Yes — the full text of “Return Messages, Not Just Text” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Return Messages, Not Just Text”?
Shape prompt output as structured chat messages. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Return Messages, Not Just Text” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Register Your First Prompt
- Add Arguments to a Prompt
- Return Messages, Not Just Text
- A Code-Review Prompt Template