Letta MCP Server

Instructions

Implementation Reference

• src/tools/agents/modify-agent.js:4-45 (handler)

  The core handler function that executes the tool logic: validates arguments, makes a PATCH request to the /agents/{id} endpoint, and returns the updated agent state.

  export async function handleModifyAgent(server, args) {
      if (!args?.agent_id) {
          server.createErrorResponse('Missing required argument: agent_id');
      }
      if (!args?.update_data) {
          server.createErrorResponse('Missing required argument: update_data');
      }
  
      try {
          const headers = server.getApiHeaders();
          const agentId = encodeURIComponent(args.agent_id);
          const updatePayload = args.update_data; // This should conform to the UpdateAgent schema
  
          // Use the specific endpoint from the OpenAPI spec
          const response = await server.api.patch(`/agents/${agentId}`, updatePayload, { headers });
          const updatedAgentState = response.data; // Assuming response.data is the updated AgentState object
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          agent: updatedAgentState,
                      }),
                  },
              ],
          };
      } catch (error) {
          // Handle potential 404 if agent not found, 422 for validation errors, or other API errors
          if (error.response) {
              if (error.response.status === 404) {
                  server.createErrorResponse(`Agent not found: ${args.agent_id}`);
              }
              if (error.response.status === 422) {
                  server.createErrorResponse(
                      `Validation error updating agent ${args.agent_id}: ${JSON.stringify(error.response.data)}`,
                  );
              }
          }
          server.createErrorResponse(error);
      }
  }

• src/tools/agents/modify-agent.js:54-82 (schema)

  The tool definition object including name, description, and detailed inputSchema for validation.

  export const modifyAgentDefinition = {
      name: 'modify_agent',
      description:
          'Update an existing agent by ID with provided data. Use get_agent_summary to see current config, list_llm_models/list_embedding_models for model options. For tools, use attach_tool instead.',
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'The ID of the agent to modify',
              },
              update_data: {
                  type: 'object',
                  description:
                      'An object containing the fields to update (e.g., name, system, description, tool_ids, etc.)',
                  // Ideally, this would mirror the UpdateAgent schema from the API spec
                  // Example properties (add more as needed based on UpdateAgent schema):
                  properties: {
                      name: { type: 'string', description: 'New name for the agent' },
                      system: { type: 'string', description: 'New system prompt' },
                      description: { type: 'string', description: 'New description' },
                      // Add other updatable fields like tool_ids, source_ids, block_ids, tags, etc.
                  },
                  additionalProperties: true, // Allow other properties from UpdateAgent schema
              },
          },
          required: ['agent_id', 'update_data'],
      },
  };

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

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

  case 'modify_agent':
      return handleModifyAgent(server, request.params.arguments);

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

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

  modifyAgentDefinition,

• src/tools/output-schemas.js:426-437 (schema)

  Output schema definition for structured responses from the modify_agent tool.

  modify_agent: {
      type: 'object',
      properties: {
          success: { type: 'boolean' },
          agent_id: { type: 'string' },
          updated_fields: {
              type: 'array',
              items: { type: 'string' },
          },
      },
      required: ['success', 'agent_id'],
  },