0Pricing
MCP Academy · Lesson

Request a Completion from the Host

Call the client to run an LLM prompt.

Request a Completion from the Host is a free MCP Academy lesson on CoddyKit. This is lesson 2 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, and your progress syncs across the web and the CoddyKit app. The MCP Academy course includes 4 lessons in total.

The Request Method

To ask for a generation, your server sends a sampling/createMessage request to the client over the protocol.

{ "method": "sampling/createMessage" }

Reach the Client via Context

Inside a tool you get a Context object. Its session is your line back to the client that can run sampling.

async def tool(topic: str, ctx: Context) -> str:
    ...

Call create_message

The Python SDK exposes ctx.session.create_message. Await it, pass your messages, and you get the model’s reply back.

result = await ctx.session.create_message(
    messages=[...],
    max_tokens=100,
)

Build a SamplingMessage

Each turn you send is a SamplingMessage with a role like user and a content block holding the actual text.

SamplingMessage(role="user",
    content=TextContent(type="text", text=prompt))

Wrap Text in TextContent

Plain text goes inside TextContent with type set to text. That typed wrapper is how MCP carries the message body.

TextContent(type="text", text="Summarize this report")

Always Set max_tokens

Give the model a ceiling with max_tokens. It caps how long the generated reply can be and keeps cost predictable.

max_tokens=200

Read the Result

The reply’s content is a typed block. Check its type, and if it is text, read result.content.text for the answer.

if result.content.type == "text":
    return result.content.text

Inspect Which Model Ran

The result also reports the model the client chose, so you can log exactly which model produced your output.

print(result.model)  # e.g. claude-3-sonnet-20240307

Know Why It Stopped

A stopReason field tells you why generation ended — like endTurn or hitting your max token limit.

result.stopReason  # "endTurn"

A Whole Tool, Briefly

So a sampling tool is: build a message, await create_message, then return the text — just a few lines.

r = await ctx.session.create_message(
    messages=[msg], max_tokens=100)
return r.content.text

It Can Be Rejected

Remember the request may be denied by the user. Treat a rejection like any failure and handle it gracefully.

Quick Check

One detail about making the call from your tool.

Recap

Send sampling/createMessage via ctx.session, wrap prompts in SamplingMessage and TextContent, set max_tokens, then read result.content.text. 💬

Frequently Asked Questions

Is the “Request a Completion from the Host” lesson free?

Yes — the full text of “Request a Completion from the Host” is free to read here on the web. 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. The MCP Academy course includes 4 lessons in total.

What will I learn in “Request a Completion from the Host”?

Call the client to run an LLM prompt. 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, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

How long does the “Request a Completion from the Host” 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

  1. What Sampling Unlocks
  2. Request a Completion from the Host
  3. Shape Messages & Preferences
  4. Human-in-the-Loop Approval
← Back to MCP Academy