Author: Alex Hancock
Date: February 17, 2026
Status: Draft
Reference Implementation: block/goose#7039
This proposal recommends adding sampling/createMessage as a standard feature of MCP Apps, enabling Views (UI iframes) to request LLM completions directly from the host. This unlocks powerful new use cases for interactive AI-powered applications embedded within conversational interfaces.
MCP Apps currently support a subset of MCP protocol messages for tool calls, resource reads, and logging. However, there is no standardized way for a View to request an LLM completion from the host.
Use Cases Enabled by Sampling:
- Embedded Chat Interfaces - Views can implement their own chat UI with custom system prompts, enabling specialized assistants within a larger conversation
- AI-Powered Form Completion - Views can use LLM suggestions to help users fill out complex forms
- Content Generation - Views can generate text, code, or other content based on user input
- Interactive Tutoring - Educational apps can provide AI-guided explanations and feedback
- Data Analysis Assistants - Views can use LLM reasoning to help interpret visualized data
The reference implementation in Goose demonstrates a working chat interface embedded within an MCP App, proving the viability and value of this feature.
Update the Standard MCP Messages section to include sampling:
### Standard MCP Messages
UI iframes can use the following subset of standard MCP protocol messages:
**Tools:**
- `tools/call` - Execute a tool on the MCP server
**Resources:**
- `resources/read` - Read resource content
**Sampling:**
- `sampling/createMessage` - Request an LLM completion from the host
**Notifications:**
- `notifications/message` - Log messages to host
**Lifecycle:**
- `ui/initialize` → `ui/notifications/initialized` - MCP-like handshake
- `ping` - Connection health checkUpdate the HostCapabilities interface:
interface HostCapabilities {
/** Experimental features (structure TBD). */
experimental?: {};
/** Host supports opening external URLs. */
openLinks?: {};
/** Host can proxy tool calls to the MCP server. */
serverTools?: {
/** Host supports tools/list_changed notifications. */
listChanged?: boolean;
};
/** Host can proxy resource reads to the MCP server. */
serverResources?: {
/** Host supports resources/list_changed notifications. */
listChanged?: boolean;
};
/** Host accepts log messages. */
logging?: {};
// ✨ NEW: Sampling capability
/** Host can fulfill sampling requests from the View. */
sampling?: {
/** Supported content modalities for messages (default: ["text"]) */
supportedModalities?: Array<"text" | "image">;
};
/** Sandbox configuration applied by the host. */
sandbox?: {
/** Permissions granted by the host. */
permissions?: {
camera?: {};
microphone?: {};
geolocation?: {};
clipboardWrite?: {};
};
/** CSP domains approved by the host. */
csp?: McpUiResourceCsp;
};
}Add a new section documenting the sampling request/response format:
// Request (View → Host)
{
jsonrpc: "2.0",
id: 1,
method: "sampling/createMessage",
params: {
/** Conversation messages for context */
messages: Array<{
role: "user" | "assistant";
content:
| { type: "text"; text: string }
| { type: "image"; data: string; mimeType: string };
}>;
/** Optional system prompt to guide the model */
systemPrompt?: string;
/** Maximum tokens to generate (host may enforce limits) */
maxTokens?: number;
}
}
// Success Response
{
jsonrpc: "2.0",
id: 1,
result: {
/** Model identifier used for completion */
model: string;
/** Reason generation stopped ("end_turn", "max_tokens", etc.) */
stopReason: string;
/** Always "assistant" for completions */
role: "assistant";
/** Generated content */
content: { type: "text"; text: string };
}
}
// Error Response
{
jsonrpc: "2.0",
id: 1,
error: {
code: -32000,
message: "Sampling not supported" | "Rate limit exceeded" | "Content policy violation"
}
}Add a new callback setter to the AppBridge class for handling sampling requests:
/**
* Register a handler for sampling requests from the view.
*
* The view sends `sampling/createMessage` requests when it wants to generate
* an LLM completion. The handler should process the request using the host's
* configured LLM provider and return the completion result.
*
* The host MAY:
* - Enforce rate limits on sampling requests
* - Apply content filtering to inputs and outputs
* - Log requests for audit purposes
* - Reject requests based on security policy
*
* @param callback - Handler that receives sampling params and returns a result
* - `params.messages` - Conversation history for context
* - `params.systemPrompt` - Optional system prompt
* - `params.maxTokens` - Optional token limit
* - `extra` - Request metadata (abort signal, session info)
* - Returns: `Promise<SamplingCreateMessageResult>`
*
* @example
* ```typescript
* bridge.onCreateSamplingMessage = async ({ messages, systemPrompt, maxTokens }, extra) => {
* const response = await llmProvider.complete({
* messages,
* systemPrompt,
* maxTokens: Math.min(maxTokens ?? 1000, 4000), // Enforce limit
* });
*
* return {
* model: response.model,
* stopReason: response.stopReason,
* role: "assistant",
* content: { type: "text", text: response.text },
* };
* };
* ```
*/
set onCreateSamplingMessage(
callback: (
params: SamplingCreateMessageRequest["params"],
extra: RequestHandlerExtra,
) => Promise<SamplingCreateMessageResult>,
) {
this.setRequestHandler(
SamplingCreateMessageRequestSchema,
async (request, extra) => {
return callback(request.params, extra);
},
);
}Add the following types to the generated schema:
// In specification schema
export const SamplingMessageSchema = z.object({
role: z.enum(["user", "assistant"]),
content: z.union([
z.object({ type: z.literal("text"), text: z.string() }),
z.object({ type: z.literal("image"), data: z.string(), mimeType: z.string() }),
]),
});
export const SamplingCreateMessageRequestSchema = z.object({
method: z.literal("sampling/createMessage"),
params: z.object({
messages: z.array(SamplingMessageSchema),
systemPrompt: z.string().optional(),
maxTokens: z.number().optional(),
}),
});
export const SamplingCreateMessageResultSchema = z.object({
model: z.string(),
stopReason: z.string(),
role: z.literal("assistant"),
content: z.object({ type: z.literal("text"), text: z.string() }),
});Add a convenience method to the App class for Views to request completions:
/**
* Request an LLM completion from the host.
*
* Sends a `sampling/createMessage` request to the host, which will use its
* configured LLM provider to generate a completion based on the provided
* messages and optional system prompt.
*
* Before calling this method, check that the host supports sampling via
* `hostCapabilities.sampling`.
*
* @param params - Sampling parameters
* - `messages` - Conversation history for context
* - `systemPrompt` - Optional system prompt to guide the model
* - `maxTokens` - Optional maximum tokens to generate
* @param options - Request options (timeout, abort signal)
* @returns Promise resolving to the completion result
* @throws Error if host doesn't support sampling or request fails
*
* @example
* ```typescript
* const result = await app.createSamplingMessage({
* messages: [
* { role: "user", content: { type: "text", text: "Hello!" } }
* ],
* systemPrompt: "You are a helpful assistant.",
* maxTokens: 500,
* });
* console.log(result.content.text);
* ```
*/
async createSamplingMessage(
params: SamplingCreateMessageRequest["params"],
options?: RequestOptions,
): Promise<SamplingCreateMessageResult> {
return this.request(
{ method: "sampling/createMessage", params },
SamplingCreateMessageResultSchema,
options,
);
}Hosts SHOULD implement rate limiting on sampling requests to prevent abuse:
- Per-View request limits (e.g., 10 requests/minute)
- Per-session token limits
- Global rate limits across all Views
Hosts MAY apply content filtering to:
- Input messages before sending to the LLM
- Output content before returning to the View
- System prompts to prevent prompt injection
Hosts SHOULD log sampling requests for security review:
- Request timestamp and View identifier
- System prompt and message count
- Token usage and model used
- Any content policy violations
Hosts MAY implement cost controls:
- Token budgets per View or session
- Model restrictions (e.g., only allow smaller models)
- Rejection of requests exceeding budget
Consider adding streaming support for sampling responses in a future iteration:
// Future: Streaming sampling
interface HostCapabilities {
sampling?: {
supportedModalities?: Array<"text" | "image">;
streaming?: boolean; // NEW: Host supports streaming responses
};
}Allow Views to request specific models or model capabilities:
// Future: Model hints
params: {
messages: SamplingMessage[];
systemPrompt?: string;
maxTokens?: number;
modelHints?: {
preferredModels?: string[]; // e.g., ["gpt-4", "claude-3"]
capabilities?: string[]; // e.g., ["vision", "code"]
};
}Add a React hook for convenient sampling in React-based Views:
// useCreateSamplingMessage hook
function useCreateSamplingMessage() {
const app = useApp();
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);
const createMessage = useCallback(async (params: SamplingCreateMessageParams) => {
setIsLoading(true);
setError(null);
try {
return await app.createSamplingMessage(params);
} catch (e) {
setError(e as Error);
throw e;
} finally {
setIsLoading(false);
}
}, [app]);
return { createMessage, isLoading, error };
}- Update specification to add
sampling/createMessageto standard messages - Add
samplingtoHostCapabilitiesinterface - Define
SamplingCreateMessageRequestandSamplingCreateMessageResultschemas - Add
onCreateSamplingMessagecallback toAppBridgeclass - Add
createSamplingMessagemethod toAppclass - Add
useCreateSamplingMessageReact hook - Update capability negotiation documentation
- Add security considerations to specification
- Create example app demonstrating sampling (see reference implementation)
- Add E2E tests for sampling flow
- Reference Implementation: block/goose#7039 - Working implementation in Goose desktop client
- MCP Apps Specification: apps.mdx
- MCP Sampling Specification: MCP Sampling
Adding sampling/createMessage support to MCP Apps enables a new class of AI-powered interactive applications. The reference implementation in Goose demonstrates the viability of this approach, and the proposed changes maintain consistency with existing MCP Apps patterns while providing appropriate security controls.
We recommend this feature be added to the MCP Apps specification as a standard capability, with hosts free to implement rate limiting, content filtering, and cost controls as appropriate for their environment.