MCP Elicitation: Human-in-the-Loop for MCP Servers

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "minLength": 3,
  "maxLength": 50,
  "format": "email" // Supported: "email", "uri", "date", "date-time"
}

{
  "type": "number", // or "integer"
  "title": "Display Name",
  "description": "Description text",
  "minimum": 0,
  "maximum": 100
}

{
  "type": "boolean",
  "title": "Display Name",
  "description": "Description text",
  "default": false
}

{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "enum": ["option1", "option2", "option3"],
  "enumNames": ["Option 1", "Option 2", "Option 3"]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  }
}

mkdir mcp-server && cd mcp-server

bun init -y

bun add typescript tsx @types/node mastra@latest @mastra/core@latest zod@^3 fetch-to-node hono -D

import { Hono } from 'hono';

const app = new Hono();

import { toFetchResponse, toReqRes } from 'fetch-to-node';

import mcpServer from './mcp-server';

app.all('/mcp/server', async(c) => {
    const { req, res } = toReqRes(c.req.raw);

    await mcpServer.startHTTP({
        url: new URL(c.req.url),
        httpPath: '/mcp/server',
        req,
        res,
        options: {
            sessionIdGenerator: undefined,
        },
    });

    return await toFetchResponse(res);
});

export default {
    ...app,
    port: 4444,
};

import { MCPServer } from '@mastra/mcp';
import tools from './tools';

const mcpServer = new MCPServer({
    version: '0.1.0',
    name: 'MCP server for demonstration purposes',
    description: 'This MCP server shows how to use the MCP server API to create a server that can be used in a chat application.',
    tools,
});

export default mcpServer;

import { createTool } from '@mastra/core';
import { z } from 'zod';
import { spawn } from 'child_process';

export const runCommand = createTool({
    id: 'runCommand',
    description: 'Run a shell command on the server. Prompts for confirmation if the command is dangerous.',
    inputSchema: z.object({
        command: z.string().describe('The shell command to run, e.g., "ls"'),
        args: z.array(z.string()).optional().describe('Arguments for the command'),
    }),
    outputSchema: z.object({
        stdout: z.string(),
        stderr: z.string(),
        code: z.number(),
    }),
    async execute({ context }, options) {
        const dangerousCommands = ['rm', 'mv', 'dd', 'shutdown', 'reboot', 'mkfs', 'chmod', 'chown', 'kill', 'killall', 'poweroff', 'halt'];
        const cmd = context.command.trim();
        const args = context.args || [];

        // Ask for confirmation if the command is dangerous
        if (dangerousCommands.includes(cmd)) {
            const elicitation = (options as any)?.elicitation;

            if (!elicitation || typeof elicitation.sendRequest !== 'function') {
                return {
                    code: -1,
                    stdout: '',
                    stderr: 'Elicitation is not available in this context. Cannot confirm dangerous command.',
                }
            }

            const result = await elicitation.sendRequest({
                message: `Are you sure you want to run the dangerous command: '${cmd}'?`,
                requestedSchema: {
                    type: 'object',
                    properties: {
                        confirm: {
                            type: 'boolean',
                            title: 'Confirm',
                            description: `Confirm running '${cmd}'?`,
                        },
                    },
                    required: ['confirm'],
                },
            });

            if (result.action !== 'accept' || !result.content.confirm) {
                return {
                    code: -1,
                    stdout: '',
                    stderr: 'Command was rejected by the user.',
                }
            }
        }

        return new Promise((resolve, reject) => {
            const child = spawn(cmd, args, { shell: true });
            let stdout = '';
            let stderr = '';

            child.stdout.on('data', (data) => { stdout += data.toString(); });
            child.stderr.on('data', (data) => { stderr += data.toString(); });

            child.on('close', (code) => {
                resolve({ stdout, stderr, code: code ?? -1 });
            });

            child.on('error', (err) => {
                reject(err);
            });
        });
    },
});

export default {
    runCommand,
};

bun src/index.ts

npx assistant-ui@latest create mcp-app
cd mcp-app 
bun add mastra -D

OPENAI_API_KEY=sk-proj-4fpws4nXpCYXsQVK7DdaUCdLNxMa...

import { openai } from '@ai-sdk/openai';
import { frontendTools } from '@assistant-ui/react-ai-sdk';
import { Agent } from '@mastra/core';
import { MCPClient } from '@mastra/mcp';
import { createDataStreamResponse } from 'ai';

// Define the MCP server name and URL for connecting to the tool server
const MCP_SERVER_NAME = 'testing';
const MCP_SERVER_URL = 'http://localhost:4444/mcp/server';

// Initialize the MCP client with server configuration
const mcp = new MCPClient({
    id: '1', // Unique client ID
    servers: {
        [MCP_SERVER_NAME]: {
            url: new URL(MCP_SERVER_URL),
        },
    },
});

// Create an AI agent with a model, name, and instructions
const agent = new Agent({
    model: openai('gpt-4o'), // Use OpenAI GPT-4o model
    name: 'Chat Agent',
    instructions: `
    You are a helpful assistant that provides accurate information. 
    Do not ask questions before running tools, just run them. 
    If you see that the user rejects a tool call, then stop and do not try to find another way to perform the task.
    `,
});


// API route handler for POST requests
export async function POST(req: Request) {
    // Parse the incoming request body for chat messages, system prompt, and tool list
    const { messages, system, tools } = await req.json();

    // Create a streaming response for the chat
    const response = createDataStreamResponse({
        status: 200,
        statusText: 'OK',
        async execute(dataStream) {
            // Run the agent and stream its response to the client
            const agentStream = await agent.stream(messages, {
                system, // Optional system prompt
                toolsets: {
                    ...(await mcp.getToolsets()), // Dynamically load toolsets from MCP server
                },
                clientTools: frontendTools(tools), // Add any client-side tools
            });

            // Merge the agent's output into the HTTP data stream
            agentStream.mergeIntoDataStream(dataStream);
        },
        // Custom error handler for the stream
        onError: (error: any) => `Custom error: ${ error.message }`,
    });

    // Return the streaming response to the client
    return response;
}

// Set up elicitation handler to respond to tool confirmation requests from the server
await mcp.elicitation.onRequest(MCP_SERVER_NAME, async(request) => {
    // Log the server's request and the schema it expects
    console.log('Server request:', request);

    await new Promise(resolve => setTimeout(resolve, 10_000));

    // Respond to the elicitation request
    // NOTE: The action must be one of 'accept', 'decline', or 'cancel' as per the MCP protocol
    // Here, we always decline (for tutorial purposes)
    return {
        action: 'decline',
        content: {
            confirm: false, // Indicate that the dangerous command is NOT confirmed
        },
    };
});

// Run the agent and stream its response to the client
const agentStream = await agent...

import { ToolCallContentPartComponent, useMessage } from '@assistant-ui/react';
import { useState } from 'react';

import type { JSONValue } from 'ai';

type ElicitationData = {
    type: 'elicitation';
    toolCallId: string;
    message: string;
    requestedSchema: JSONValue;
};

export const RunCommandTool: ToolCallContentPartComponent = ({
    toolCallId,
    status,
    args,
    result,
}) => {
    const elicitation = useMessage(
        m => (m.metadata.unstable_data as ElicitationData[])?.find(
            d => d.type === 'elicitation' && d.toolCallId === toolCallId
        )
    );
    const content = result?.structuredContent;
    const [isSubmitting, setIsSubmitting] = useState(false);
    const [submitResult, setSubmitResult] = useState<string | null>(null);
    const isRunning = status.type === 'running';

    function handleElicitationResponse(action: 'accept' | 'decline') {
        setIsSubmitting(true);
        setSubmitResult(null);

        fetch('/api/chat/elicitation', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                toolCallId,
                action,
                content: {
                    confirm: action === 'accept',
                },
            }),
        }).then(async(res) => {
            const data = await res.json();

            setSubmitResult(data.success ? 'Submitted!' : 'Failed to submit');
        }).catch((err) => {
            setSubmitResult(`Error: ${ err.message }`);
        }).finally(() => {
            setIsSubmitting(false);
        });
    }

    return (
        <div className="flex flex-col gap-3 py-3 mb-4 w-full rounded-lg border">
            <div className="flex gap-2 items-center px-4">
                <code className="font-mono text-sm font-semibold">
                    { `${ args.command }${ (Array.isArray(args.args) && args.args.length > 0) ? ` ${ args.args.join(' ') }` : '' }` }
                </code>
            </div>

            {/* Elicitation while running, show button to accept or decline */}
            {(isRunning && elicitation != null) && (
                <div className="flex flex-col gap-2 px-4 pt-2 text-xs border-t border-dashed">
                    <pre className="whitespace-pre-wrap">
                        {elicitation.message}
                    </pre>
                    <div className="flex gap-2 mt-2">
                        <button
                            className="px-3 py-1 text-gray-800 bg-gray-200 rounded border border-gray-300 hover:bg-gray-300"
                            onClick={ () => handleElicitationResponse('accept') }
                            disabled={ isSubmitting }
                        >
                            Accept
                        </button>
                        <button
                            className="px-3 py-1 text-gray-800 bg-gray-200 rounded border border-gray-300 hover:bg-gray-300"
                            onClick={ () => handleElicitationResponse('decline') }
                            disabled={ isSubmitting }
                        >
                            Decline
                        </button>
                        {isSubmitting && <span className="ml-2">Submitting...</span>}
                        {submitResult && <span className="ml-2">{submitResult}</span>}
                    </div>
                </div>
            )}

            {/* Show the result of the tool call */}
            {content != null && (
                <div className="flex flex-col gap-2 px-4 pt-2 text-xs border-t border-dashed">
                    <pre className="whitespace-pre-wrap">
                        {typeof content === 'string'
                            ? content
                            : JSON.stringify(content, null, 2)}
                    </pre>
                </div>
            )}
        </div>
    );
};

<MessagePrimitive.Content
    components={ {
        ...
        tools: {
            by_name: {
                runCommand: RunCommandTool,
            },
            Fallback: ToolFallback,
        },
    } }
/>

import { addElicitation, rejectElicitation } from './elicitation/elicitationStore';

...
async execute(dataStream) {
  let currentToolCallId: string | null = null;

  // Set up elicitation handler to respond to tool confirmation requests from the server
  await mcp.elicitation.onRequest(MCP_SERVER_NAME, async(request) => {
      const toolCallId = currentToolCallId;

      if (!toolCallId) {
          throw new Error('No tool call ID found');
      }

      const { promise, resolve, reject } = Promise.withResolvers<{
          action: 'accept' | 'decline' | 'cancel';
          content: {
              confirm: boolean;
          };
      }>();

      // Store the resolver globally for cross-request resolution
      addElicitation(toolCallId, resolve, reject);

      // Cancel the elicitation request after 60 seconds
      const timeout = setTimeout(() => {
          rejectElicitation(toolCallId, 'Timeout: elicitation cancelled');
      }, 60_000);

      dataStream.writeData({
          type: 'elicitation',
          toolCallId: currentToolCallId,
          message: request.message,
          requestedSchema: typeof request.requestedSchema?.toJSON === 'function'
              ? request.requestedSchema.toJSON()
              : request.requestedSchema,
      });

      return promise.catch((err) => {
          return {
              action: 'cancel',
              content: {
                  error: err.message,
              },
          };
      }).finally(() => {
          clearTimeout(timeout);
      });
  });

  // Run the agent and stream its response to the client
  const agentStream = await agent.stream(messages, {
      system,
      toolsets: {
          ...(await mcp.getToolsets()),
      },
      // Add any client-side tools
      clientTools: frontendTools(tools),
      onChunk: ({ chunk }) => {
          // Track the current tool call ID
          if ('toolCallId' in chunk) {
              currentToolCallId = chunk.toolCallId;
          }
      },
  });

  // Merge the agent's output into the HTTP data stream
  agentStream.mergeIntoDataStream(dataStream);
}

import { resolveElicitation } from './elicitationStore';

export async function POST(req: Request) {
    const { toolCallId, action, content } = await req.json();
    const success = resolveElicitation(toolCallId, { action, content });

    return new Response(JSON.stringify({ success }), { status: 200 });
}

type ElicitationResolver = (value: any) => void;
type ElicitationRejecter = (reason?: any) => void;

interface ElicitationEntry {
    resolve: ElicitationResolver;
    reject: ElicitationRejecter;
}

const elicitationMap = globalThis.elicitationMap || new Map<string, ElicitationEntry>();

if (!globalThis.elicitationMap) {
    globalThis.elicitationMap = elicitationMap;
}

export function addElicitation(toolCallId: string, resolve: ElicitationResolver, reject: ElicitationRejecter) {
    elicitationMap.set(toolCallId, { resolve, reject });
}

export function resolveElicitation(toolCallId: string, value: any) {
    const entry = elicitationMap.get(toolCallId);

    if (entry) {
        entry.resolve(value);
        elicitationMap.delete(toolCallId);

        return true;
    }

    return false;
}

export function rejectElicitation(toolCallId: string, reason?: any) {
    const entry = elicitationMap.get(toolCallId);

    if (entry) {
        entry.reject(reason);
        elicitationMap.delete(toolCallId);

        return true;
    }

    return false;
}