@mastra/mcp-docs-server 0.13.2-alpha.1 → 0.13.2-alpha.2

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -308,6 +308,145 @@ const { prompt, messages } = await mcpClient.prompts.get({
 });
 ```
 
+### `elicitation` Property
+
+The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Set up elicitation handler
+mcpClient.elicitation.onRequest('serverName', async (request) => {
+  // Handle elicitation request from server
+  console.log('Server requests:', request.message);
+  console.log('Schema:', request.requestedSchema);
+  
+  // Return user response
+  return {
+    action: 'accept',
+    content: { name: 'John Doe', email: 'john@example.com' }
+  };
+});
+```
+
+#### `elicitation.onRequest(serverName: string, handler: ElicitationHandler)`
+
+Sets up a handler function that will be called when any connected MCP server sends an elicitation request. The handler receives the request and must return a response.
+
+**ElicitationHandler Function:**
+
+The handler function receives a request object with:
+- `message`: A human-readable message describing what information is needed
+- `requestedSchema`: A JSON schema defining the structure of the expected response
+
+The handler must return an `ElicitResult` with:
+- `action`: One of `'accept'`, `'reject'`, or `'cancel'`
+- `content`: The user's data (only when action is `'accept'`)
+
+**Example:**
+
+```typescript
+mcpClient.elicitation.onRequest('serverName', async (request) => {
+  console.log(`Server requests: ${request.message}`);
+  
+  // Example: Simple user input collection
+  if (request.requestedSchema.properties.name) {
+    // Simulate user accepting and providing data
+    return {
+      action: 'accept',
+      content: {
+        name: 'Alice Smith',
+        email: 'alice@example.com'
+      }
+    };
+  }
+  
+  // Simulate user rejecting the request
+  return { action: 'reject' };
+});
+```
+
+**Complete Interactive Example:**
+
+```typescript
+import { MCPClient } from '@mastra/mcp';
+import { createInterface } from 'readline';
+
+const readline = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function askQuestion(question: string): Promise<string> {
+  return new Promise(resolve => {
+    readline.question(question, answer => resolve(answer.trim()));
+  });
+}
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL('http://localhost:3000/mcp'),
+    },
+  },
+});
+
+// Set up interactive elicitation handler
+await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+  console.log(`\n📋 Server Request: ${request.message}`);
+  console.log('Required information:');
+  
+  const schema = request.requestedSchema;
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  const content: Record<string, any> = {};
+  
+  // Collect input for each field
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    const field = fieldSchema as any;
+    const isRequired = required.includes(fieldName);
+    
+    let prompt = `${field.title || fieldName}`;
+    if (field.description) prompt += ` (${field.description})`;
+    if (isRequired) prompt += ' *required*';
+    prompt += ': ';
+    
+    const answer = await askQuestion(prompt);
+    
+    // Handle cancellation
+    if (answer.toLowerCase() === 'cancel') {
+      return { action: 'cancel' };
+    }
+    
+    // Validate required fields
+    if (answer === '' && isRequired) {
+      console.log(`❌ ${fieldName} is required`);
+      return { action: 'reject' };
+    }
+    
+    if (answer !== '') {
+      content[fieldName] = answer;
+    }
+  }
+  
+  // Confirm submission
+  console.log('\n📝 You provided:');
+  console.log(JSON.stringify(content, null, 2));
+  
+  const confirm = await askQuestion('\nSubmit this information? (yes/no/cancel): ');
+  
+  if (confirm.toLowerCase() === 'yes' || confirm.toLowerCase() === 'y') {
+    return { action: 'accept', content };
+  } else if (confirm.toLowerCase() === 'cancel') {
+    return { action: 'cancel' };
+  } else {
+    return { action: 'reject' };
+  }
+});
+```
+
 #### `prompts.list()`
 
 Retrieves all available prompts from all connected MCP servers, grouped by server name.
@@ -373,6 +512,111 @@ mcpClient.prompts.onListChanged("myWeatherServer", () => {
 });
 ```
 
+## Elicitation
+
+Elicitation is a feature that allows MCP servers to request structured information from users. When a server needs additional data, it can send an elicitation request that the client handles by prompting the user. A common example is during a tool call.
+
+### How Elicitation Works
+
+1. **Server Request**: An MCP server tool calls `server.elicitation.sendRequest()` with a message and schema
+2. **Client Handler**: Your elicitation handler function is called with the request
+3. **User Interaction**: Your handler collects user input (via UI, CLI, etc.)
+4. **Response**: Your handler returns the user's response (accept/reject/cancel)
+5. **Tool Continuation**: The server tool receives the response and continues execution
+
+### Setting Up Elicitation
+
+You must set up an elicitation handler before tools that use elicitation are called:
+
+```typescript
+import { MCPClient } from '@mastra/mcp';
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL('http://localhost:3000/mcp'),
+    },
+  },
+});
+
+// Set up elicitation handler
+mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+  // Handle the server's request for user input
+  console.log(`Server needs: ${request.message}`);
+  
+  // Your logic to collect user input
+  const userData = await collectUserInput(request.requestedSchema);
+  
+  return {
+    action: 'accept',
+    content: userData
+  };
+});
+```
+
+### Response Types
+
+Your elicitation handler must return one of three response types:
+
+- **Accept**: User provided data and confirmed submission
+  ```typescript
+  return {
+    action: 'accept',
+    content: { name: 'John Doe', email: 'john@example.com' }
+  };
+  ```
+
+- **Reject**: User explicitly declined to provide the information
+  ```typescript
+  return { action: 'reject' };
+  ```
+
+- **Cancel**: User dismissed or cancelled the request
+  ```typescript
+  return { action: 'cancel' };
+  ```
+
+### Schema-Based Input Collection
+
+The `requestedSchema` provides structure for the data the server needs:
+
+```typescript
+await mcpClient.elicitation.onRequest('interactiveServer', async (request) => {
+  const { properties, required = [] } = request.requestedSchema;
+  const content: Record<string, any> = {};
+  
+  for (const [fieldName, fieldSchema] of Object.entries(properties || {})) {
+    const field = fieldSchema as any;
+    const isRequired = required.includes(fieldName);
+    
+    // Collect input based on field type and requirements
+    const value = await promptUser({
+      name: fieldName,
+      title: field.title,
+      description: field.description,
+      type: field.type,
+      required: isRequired,
+      format: field.format,
+      enum: field.enum,
+    });
+    
+    if (value !== null) {
+      content[fieldName] = value;
+    }
+  }
+  
+  return { action: 'accept', content };
+});
+```
+
+### Best Practices
+
+- **Always handle elicitation**: Set up your handler before calling tools that might use elicitation
+- **Validate input**: Check that required fields are provided
+- **Respect user choice**: Handle reject and cancel responses gracefully
+- **Clear UI**: Make it obvious what information is being requested and why
+- **Security**: Never auto-accept requests for sensitive information
+
 ## Examples
 
 ### Static Tool Configuration

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -833,6 +833,192 @@ For practical examples of setting up and deploying an MCPServer, see the [Deploy
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
+## Elicitation
+
+### What is Elicitation?
+
+Elicitation is a feature in the Model Context Protocol (MCP) that allows servers to request structured information from users. This enables interactive workflows where servers can collect additional data dynamically.
+
+The `MCPServer` class automatically includes elicitation capabilities. Tools receive an `options` parameter in their `execute` function that includes an `elicitation.sendRequest()` method for requesting user input.
+
+### Tool Execution Signature
+
+When tools are executed within an MCP server context, they receive an additional `options` parameter:
+
+```typescript
+execute: async ({ context }, options) => {
+  // context contains the tool's input parameters
+  // options contains server capabilities like elicitation
+  
+  const result = await options.elicitation.sendRequest({
+    message: "Please provide information",
+    requestedSchema: { /* schema */ }
+  });
+  
+  return result;
+}
+```
+
+### How Elicitation Works
+
+A common use case is during tool execution. When a tool needs user input, it can use the elicitation functionality provided through the tool's execution options:
+
+1. The tool calls `options.elicitation.sendRequest()` with a message and schema
+2. The request is sent to the connected MCP client
+3. The client presents the request to the user (via UI, command line, etc.)
+4. The user provides input, rejects, or cancels the request
+5. The client sends the response back to the server
+6. The tool receives the response and continues execution
+
+### Using Elicitation in Tools
+
+Here's an example of a tool that uses elicitation to collect user contact information:
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const server = new MCPServer({
+  name: "Interactive Server",
+  version: "1.0.0",
+  tools: {
+    collectContactInfo: createTool({
+      id: "collectContactInfo",
+      description: "Collects user contact information through elicitation",
+      inputSchema: z.object({
+        reason: z.string().optional().describe("Reason for collecting contact info"),
+      }),
+      execute: async ({ context }, options) => {
+        const { reason } = context;
+
+        try {
+          // Request user input via elicitation through the options parameter
+          const result = await options.elicitation.sendRequest({
+            message: reason 
+              ? `Please provide your contact information. ${reason}`
+              : 'Please provide your contact information',
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  title: 'Full Name',
+                  description: 'Your full name',
+                },
+                email: {
+                  type: 'string',
+                  title: 'Email Address', 
+                  description: 'Your email address',
+                  format: 'email',
+                },
+                phone: {
+                  type: 'string',
+                  title: 'Phone Number',
+                  description: 'Your phone number (optional)',
+                },
+              },
+              required: ['name', 'email'],
+            },
+          });
+
+          // Handle the user's response
+          if (result.action === 'accept') {
+            return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
+          } else if (result.action === 'reject') {
+            return 'Contact information collection was declined by the user.';
+          } else {
+            return 'Contact information collection was cancelled by the user.';
+          }
+        } catch (error) {
+          return `Error collecting contact information: ${error}`;
+        }
+      },
+    }),
+  },
+});
+```
+
+### Elicitation Request Schema
+
+The `requestedSchema` must be a flat object with primitive properties only. Supported types include:
+
+- **String**: `{ type: 'string', title: 'Display Name', description: 'Help text' }`
+- **Number**: `{ type: 'number', minimum: 0, maximum: 100 }`
+- **Boolean**: `{ type: 'boolean', default: false }`
+- **Enum**: `{ type: 'string', enum: ['option1', 'option2'] }`
+
+Example schema:
+
+```typescript
+{
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      title: 'Full Name',
+      description: 'Your complete name',
+    },
+    age: {
+      type: 'number',
+      title: 'Age',
+      minimum: 18,
+      maximum: 120,
+    },
+    newsletter: {
+      type: 'boolean',
+      title: 'Subscribe to Newsletter',
+      default: false,
+    },
+  },
+  required: ['name'],
+}
+```
+
+### Response Actions
+
+Users can respond to elicitation requests in three ways:
+
+1. **Accept** (`action: 'accept'`): User provided data and confirmed submission
+   - Contains `content` field with the submitted data
+2. **Reject** (`action: 'reject'`): User explicitly declined to provide information
+   - No content field
+3. **Cancel** (`action: 'cancel'`): User dismissed the request without deciding
+   - No content field
+
+Tools should handle all three response types appropriately.
+
+### Security Considerations
+
+- **Never request sensitive information** like passwords, SSNs, or credit card numbers
+- Validate all user input against the provided schema
+- Handle rejection and cancellation gracefully
+- Provide clear reasons for data collection
+- Respect user privacy and preferences
+
+### Tool Execution API
+
+The elicitation functionality is available through the `options` parameter in tool execution:
+
+```typescript
+// Within a tool's execute function
+options.elicitation.sendRequest({
+  message: string,           // Message to display to user
+  requestedSchema: object    // JSON schema defining expected response structure
+}): Promise<ElicitResult>
+```
+
+Note that elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). This means that when multiple clients are connected to the same server, elicitation requests are routed to the correct client session that initiated the tool execution.
+
+The `ElicitResult` type:
+
+```typescript
+type ElicitResult = {
+  action: 'accept' | 'reject' | 'cancel';
+  content?: any; // Only present when action is 'accept'
+}
+```
+
 ## Related Information
 
 - For connecting to MCP servers in Mastra, see the [MCPClient documentation](./mcp-client).

package/.docs/raw/reference/workflows/create-run.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## Parameters

package/.docs/raw/reference/workflows/resume.mdx

@@ -10,7 +10,7 @@ The `.resume()` method resumes a suspended workflow run with new data, allowing
 ## Usage
 
 ```typescript
-const run = counterWorkflow.createRun();
+const run = await counterWorkflow.createRunAsync();
 const result = await run.start({ inputData: { startValue: 0 } });
 
 if (result.status === "suspended") {

package/.docs/raw/reference/workflows/start.mdx

@@ -10,7 +10,7 @@ The `.start()` method starts a workflow run with input data, allowing you to exe
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Start the workflow with input data
 const result = await run.start({

package/.docs/raw/reference/workflows/stream.mdx

@@ -10,7 +10,7 @@ The `.stream()` method allows you to monitor the execution of a workflow run, pr
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a stream to monitor execution
 const result = run.stream({ inputData: {...} });

package/.docs/raw/reference/workflows/watch.mdx

@@ -10,7 +10,7 @@ The `.watch()` method allows you to monitor the execution of a workflow run, pro
 ## Usage
 
 ```typescript
-const run = myWorkflow.createRun();
+const run = await myWorkflow.createRunAsync();
 
 // Add a watcher to monitor execution
 run.watch(event => {

package/.docs/raw/reference/workflows/workflow.mdx

@@ -31,7 +31,7 @@ const mastra = new Mastra({
   },
 });
 
-const run = mastra.getWorkflow("myWorkflow").createRun();
+const run = await mastra.getWorkflow("myWorkflow").createRunAsync();
 ```
 
 ## API Reference
@@ -99,7 +99,11 @@ Validates and finalizes the workflow configuration. Must be called after adding
 
 #### `createRun()`
 
-Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+Deprecated. Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+
+#### `createRunAsync()`
+
+Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID. Stores a pending workflow run snapshot into storage.
 
 #### `execute()`
 

package/.docs/raw/workflows/control-flow.mdx

@@ -126,6 +126,47 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
+### Early exit
+
+You can bail out of a workflow execution successfully by calling `bail()` in a step. This returns whatever payload is passed to the `bail()` function as the result of the workflow.
+
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail, inputData }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
+
+Unsuccessful bails happen through throwing an error in the step.
+
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail, inputData }) => {
+    throw new Error('bailed');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .commit();
+```
 #### Example Run Instance
 
 The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
@@ -133,7 +174,7 @@ The following example demonstrates how to start a run with multiple inputs. Each
 ```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.start({
   inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]

package/.docs/raw/workflows/overview.mdx

@@ -157,12 +157,12 @@ With the Mastra Dev Server running you can run the workflow from the Mastra Play
 
 #### Command line
 
-Create a run instance of any Mastra workflow using `createRun` and `start`:
+Create a run instance of any Mastra workflow using `createRunAsync` and `start`:
 
 ```typescript {3,5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.start({
   inputData: {
@@ -172,7 +172,7 @@ const result = await run.start({
 
 console.log(JSON.stringify(result, null, 2));
 ```
-> see [createRun](/reference/workflows/create-run) and [start](/reference/workflows/start) for more information.
+> see [createRunAsync](/reference/workflows/create-run-async) and [start](/reference/workflows/start) for more information.
 
 To trigger this workflow, run the following:
 
@@ -182,6 +182,74 @@ npx tsx src/test-workflow.ts
 
 </Steps>
 
+#### Run Workflow Results
+
+The result of running a workflow using either `start()` or `resume()` will look like one of the following, depending on the outcome.
+
+##### Status success
+
+```json
+{
+  "status": "success",
+  "steps": {
+    // ...
+    "step-1": {
+      // ...
+      "status": "success",
+    }
+  },
+  "result": {
+    "output": "London + step-1"
+  }
+}
+```
+
+- **status**: Shows the final state of the workflow execution, either: `success`, `suspended`, or `error`
+- **steps**: Lists each step in the workflow, including inputs and outputs
+- **status**: Shows the outcome of each individual step
+- **result**: Includes the final output of the workflow, typed according to the `outputSchema`
+
+
+##### Status suspended
+
+```json
+{
+  "status": "suspended",
+  "steps": {
+    // ...
+    "step-1": {
+      // ...
+      "status": "suspended",
+    }
+  },
+  "suspended": [
+    [
+      "step-1"
+    ]
+  ]
+}
+```
+
+- **suspended**: An optional array listing any steps currently awaiting input before continuing
+
+##### Status failed
+
+```json
+{
+  "status": "failed",
+  "steps": {
+    // ...
+    "step-1": {
+      // ...
+      "status": "failed",
+      "error": "Test error",
+    }
+  },
+  "error": "Test error"
+}
+```
+- **error**: An optional field that includes the error message if the workflow fails
+
 ### Stream Workflow
 
 Similar to the run method shown above, workflows can also be streamed:
@@ -189,7 +257,7 @@ Similar to the run method shown above, workflows can also be streamed:
 ```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 const result = await run.stream({
   inputData: {
@@ -211,7 +279,7 @@ A workflow can also be watched, allowing you to inspect each event that is emitt
 ```typescript {5} filename="src/test-workflow.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
-const run = mastra.getWorkflow("testWorkflow").createRun();
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
 run.watch((event) => {
   console.log(event);