mastra-ai/mastra · error · Error

The "elicitation" key is now nested under "mcp.elicitation"

Error message

The "elicitation" key is now nested under "mcp.elicitation" in tool arguments

What it means

Tool execution context historically exposed `elicitation` and `extra` at the top level; they are now nested as `mcp.elicitation` and `mcp.extra`. To catch stale code, `registerHandlersOnServer` installs throwing getters on the proxied context so any access to the old `elicitation` key fails fast with this migration message.

Source

Thrown at packages/mcp/src/server/server.ts:1138

              ...params,
            },
          });
        };

        const mcpOptions: MastraToolInvocationOptions = {
          messages: [],
          toolCallId: '',
          requestContext: proxiedContext,
          // Pass MCP-specific context through the mcp property
          mcp: {
            elicitation: sessionElicitation,
            extra,
            log: sessionLog,
            progress: sessionProgress,
          },
          // @ts-expect-error this is to let people know that the elicitation and extra keys are now nested under mcp.elicitation and mcp.extra in tool arguments
          get elicitation() {
            throw new Error(`The "elicitation" key is now nested under "mcp.elicitation" in tool arguments`);
          },
          get extra() {
            throw new Error(`The "extra" key is now nested under "mcp.extra" in tool arguments`);
          },
        };

        await this.enforceToolExecutionFGA(request.params.name, proxiedContext);

        const result = await tool.execute(validation?.value ?? request.params.arguments ?? {}, mcpOptions);

        const duration = Date.now() - startTime;

        // Check if the tool builder returned a validation error (e.g. input failed Zod validation
        // after passing the JSON Schema first-pass validation above)
        if (isValidationError(result)) {
          this.logger.warn(`CallTool: Tool '${request.params.name}' returned a validation error in ${duration}ms.`, {
            error: result.message,
          });

View on GitHub (pinned to 75dd419e61)

Solutions

Replace `context.elicitation` / `args.elicitation` accesses with `mcp.elicitation` (the options object passed to execute).
Update destructuring like `({ elicitation }) => ...` to read from the nested key.
Search your tool implementations for `.elicitation` and migrate all occurrences to `mcp.elicitation`.

Example fix

// before
execute: async (args, { elicitation }) => { ... }
// after
execute: async (args, mcp) => { const elicitation = mcp.elicitation; ... }

Defensive patterns

Strategy: type-guard

Validate before calling

// static check before deploy
grep -rn "\.elicitation" src/tools/ && echo 'migrate to mcp.elicitation'

Type guard

function getElicitation(mcp: unknown): Elicitation | undefined { return !!mcp && typeof mcp === 'object' && 'elicitation' in mcp ? (mcp as any).elicitation : undefined; }

Try / catch

try { return await tool.execute(args, mcpOptions); } catch (e) { if (String(e?.message).includes('mcp.elicitation')) { throw new Error('Tool uses deprecated top-level elicitation; migrate to mcp.elicitation'); } throw e; }

Prevention

Read tool context only from the documented mcp.* nested keys.
Add a lint rule banning destructuring `elicitation` at the top level of execute args.
Run tool integration tests after any Mastra MCP version bump.

When it happens

Trigger: A tool's `execute` function (or anything it calls) reads `context.elicitation` from the second argument of tool.execute during an MCP `tools/call` on a server created by this MCPServer.

Common situations: Tools written against pre-nesting Mastra MCP examples, copied sample tools that destructure `{ elicitation }` from the options/context argument, or outdated tutorials after the API reshuffle.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/3776f9f7e64b3cb3. Report an issue: GitHub.