Send messages to Claude from your MCP App

​

Send a message from a view

• role: set it to "user"
• content: put the message here as text blocks

import { App } from "@modelcontextprotocol/ext-apps";

const app = new App({ name: "Shopping list", version: "1.0.0" });
await app.connect();

const button = document.querySelector("#plan");
const status = document.querySelector("#status");

button?.addEventListener("click", async () => {
  let message = "Continue in the conversation.";
  try {
    const { isError } = await app.sendMessage({
      role: "user",
      content: [
        { type: "text", text: "Plan three dinners from this shopping list: milk, eggs, rice, and spinach." }
      ]
    });
    if (isError) {
      message = "Claude didn't take the request.";
    }
  } catch {
    message = "The request couldn't be confirmed.";
  }
  if (status) {
    status.textContent = message;
  }
});

• Asks you to allow the message
• Places the text in your message box, ready to send

​

Write a message that the user can agree to

• Caution: when Claude fills the message box with your view’s text, a caution can appear above the box. The caution opens with “Use caution before running this prompt.”
• Existing draft: Claude doesn’t replace a draft that the user already has in the message box unless they agree

​

Handle the result of app.sendMessage

• isError: true: treat the message as not accepted
• A result with no error: you can receive this result before the user agrees, and you can’t learn their decision from it. Don’t treat it as evidence that Claude read the message.
• A rejected promise: when the MCP Apps SDK stops waiting, after 60 seconds by default, the promise rejects. Don’t tell the user that the message wasn’t sent, because Claude can still have it after that time.

​

Messages that Claude accepts

• Content: send text blocks that aren’t blank. Claude refuses a blank message, and can refuse a message that contains any other kind of block.
• Length: send at most 8,000 characters, counted across all blocks, plus one for each block after the first
• Invisible characters: leave out invisible characters, such as soft hyphens and zero-width spaces, unless Claude recognizes them as part of an emoji or a writing system. Persian, Hindi, and Thai are examples of such writing systems.
• Line breaks: use at most three consecutive line breaks
• Spaces and tabs: use at most 64 consecutive spaces or tabs
• Pace: send a message when the user acts, not on a timer, and don’t retry in code.
  • If you send messages quickly one after another, Claude can refuse them.
  • After the user declines a message, Claude can refuse later messages for a short time.

​

Next steps

• Let Claude call tools in your MCP App: let Claude change what the user has open in the view
• Supersede older widget instances: stop an older copy of your app from sending messages
• Design guidelines: decide which interactions belong in the app and which in the conversation
• Troubleshoot MCP Apps: open developer tools to inspect the view’s requests