Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/import-agent.js:11-79 (handler)

  Main handler function that implements the import_agent tool: reads a JSON file, sends it via FormData to /agents/import API endpoint, handles errors, and returns the imported agent state.

  export async function handleImportAgent(server, args) {
      if (!args?.file_path) {
          server.createErrorResponse('Missing required argument: file_path');
      }
  
      const filePath = path.resolve(args.file_path); // Resolve to absolute path
  
      // Check if file exists
      if (!fs.existsSync(filePath)) {
          server.createErrorResponse(`File not found at path: ${filePath}`);
      }
  
      try {
          const headers = server.getApiHeaders();
          // Remove content-type as axios will set it correctly for FormData
          delete headers['Content-Type'];
  
          const form = new FormData();
          form.append('file', fs.createReadStream(filePath), path.basename(filePath));
  
          // Construct query parameters for optional settings
          const params = {};
          if (args.append_copy_suffix !== undefined) {
              params.append_copy_suffix = args.append_copy_suffix;
          }
          if (args.override_existing_tools !== undefined) {
              params.override_existing_tools = args.override_existing_tools;
          }
          if (args.project_id) {
              params.project_id = args.project_id;
          }
  
          // Use the specific endpoint from the OpenAPI spec
          const response = await server.api.post('/agents/import', form, {
              headers: {
                  ...headers,
                  ...form.getHeaders(), // Let FormData set the Content-Type with boundary
              },
              params: params, // Add optional query parameters
          });
  
          const importedAgentState = response.data; // Assuming response.data is the new AgentState object
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          agent_id: importedAgentState.id,
                          agent: importedAgentState,
                      }),
                  },
              ],
          };
      } catch (error) {
          // Handle potential 422 for validation errors, or other API/file errors
          if (error.response) {
              if (error.response.status === 422) {
                  server.createErrorResponse(
                      `Validation error importing agent from ${args.file_path}: ${JSON.stringify(error.response.data)}`,
                  );
              }
          }
          logger.error('[import_agent] Error:', error.response?.data || error.message);
          server.createErrorResponse(
              `Failed to import agent from ${args.file_path}: ${error.message}`,
          );
      }
  }

• src/tools/agents/import-agent.js:84-114 (schema)

  Tool definition object including name, description, and inputSchema for validation of arguments to import_agent.

  export const importAgentDefinition = {
      name: 'import_agent',
      description:
          'Import a serialized agent JSON file and recreate the agent in the system. Use export_agent to create the JSON file, then modify_agent or attach_tool to customize the imported agent.',
      inputSchema: {
          type: 'object',
          properties: {
              file_path: {
                  type: 'string',
                  description: 'Path to the agent JSON file to import.',
              },
              append_copy_suffix: {
                  type: 'boolean',
                  description:
                      'Optional: If set to True, appends "_copy" to the end of the agent name. Defaults to true.',
                  default: true,
              },
              override_existing_tools: {
                  type: 'boolean',
                  description:
                      'Optional: If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Letta core tools cannot be updated. Defaults to true.',
                  default: true,
              },
              project_id: {
                  type: 'string',
                  description: 'Optional: The project ID to associate the uploaded agent with.',
              },
          },
          required: ['file_path'],
      },
  };

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

  Dispatch registration in the CallToolRequestSchema handler switch statement that routes 'import_agent' calls to the handleImportAgent function.

  case 'import_agent':
      return handleImportAgent(server, request.params.arguments);

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

  Inclusion of importAgentDefinition in the allTools array used for ListToolsRequestSchema to expose the tool.

  importAgentDefinition,

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

  Import statement that brings in the handler and definition from the implementation file.

  import { handleImportAgent, importAgentDefinition } from './agents/import-agent.js';