{"record":{"id":"3776f9f7e64b3cb3","repo":"mastra-ai/mastra","slug":"the-elicitation-key-is-now-nested-under-mcp-eli","errorCode":null,"errorMessage":"The \"elicitation\" key is now nested under \"mcp.elicitation\" in tool arguments","messagePattern":"The \"elicitation\" key is now nested under \"mcp\\.elicitation\" in tool arguments","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/server/server.ts","lineNumber":1138,"sourceCode":"              ...params,\n            },\n          });\n        };\n\n        const mcpOptions: MastraToolInvocationOptions = {\n          messages: [],\n          toolCallId: '',\n          requestContext: proxiedContext,\n          // Pass MCP-specific context through the mcp property\n          mcp: {\n            elicitation: sessionElicitation,\n            extra,\n            log: sessionLog,\n            progress: sessionProgress,\n          },\n          // @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\n          get elicitation() {\n            throw new Error(`The \"elicitation\" key is now nested under \"mcp.elicitation\" in tool arguments`);\n          },\n          get extra() {\n            throw new Error(`The \"extra\" key is now nested under \"mcp.extra\" in tool arguments`);\n          },\n        };\n\n        await this.enforceToolExecutionFGA(request.params.name, proxiedContext);\n\n        const result = await tool.execute(validation?.value ?? request.params.arguments ?? {}, mcpOptions);\n\n        const duration = Date.now() - startTime;\n\n        // Check if the tool builder returned a validation error (e.g. input failed Zod validation\n        // after passing the JSON Schema first-pass validation above)\n        if (isValidationError(result)) {\n          this.logger.warn(`CallTool: Tool '${request.params.name}' returned a validation error in ${duration}ms.`, {\n            error: result.message,\n          });","sourceCodeStart":1120,"sourceCodeEnd":1156,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/server/server.ts#L1120-L1156","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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`."],"exampleFix":"// before\nexecute: async (args, { elicitation }) => { ... }\n// after\nexecute: async (args, mcp) => { const elicitation = mcp.elicitation; ... }","handlingStrategy":"type-guard","validationCode":"// static check before deploy\ngrep -rn \"\\.elicitation\" src/tools/ && echo 'migrate to mcp.elicitation'","typeGuard":"function getElicitation(mcp: unknown): Elicitation | undefined { return !!mcp && typeof mcp === 'object' && 'elicitation' in mcp ? (mcp as any).elicitation : undefined; }","tryCatchPattern":"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; }","preventionTips":["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."],"tags":["mcp","migration","breaking-change","tools"],"backgroundTag":"api-migration-renamed-key","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}