HubSpot MCP Server

Instructions

🛡️ Guardrails:
  1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.

🎯 Purpose:
  1. Updates an existing HubSpot engagement (Note or Task).
  2. Allows modification of engagement attributes, content, and metadata.

📋 Prerequisites:
  1. You need the engagement ID to update an existing engagement.
  2. Use the hubspot-get-engagement tool to get the current engagement details if needed.
  3. Use the hubspot-get-user-details tool to get the owner ID.

🧭 Usage Guidance:
  1. Use for updating NOTE content or TASK details (subject, description, status).
  2. Only include the fields you want to update - other fields will remain unchanged.
  3. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly.

Implementation Reference

• dist/tools/engagements/updateEngagementTool.js:60-103 (handler)

  Executes the tool logic: parses args, builds PATCH request body for HubSpot engagements API, sends request, handles response or error.

  async process(args) {
      try {
          const { engagementId, ownerId, timestamp, metadata, associations } = args;
          // Build request body with only provided fields
          const requestBody = {
              ...(ownerId || timestamp !== undefined
                  ? {
                      engagement: {
                          ...(ownerId && { ownerId }),
                          ...(timestamp !== undefined && { timestamp }),
                      },
                  }
                  : {}),
              ...(Object.keys(metadata).length > 0 && { metadata }),
              ...(Object.keys(associations).length > 0 && { associations }),
          };
          const response = await this.client.patch(`/engagements/v1/engagements/${engagementId}`, {
              body: requestBody,
          });
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          status: 'success',
                          engagement: response,
                          message: `Successfully updated engagement ${engagementId}`,
                      }, null, 2),
                  },
              ],
          };
      }
      catch (error) {
          return {
              content: [
                  {
                      type: 'text',
                      text: `Error updating HubSpot engagement: ${error instanceof Error ? error.message : String(error)}`,
                  },
              ],
              isError: true,
          };
      }
  }

• dist/tools/engagements/updateEngagementTool.js:6-24 (schema)

  Zod schema defining the input parameters for updating an engagement: engagementId (required), ownerId/timestamp/metadata/associations (optional).

  const UpdateEngagementSchema = z.object({
      engagementId: z.number().int().positive().describe('The ID of the engagement to update'),
      ownerId: z
          .number()
          .int()
          .positive()
          .optional()
          .describe('The ID of the owner of this engagement'),
      timestamp: z
          .number()
          .int()
          .optional()
          .describe('Timestamp for the engagement (milliseconds since epoch).'),
      metadata: z
          .object({})
          .passthrough()
          .describe('Metadata specific to the engagement type (Note or Task)'),
      associations: AssociationsSchema.describe('Associated records for this engagement'),
  });

• dist/tools/engagements/updateEngagementTool.js:25-53 (registration)

  ToolDefinition object specifying name 'hubspot-update-engagement', description, inputSchema, and annotations; passed to BaseTool constructor.

  const ToolDefinition = {
      name: 'hubspot-update-engagement',
      description: `
      🛡️ Guardrails:
        1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.
  
      🎯 Purpose:
        1. Updates an existing HubSpot engagement (Note or Task).
        2. Allows modification of engagement attributes, content, and metadata.
  
      📋 Prerequisites:
        1. You need the engagement ID to update an existing engagement.
        2. Use the hubspot-get-engagement tool to get the current engagement details if needed.
        3. Use the hubspot-get-user-details tool to get the owner ID.
  
      🧭 Usage Guidance:
        1. Use for updating NOTE content or TASK details (subject, description, status).
        2. Only include the fields you want to update - other fields will remain unchanged.
        3. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly.
    `,
      inputSchema: zodToJsonSchema(UpdateEngagementSchema),
      annotations: {
          title: 'Update Engagement',
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
      },
  };

• dist/tools/toolsRegistry.js:42-42 (registration)

  Registers an instance of UpdateEngagementTool in the central tools registry.

  registerTool(new UpdateEngagementTool());