add_users_to_audience

Instructions

Implementation Reference

• src/tools/audiences.ts:125-141 (handler)

  The 'add_users_to_audience' tool handler: registers an MCP tool that accepts audience_id and a JSON payload, then POSTs to /{audience_id}/users to add users to a custom audience.

  // ─── add_users_to_audience ─────────────────────────────────
  server.tool(
    "add_users_to_audience",
    "Add users to a custom audience. Payload must be a JSON string containing hashed user data with a schema array defining the data types (e.g. EMAIL, PHONE, FN, LN).",
    {
      audience_id: z.string().describe("Audience ID"),
      payload: z.string().describe("JSON string: {schema: ['EMAIL','PHONE',...], data: [['hash1','hash2',...], ...]}. All PII must be SHA-256 hashed."),
    },
    async ({ audience_id, payload }) => {
      try {
        const { data, rateLimit } = await client.post(`/${audience_id}/users`, { payload });
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/tools/audiences.ts:129-131 (schema)

  Input schema for add_users_to_audience: audience_id (string) and payload (JSON string with schema + data).

  {
    audience_id: z.string().describe("Audience ID"),
    payload: z.string().describe("JSON string: {schema: ['EMAIL','PHONE',...], data: [['hash1','hash2',...], ...]}. All PII must be SHA-256 hashed."),

• src/tools/audiences.ts:125-141 (registration)

  Tool registration via server.tool() call within the registerAudienceTools function.

  // ─── add_users_to_audience ─────────────────────────────────
  server.tool(
    "add_users_to_audience",
    "Add users to a custom audience. Payload must be a JSON string containing hashed user data with a schema array defining the data types (e.g. EMAIL, PHONE, FN, LN).",
    {
      audience_id: z.string().describe("Audience ID"),
      payload: z.string().describe("JSON string: {schema: ['EMAIL','PHONE',...], data: [['hash1','hash2',...], ...]}. All PII must be SHA-256 hashed."),
    },
    async ({ audience_id, payload }) => {
      try {
        const { data, rateLimit } = await client.post(`/${audience_id}/users`, { payload });
        return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
      } catch (error) {
        return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/index.ts:60-61 (registration)

  Registration of all audience tools (including add_users_to_audience) in the main server setup.

  // --- Audience & Targeting ---
  registerAudienceTools(server, client);

• src/tools/audiences.ts:5-6 (helper)

  The registerAudienceTools helper function that encapsulates all audience tool registrations.

  export function registerAudienceTools(server: McpServer, client: AdsClient): void {
    // ─── list_custom_audiences ─────────────────────────────────