Letta MCP Server

Instructions

Implementation Reference

• src/tools/prompts/use-prompt.js:6-52 (handler)

  The main handler function for the 'use_prompt' tool. It retrieves a registered prompt by name from the promptRegistry, executes it with provided arguments, and returns the resulting messages in both text and structured content formats.

  export async function handleUsePrompt(server, args) {
      try {
          const { prompt_name, arguments: promptArgs } = args;
  
          if (!prompt_name) {
              throw new Error('Missing required parameter: prompt_name');
          }
  
          // Get the prompt from registry
          const prompt = promptRegistry.get(prompt_name);
          if (!prompt) {
              // List available prompts for helpful error
              const availablePrompts = Array.from(promptRegistry.keys());
              throw new Error(
                  `Prompt not found: ${prompt_name}. Available prompts: ${availablePrompts.join(', ')}`,
              );
          }
  
          // Execute the prompt handler
          const messages = await prompt.handler(promptArgs || {});
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify(
                          {
                              prompt_name,
                              description: prompt.description,
                              messages: messages.length,
                              preview: messages[0]?.content?.text?.substring(0, 200) + '...',
                          },
                          null,
                          2,
                      ),
                  },
              ],
              structuredContent: {
                  prompt_name,
                  description: prompt.description,
                  messages,
              },
          };
      } catch (error) {
          return server.createErrorResponse(error, 'Failed to execute prompt');
      }
  }

• src/tools/prompts/use-prompt.js:57-102 (schema)

  The tool definition object for 'use_prompt', including detailed inputSchema (requiring prompt_name and optional arguments) and outputSchema (including prompt details and messages).

  export const usePromptToolDefinition = {
      name: 'use_prompt',
      description:
          'Execute a registered prompt template. Use this to run wizards, workflows, and guided interactions.',
      inputSchema: {
          type: 'object',
          properties: {
              prompt_name: {
                  type: 'string',
                  description:
                      'Name of the prompt to execute (e.g., letta_agent_wizard, letta_memory_optimizer)',
              },
              arguments: {
                  type: 'object',
                  description: 'Arguments to pass to the prompt (depends on the specific prompt)',
                  additionalProperties: true,
              },
          },
          required: ['prompt_name'],
      },
      outputSchema: {
          type: 'object',
          properties: {
              prompt_name: {
                  type: 'string',
                  description: 'Name of the executed prompt',
              },
              description: {
                  type: 'string',
                  description: 'Description of the prompt',
              },
              messages: {
                  type: 'array',
                  items: {
                      type: 'object',
                      properties: {
                          role: { type: 'string' },
                          content: { type: 'object' },
                      },
                  },
                  description: 'Messages returned by the prompt',
              },
          },
          required: ['prompt_name', 'messages'],
      },
  };

• src/tools/index.js:219-220 (registration)

  Registration of the 'use_prompt' tool handler in the central switch statement within the CallToolRequestSchema handler, dispatching calls to handleUsePrompt.

  case 'use_prompt':
      return handleUsePrompt(server, request.params.arguments);

• src/tools/index.js:137-137 (registration)

  Inclusion of usePromptToolDefinition in the allTools array for registration with the MCP server.

  usePromptToolDefinition,

• src/tools/index.js:80-80 (registration)

  Import of the handler function and tool definition from the implementation file.

  import { handleUsePrompt, usePromptToolDefinition } from './prompts/use-prompt.js';