Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/delete-agent.js:4-35 (handler)

  The handler function that executes the delete_agent tool logic: validates agent_id, calls the API to delete the agent, handles errors like 404, and returns a success response with the deleted agent_id.

  export async function handleDeleteAgent(server, args) {
      if (!args?.agent_id) {
          server.createErrorResponse('Missing required argument: agent_id');
      }
  
      try {
          const headers = server.getApiHeaders();
          const agentId = encodeURIComponent(args.agent_id);
  
          // Use the specific endpoint from the OpenAPI spec
          // Note: axios delete method typically doesn't have a body, config is the second arg
          await server.api.delete(`/agents/${agentId}`, { headers });
  
          // Successful deletion usually returns 200 or 204 with no body
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          agent_id: args.agent_id,
                      }),
                  },
              ],
          };
      } catch (error) {
          // Handle potential 404 if agent not found, or other API errors
          if (error.response && error.response.status === 404) {
              server.createErrorResponse(`Agent not found: ${args.agent_id}`);
          }
          server.createErrorResponse(error);
      }
  }

• src/tools/agents/delete-agent.js:40-54 (schema)

  The tool definition including name, description, and inputSchema for validating the agent_id parameter.

  export const deleteAgentDefinition = {
      name: 'delete_agent',
      description:
          'Delete a specific agent by ID. Use list_agents to find agent IDs. For bulk deletion, use bulk_delete_agents. WARNING: This action is permanent.',
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'The ID of the agent to delete',
              },
          },
          required: ['agent_id'],
      },
  };

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

  Registration of the delete_agent handler in the main tool call switch statement within registerToolHandlers.

  case 'delete_agent':
      return handleDeleteAgent(server, request.params.arguments);

• src/tools/output-schemas.js:439-447 (schema)

  Output schema definition for structured responses from the delete_agent tool.

  delete_agent: {
      type: 'object',
      properties: {
          success: { type: 'boolean' },
          agent_id: { type: 'string' },
          message: { type: 'string' },
      },
      required: ['success'],
  },

• src/tools/annotations.js:25-33 (helper)

  Annotations providing metadata about the delete_agent tool, including warnings about its dangerous nature and side effects.

  delete_agent: {
      title: 'Delete Agent',
      readOnly: false,
      requiresAuth: true,
      costLevel: 'low',
      executionTime: 'fast',
      sideEffects: 'Permanently removes agent and associated data',
      dangerous: true,
  },