Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/clone-agent.js:12-130 (handler)

  Core handler function for clone_agent tool. Exports source agent config from API, changes name, saves to temporary JSON file, imports as new agent using FormData POST to /agents/import endpoint, handles errors and cleanup.

  export async function handleCloneAgent(server, args) {
      if (!args?.source_agent_id) {
          server.createErrorResponse('Missing required argument: source_agent_id');
      }
      if (!args?.new_agent_name) {
          server.createErrorResponse('Missing required argument: new_agent_name');
      }
  
      const sourceAgentId = args.source_agent_id;
      const newAgentName = args.new_agent_name;
      const overrideTools = args.override_existing_tools ?? true; // Default override
      const projectId = args.project_id; // Optional project ID for the new agent
  
      let tempFilePath = '';
  
      try {
          const headers = server.getApiHeaders();
          const encodedSourceAgentId = encodeURIComponent(sourceAgentId);
  
          // --- Step 1: Export the source agent ---
          logger.info(`Exporting source agent ${sourceAgentId}...`);
          const exportResponse = await server.api.get(`/agents/${encodedSourceAgentId}/export`, {
              headers,
          });
          const agentConfig = exportResponse.data;
  
          if (!agentConfig || typeof agentConfig !== 'object') {
              throw new Error('Received invalid data from agent export endpoint.');
          }
          logger.info(`Source agent ${sourceAgentId} exported successfully.`);
  
          // --- Step 2: Modify the configuration for the new agent ---
          agentConfig.name = newAgentName; // Set the new name
          // Optionally clear fields that shouldn't be copied or might cause conflicts
          // delete agentConfig.id; // ID will be assigned on import
          // delete agentConfig.created_at;
          // delete agentConfig.updated_at;
          // Consider if message history should be copied or cleared
          // agentConfig.messages = [];
          // agentConfig.message_ids = [];
  
          const agentJsonString = JSON.stringify(agentConfig, null, 2);
  
          // --- Step 3: Save modified config to a temporary file ---
          // Use os.tmpdir() which should work inside Docker if /tmp is writable
          tempFilePath = path.join(os.tmpdir(), `agent_clone_temp_${Date.now()}.json`);
          logger.info(`Saving temporary config to ${tempFilePath}...`);
          await fs.writeFile(tempFilePath, agentJsonString);
          logger.info('Temporary config saved.');
  
          // --- Step 4: Import the modified configuration ---
          logger.info(`Importing new agent '${newAgentName}' from ${tempFilePath}...`);
          const importHeaders = server.getApiHeaders();
          delete importHeaders['Content-Type']; // Let FormData set the correct header
  
          const form = new FormData();
          form.append('file', await fs.readFile(tempFilePath), path.basename(tempFilePath)); // Read file content for FormData
  
          const importParams = {
              append_copy_suffix: false, // We explicitly set the name, don't append suffix
              override_existing_tools: overrideTools,
          };
          if (projectId) {
              importParams.project_id = projectId;
          }
  
          const importResponse = await server.api.post('/agents/import', form, {
              headers: {
                  ...importHeaders,
                  ...form.getHeaders(),
              },
              params: importParams,
          });
  
          const importedAgentState = importResponse.data;
          logger.info(
              `Agent '${newAgentName}' imported successfully with ID: ${importedAgentState.id}`,
          );
  
          // --- Step 5: Cleanup temporary file ---
          await fs.unlink(tempFilePath);
          logger.info(`Cleaned up temporary file ${tempFilePath}.`);
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          new_agent: importedAgentState,
                      }),
                  },
              ],
          };
      } catch (error) {
          logger.error('Error:', error.response?.data || error.message);
          // Attempt cleanup even on error
          if (tempFilePath) {
              try {
                  await fs.unlink(tempFilePath);
                  logger.info(`Cleaned up temporary file ${tempFilePath} after error.`);
              } catch (cleanupError) {
                  logger.error(`Error cleaning up temporary file ${tempFilePath}:`, cleanupError);
              }
          }
  
          // Handle specific API errors
          if (error.response) {
              if (error.response.status === 404 && error.config.url.includes('/export')) {
                  server.createErrorResponse(`Source agent not found: ${sourceAgentId}`);
              }
              if (error.response.status === 422 && error.config.url.includes('/import')) {
                  server.createErrorResponse(
                      `Validation error importing cloned agent: ${JSON.stringify(error.response.data)}`,
                  );
              }
          }
          server.createErrorResponse(`Failed to clone agent ${sourceAgentId}: ${error.message}`);
      }
  }

• src/tools/agents/clone-agent.js:135-163 (schema)

  Tool definition including name, description, and input schema with required parameters source_agent_id and new_agent_name.

  export const cloneAgentDefinition = {
      name: 'clone_agent',
      description:
          'Creates a new agent by cloning the configuration of an existing agent. Use list_agents to find source agent ID. Alternative to export_agent + import_agent workflow. Modify the clone with modify_agent afterwards.',
      inputSchema: {
          type: 'object',
          properties: {
              source_agent_id: {
                  type: 'string',
                  description: 'The ID of the agent to clone.',
              },
              new_agent_name: {
                  type: 'string',
                  description: 'The name for the new cloned agent.',
              },
              override_existing_tools: {
                  type: 'boolean',
                  description:
                      'Optional: If set to True, existing tools can get their source code overwritten by the tool definitions from the source agent. Defaults to true.',
                  default: true,
              },
              project_id: {
                  type: 'string',
                  description: 'Optional: The project ID to associate the new cloned agent with.',
              },
          },
          required: ['source_agent_id', 'new_agent_name'],
      },
  };

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

  Registration of the handler in the central tool dispatch switch statement within registerToolHandlers function.

  case 'clone_agent':
      return handleCloneAgent(server, request.params.arguments);

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

  Import of the handler function and tool definition from clone-agent.js.

  import { handleCloneAgent, cloneAgentDefinition } from './agents/clone-agent.js';

• src/tools/output-schemas.js:327-336 (schema)

  Output schema definition for structured responses from clone_agent tool.

  clone_agent: {
      type: 'object',
      properties: {
          success: { type: 'boolean' },
          original_agent_id: { type: 'string' },
          new_agent_id: { type: 'string' },
          new_agent_name: { type: 'string' },
      },
      required: ['success', 'new_agent_id'],
  },