Skip to content

Instantly share code, notes, and snippets.

@alexhancock
Last active February 18, 2026 17:22
Show Gist options
  • Select an option

  • Save alexhancock/2bb8b62500f33ccb29a0edb4aa7c5342 to your computer and use it in GitHub Desktop.

Select an option

Save alexhancock/2bb8b62500f33ccb29a0edb4aa7c5342 to your computer and use it in GitHub Desktop.
Proposing Sampling Support for MCP Apps

Proposal: Add sampling/createMessage Support to MCP Apps

Author: Alex Hancock
Date: February 17, 2026
Status: Draft
Reference Implementation: block/goose#7039


Summary

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.


Motivation

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:

  1. Embedded Chat Interfaces - Views can implement their own chat UI with custom system prompts, enabling specialized assistants within a larger conversation
  2. AI-Powered Form Completion - Views can use LLM suggestions to help users fill out complex forms
  3. Content Generation - Views can generate text, code, or other content based on user input
  4. Interactive Tutoring - Educational apps can provide AI-guided explanations and feedback
  5. 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.


Specification Changes

1. Add sampling/createMessage to Standard MCP Messages

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 check

2. Add Sampling to Host Capabilities

Update 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;
  };
}

3. Define Sampling Message Format

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"
  }
}

SDK Changes

1. Add onCreateSamplingMessage Callback to AppBridge

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);
    },
  );
}

2. Add Types to Schema

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() }),
});

3. Add createSamplingMessage Method to App Class

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,
  );
}

Security Considerations

Rate Limiting

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

Content Filtering

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

Audit Logging

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

Cost Management

Hosts MAY implement cost controls:

  • Token budgets per View or session
  • Model restrictions (e.g., only allow smaller models)
  • Rejection of requests exceeding budget

Additional Recommendations

1. Streaming Support (Future Enhancement)

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
  };
}

2. Model Selection (Future Enhancement)

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"]
  };
}

3. React Hook

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 };
}

Implementation Checklist

  • Update specification to add sampling/createMessage to standard messages
  • Add sampling to HostCapabilities interface
  • Define SamplingCreateMessageRequest and SamplingCreateMessageResult schemas
  • Add onCreateSamplingMessage callback to AppBridge class
  • Add createSamplingMessage method to App class
  • Add useCreateSamplingMessage React hook
  • Update capability negotiation documentation
  • Add security considerations to specification
  • Create example app demonstrating sampling (see reference implementation)
  • Add E2E tests for sampling flow

References


Conclusion

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment