Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/prompt-agent.js:8-115 (handler)

  Main handler function for the prompt_agent tool. Validates arguments, fetches agent info, sends message to agent via Letta API /messages/stream endpoint, parses SSE response, and returns structured response with agent details and response text.

  export async function handlePromptAgent(server, args) {
      try {
          // Validate arguments
          if (!args.agent_id || !args.message) {
              throw new Error('Missing required arguments: agent_id and message');
          }
  
          // Headers for API requests
          const headers = server.getApiHeaders();
  
          // First, check if the agent exists
          const agentInfoResponse = await server.api.get(`/agents/${args.agent_id}`, { headers });
          const agentName = agentInfoResponse.data.name;
  
          // Send message to agent using the messages/stream endpoint
          const response = await server.api.post(
              `/agents/${args.agent_id}/messages/stream`,
              {
                  messages: [
                      {
                          role: 'user',
                          content: args.message,
                      },
                  ],
                  stream_steps: false,
                  stream_tokens: false,
              },
              {
                  headers,
                  responseType: 'text',
              },
          );
  
          // Extract the response
          let responseText = '';
          try {
              // The response is in Server-Sent Events (SSE) format
              if (typeof response.data === 'string') {
                  // Find lines that start with "data: "
                  const dataLines = response.data
                      .split('\n')
                      .filter((line) => line.trim().startsWith('data: '));
  
                  // Process each data line
                  const messages = [];
                  for (const line of dataLines) {
                      try {
                          // Extract the JSON part after "data: "
                          const jsonStr = line.substring(6);
                          const eventData = JSON.parse(jsonStr);
  
                          // Extract the message content based on message type
                          if (eventData.message_type === 'assistant_message' && eventData.content) {
                              // This is the main response message
                              responseText = eventData.content;
                              break;
                          } else if (
                              eventData.message_type === 'reasoning_message' &&
                              eventData.reasoning
                          ) {
                              // This is the reasoning message (agent's thought process)
                              messages.push(`[Reasoning]: ${eventData.reasoning}`);
                          } else if (eventData.delta && eventData.delta.content) {
                              // This is a streaming delta update
                              messages.push(eventData.delta.content);
                          }
                      } catch (jsonError) {
                          logger.error('Error parsing SSE JSON:', jsonError);
                          // If we can't parse the JSON, just add the raw line
                          messages.push(line.substring(6));
                      }
                  }
  
                  // If we didn't find a specific assistant message, join all messages
                  if (!responseText && messages.length > 0) {
                      responseText = messages.join('\n');
                  }
  
                  // If we still don't have a response, use the raw data
                  if (!responseText) {
                      responseText = "Received response but couldn't extract message content";
                  }
              } else if (response.data) {
                  // Handle non-string response (unlikely with SSE)
                  responseText = JSON.stringify(response.data);
              }
          } catch (error) {
              logger.error('Error parsing response:', error);
              responseText = 'Error parsing agent response';
          }
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          agent_id: args.agent_id,
                          agent_name: agentName,
                          message: args.message,
                          response: responseText,
                      }),
                  },
              ],
          };
      } catch (error) {
          server.createErrorResponse(error);
      }
  }

• src/tools/agents/prompt-agent.js:120-139 (schema)

  Tool schema definition specifying name, description, and input schema requiring agent_id and message.

  export const promptAgentToolDefinition = {
      name: 'prompt_agent',
      description:
          'Send a message to an agent and get a response. Ensure the agent has necessary tools attached (see attach_tool) first. Use list_agents to find agent IDs.',
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'ID of the agent to prompt',
              },
              message: {
                  type: 'string',
                  description: 'Message to send to the agent',
              },
          },
          required: ['agent_id', 'message'],
      },
  };

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

  Registration of the prompt_agent handler in the main tool call switch statement.

  case 'prompt_agent':
      return handlePromptAgent(server, request.params.arguments);

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

  Import of the handlePromptAgent function and promptAgentToolDefinition from the implementation file.

  import { handlePromptAgent, promptAgentToolDefinition } from './agents/prompt-agent.js';

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

  Inclusion of promptAgentToolDefinition in the allTools array for registration.

  listAgentsToolDefinition,
  promptAgentToolDefinition,