Letta MCP Server

Instructions

Implementation Reference

• src/tools/tools/bulk-attach-tool.js:10-113 (handler)

  Primary handler function implementing the bulk tool attachment logic: validates inputs, lists matching agents, attaches tool to each via API, handles errors per agent, returns summary with results.
  export async function handleBulkAttachToolToAgents(server, args) { if (!args?.tool_id) { server.createErrorResponse('Missing required argument: tool_id'); } // Require at least one filter criteria if (!args?.agent_name_filter && !args?.agent_tag_filter) { server.createErrorResponse( 'Missing required argument: Provide either agent_name_filter or agent_tag_filter.', ); } const toolId = args.tool_id; const nameFilter = args.agent_name_filter; const tagFilter = args.agent_tag_filter; // Assuming API supports tag filtering for list_agents const results = []; let agentsToProcess = []; try { const headers = server.getApiHeaders(); // Step 1: List agents based on filter criteria logger.info( `[bulk_attach_tool] Listing agents with filter: name='${nameFilter}', tags='${tagFilter}'...`, ); const listParams = {}; if (nameFilter) listParams.name = nameFilter; // Assuming API uses 'name' for filtering if (tagFilter) listParams.tags = tagFilter; // Assuming API uses 'tags' (might need adjustment based on actual API) const listResponse = await server.api.get('/agents/', { headers, params: listParams }); agentsToProcess = listResponse.data; // Assuming response.data is an array of AgentState objects if (!Array.isArray(agentsToProcess) || agentsToProcess.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ message: 'No agents found matching the specified filter.', results: [], }), }, ], }; } logger.info(`[bulk_attach_tool] Found ${agentsToProcess.length} agents to process.`); // Step 2: Iterate and attach tool to each agent const encodedToolId = encodeURIComponent(toolId); for (const agent of agentsToProcess) { const agentId = agent.id; const encodedAgentId = encodeURIComponent(agentId); try { logger.info(`[bulk_attach_tool] Attaching tool ${toolId} to agent ${agentId}...`); // Use the specific endpoint from the OpenAPI spec await server.api.patch( `/agents/${encodedAgentId}/tools/attach/${encodedToolId}`, {}, { headers }, ); // PATCH often has empty body for attach/detach results.push({ agent_id: agentId, name: agent.name, status: 'success' }); logger.info( `[bulk_attach_tool] Successfully attached tool ${toolId} to agent ${agentId}.`, ); } catch (attachError) { let errorMessage = `Failed to attach tool ${toolId} to agent ${agentId}: ${attachError.message}`; if (attachError.response) { errorMessage += ` (Status: ${attachError.response.status}, Data: ${JSON.stringify(attachError.response.data)})`; } logger.error(`[bulk_attach_tool] ${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: agentsToProcess.length, success_count: successCount, error_count: errorCount, }, results: results, }), }, ], }; } catch (error) { // Handle errors during the list_agents call or unexpected issues logger.error('[bulk_attach_tool] Error:', error.response?.data || error.message); server.createErrorResponse(`Failed during bulk attach operation: ${error.message}`); } }
• src/tools/tools/bulk-attach-tool.js:118-146 (schema)

  Input schema and tool definition for bulk_attach_tool_to_agents, defining parameters like tool_id, agent_name_filter, agent_tag_filter.
  export const bulkAttachToolDefinition = { name: 'bulk_attach_tool_to_agents', description: 'Attaches a specified tool to multiple agents based on filter criteria (name or tags). Use list_agents to find agents and list_mcp_tools_by_server or upload_tool to get tool IDs.', inputSchema: { type: 'object', properties: { tool_id: { type: 'string', description: 'The ID of the tool to attach.', }, agent_name_filter: { type: 'string', description: 'Optional: Filter agents by name (exact match or substring, depending on API).', }, agent_tag_filter: { // Assuming API accepts comma-separated string or array for tags type: 'string', // or 'array' with items: { type: 'string' } description: 'Optional: Filter agents by tag(s). Provide a single tag or comma-separated list.', }, // Could add more filters like project_id if needed and supported by list_agents API }, required: ['tool_id'], // Custom validation could ensure at least one filter is present, but basic schema doesn't enforce this easily. // The handler function checks for this. }, };
• src/tools/output-schemas.js:339-361 (schema)

  Output schema defining the expected structured response: summary counts and per-agent results.
  bulk_attach_tool_to_agents: { type: 'object', properties: { tool_id: { type: 'string' }, total_agents: { type: 'integer' }, successful_attachments: { type: 'integer' }, failed_attachments: { 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: ['tool_id', 'total_agents', 'successful_attachments'], },
• src/tools/index.js:209-210 (registration)

  Dispatch registration in the main tool call handler switch statement, routing calls to the handler function.
  case 'bulk_attach_tool_to_agents': return handleBulkAttachToolToAgents(server, request.params.arguments);
• src/tools/index.js:55-57 (registration)

  Import of the handler function and tool definition.
  handleBulkAttachToolToAgents, bulkAttachToolDefinition, } from './tools/bulk-attach-tool.js';
• src/tools/index.js:132-132 (registration)

  Inclusion of the tool definition in the allTools array for registration with the MCP server.
  bulkAttachToolDefinition,