Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/bulk-delete-agents.js:9-110 (handler)

  Core handler function that executes the bulk_delete_agents tool: validates input, lists matching agents using filters or IDs, deletes each via DELETE /agents/{id}, reports success/error per agent with summary.
  export async function handleBulkDeleteAgents(server, args) { // Require at least one filter criteria to prevent accidental mass deletion if (!args?.agent_name_filter && !args?.agent_tag_filter && !args?.agent_ids) { server.createErrorResponse( 'Missing required argument: Provide agent_ids, agent_name_filter, or agent_tag_filter.', ); } const nameFilter = args.agent_name_filter; const tagFilter = args.agent_tag_filter; const specificAgentIds = args.agent_ids; // Allow deleting a specific list of IDs const results = []; let agentsToDelete = []; try { const headers = server.getApiHeaders(); // Step 1: Identify agents to delete if (specificAgentIds && Array.isArray(specificAgentIds) && specificAgentIds.length > 0) { // If a list of IDs is provided, use that directly logger.info(`Received specific list of ${specificAgentIds.length} agents to delete.`); // We need agent objects (at least with 'id' and 'name') for consistent reporting // Fetch details for each ID or use list_agents with multiple ID filter if supported // For simplicity, we'll just use the IDs for deletion and report only IDs agentsToDelete = specificAgentIds.map((id) => ({ id: id, name: `ID: ${id}` })); // Create placeholder objects } else { // Otherwise, list agents based on filters logger.info(`Listing agents with filter: name='${nameFilter}', tags='${tagFilter}'...`); const listParams = {}; if (nameFilter) listParams.name = nameFilter; if (tagFilter) listParams.tags = tagFilter; // Adjust if API uses different param name const listResponse = await server.api.get('/agents/', { headers, params: listParams }); agentsToDelete = listResponse.data; // Assuming response.data is an array of AgentState objects if (!Array.isArray(agentsToDelete) || agentsToDelete.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ message: 'No agents found matching the specified filter.', results: [], }), }, ], }; } logger.info(`Found ${agentsToDelete.length} agents to delete.`); } // Step 2: Iterate and delete each agent for (const agent of agentsToDelete) { const agentId = agent.id; const encodedAgentId = encodeURIComponent(agentId); try { logger.info(`Deleting agent ${agentId} (${agent.name})...`); // Use the specific endpoint from the OpenAPI spec await server.api.delete(`/agents/${encodedAgentId}`, { headers }); results.push({ agent_id: agentId, name: agent.name, status: 'success' }); logger.info(`Successfully deleted agent ${agentId}.`); } catch (deleteError) { let errorMessage = `Failed to delete agent ${agentId} (${agent.name}): ${deleteError.message}`; if (deleteError.response) { errorMessage += ` (Status: ${deleteError.response.status}, Data: ${JSON.stringify(deleteError.response.data)})`; } logger.error(errorMessage); results.push({ agent_id: agentId, name: agent.name, status: 'error', error: errorMessage, }); } } // Step 3: Return summary of results const successCount = results.filter((r) => r.status === 'success').length; const errorCount = results.filter((r) => r.status === 'error').length; return { content: [ { type: 'text', text: JSON.stringify({ summary: { total_agents: agentsToDelete.length, success_count: successCount, error_count: errorCount, }, results: results, }), }, ], }; } catch (error) { // Handle errors during the list_agents call or unexpected issues logger.error('Error:', error.response?.data || error.message); server.createErrorResponse(`Failed during bulk delete operation: ${error.message}`); } }
• src/tools/agents/bulk-delete-agents.js:115-142 (schema)

  Tool definition including name, description, and inputSchema for validation of arguments: agent_ids, agent_name_filter, agent_tag_filter.
  export const bulkDeleteAgentsDefinition = { name: 'bulk_delete_agents', description: 'Deletes multiple agents based on filter criteria (name or tags) or a specific list of IDs. Use list_agents first to identify agents to delete. WARNING: This action is permanent.', inputSchema: { type: 'object', properties: { agent_ids: { type: 'array', items: { type: 'string' }, description: 'Optional: A specific list of agent IDs to delete.', }, agent_name_filter: { type: 'string', description: 'Optional: Filter agents to delete by name (exact match or substring, depending on API).', }, agent_tag_filter: { type: 'string', description: 'Optional: Filter agents to delete by tag(s). Provide a single tag or comma-separated list.', }, // Could add more filters like project_id if needed }, // Custom validation in the handler ensures at least one argument is provided required: [], }, };
• src/tools/index.js:213-214 (registration)

  Handler dispatch registration: switch case in CallToolRequestSchema handler that routes 'bulk_delete_agents' calls to handleBulkDeleteAgents.
  case 'bulk_delete_agents': return handleBulkDeleteAgents(server, request.params.arguments);
• src/tools/index.js:134-134 (registration)

  Tool definition registration: inclusion of bulkDeleteAgentsDefinition in the allTools array used for ListToolsRequestSchema response.
  bulkDeleteAgentsDefinition,
• src/tools/output-schemas.js:363-384 (schema)

  Output schema defining structured response format for bulk_delete_agents: summary counts and per-agent results.
  bulk_delete_agents: { type: 'object', properties: { total_agents: { type: 'integer' }, deleted: { type: 'integer' }, failed: { type: 'integer' }, results: { type: 'array', items: { type: 'object', properties: { agent_id: { type: 'string' }, agent_name: { type: 'string' }, success: { type: 'boolean' }, error: { type: 'string' }, }, required: ['agent_id', 'success'], }, }, }, required: ['total_agents', 'deleted'], },