How to implement sampling (LLM calls) in MCP

1// The sampling flow:
2// 1. Client calls tool on server
3// 2. Server needs AI analysis as part of the tool
4// 3. Server sends sampling/createMessage to client
5// 4. Client shows user approval dialog
6// 5. Client routes to its AI model
7// 6. Client returns generated message to server
8// 7. Server uses the result in its tool response

1// TypeScript
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5const server = new McpServer({ name: "sampling-server", version: "1.0.0" });
6
7server.registerTool("analyze-data", {
8  description: "Analyze a dataset and return AI-generated insights",
9  inputSchema: {
10    data: z.string().describe("Data to analyze (JSON or CSV format)"),
11    question: z.string().describe("Specific question about the data"),
12  },
13}, async ({ data, question }, extra) => {
14  // Request the client's AI model to analyze the data
15  try {
16    const samplingResult = await extra.requestSampling({
17      messages: [
18        {
19          role: "user",
20          content: {
21            type: "text",
22            text: `Analyze this data and answer the question.\n\nData:\n${data}\n\nQuestion: ${question}\n\nProvide a concise, data-driven answer.`,
23          },
24        },
25      ],
26      maxTokens: 1000,
27      systemPrompt: "You are a data analyst. Provide precise, factual analysis based only on the data provided.",
28    });
29
30    return {
31      content: [{
32        type: "text",
33        text: `Analysis:\n${samplingResult.content.type === "text" ? samplingResult.content.text : "Non-text response"}`,
34      }],
35    };
36  } catch (error) {
37    return {
38      content: [{ type: "text", text: `Error: Sampling not available — ${(error as Error).message}` }],
39      isError: true,
40    };
41  }
42});

1// TypeScript — model preferences
2const samplingResult = await extra.requestSampling({
3  messages: [{
4    role: "user",
5    content: { type: "text", text: "Summarize this document..." },
6  }],
7  maxTokens: 500,
8  modelPreferences: {
9    hints: [
10      { name: "claude-sonnet-4-20250514" },  // Preferred model
11      { name: "claude" },             // Fallback: any Claude model
12    ],
13    costPriority: 0.3,           // 0 = cheapest, 1 = most expensive ok
14    speedPriority: 0.7,          // 0 = slowest ok, 1 = fastest
15    intelligencePriority: 0.5,   // 0 = simplest, 1 = smartest
16  },
17  systemPrompt: "Provide a brief summary in 2-3 sentences.",
18});

1// TypeScript — multi-step tool with sampling
2server.registerTool("smart-report", {
3  description: "Generate an AI-analyzed report from database data",
4  inputSchema: {
5    tableName: z.string().describe("Table to analyze"),
6    metric: z.string().describe("Metric to focus on"),
7  },
8}, async ({ tableName, metric }, extra) => {
9  try {
10    // Step 1: Fetch data from database
11    const data = await pool.query(
12      `SELECT * FROM ${tableName} ORDER BY created_at DESC LIMIT 100`
13    );
14
15    // Step 2: Use sampling to analyze the data
16    const analysis = await extra.requestSampling({
17      messages: [{
18        role: "user",
19        content: {
20          type: "text",
21          text: `Analyze this data focusing on ${metric}:\n\n${JSON.stringify(data.rows, null, 2)}\n\nProvide:\n1. Key trends\n2. Anomalies\n3. Recommendations`,
22        },
23      }],
24      maxTokens: 2000,
25      systemPrompt: "You are a business analyst. Be specific and reference actual data values.",
26    });
27
28    const analysisText = analysis.content.type === "text" ? analysis.content.text : "";
29
30    // Step 3: Return combined result
31    return {
32      content: [{
33        type: "text",
34        text: `Report for ${tableName} — ${metric}\n\nData points: ${data.rowCount}\n\n${analysisText}`,
35      }],
36    };
37  } catch (error) {
38    return {
39      content: [{ type: "text", text: `Error: ${(error as Error).message}` }],
40      isError: true,
41    };
42  }
43});

1// TypeScript — graceful sampling fallback
2server.registerTool("summarize-logs", {
3  description: "Summarize application logs, with AI analysis if available",
4  inputSchema: {
5    hours: z.number().min(1).max(72).default(24)
6      .describe("Hours of logs to analyze"),
7  },
8}, async ({ hours }, extra) => {
9  const logs = await fetchLogs(hours);
10  const summary = {
11    totalEntries: logs.length,
12    errors: logs.filter((l: any) => l.level === "error").length,
13    warnings: logs.filter((l: any) => l.level === "warn").length,
14  };
15
16  // Try AI analysis, fall back to raw summary
17  let analysis = "AI analysis not available (client does not support sampling).";
18  try {
19    const result = await extra.requestSampling({
20      messages: [{
21        role: "user",
22        content: {
23          type: "text",
24          text: `Analyze these application logs and identify patterns:\n\n${JSON.stringify(logs.slice(0, 50), null, 2)}`,
25        },
26      }],
27      maxTokens: 1000,
28    });
29    if (result.content.type === "text") {
30      analysis = result.content.text;
31    }
32  } catch {
33    // Sampling not supported or declined — use raw summary
34  }
35
36  return {
37    content: [{
38      type: "text",
39      text: `Log Summary (last ${hours}h):\n${JSON.stringify(summary, null, 2)}\n\nAnalysis:\n${analysis}`,
40    }],
41  };
42});