Flodesk MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Batch create or update subscribers.

batch_create_or_update_subscribers

Destructive

Create or update up to 50 subscribers in one request to manage Flodesk subscriber details, segments, and opt-in status.

Instructions

Create or update up to 50 subscribers in a single request.

Input Schema

TableJSON Schema

Name	Required	Description
`account`	No	Exact configured private account profile label; not a tenant or provider account ID.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.
`subscribers`	No
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv3.0.0Oct 5, 2026

addedInput schema / $defs

Added value: +{
+  "subscribers": {
+    "description": "List of subscribers to create or update. Maximum 50 items.",
+    "items": {
+      "properties": {
+        "custom_fields": {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "An object containing custom field data.\nE.g. ``` \"favorite_color\": \"Lavender\" ```.",
+          "type": "object"
+        },
+        "double_optin": {
+          "description": "Whether or not to require the subscriber to confirm subscription via email.\n\nThis option is only available to set with new subscriber creation. Default to `false` if not indicated.",
+          "type": "boolean"
+        },
+        "email": {
+          "description": "The subscriber's `email`. Either `email` or `id` must be included.",
+          "type": "string"
+        },
+        "first_name": {
+          "description": "The subscriber's first name.",
+          "type": "string"
+        },
+        "id": {
+          "description": "The subscriber's `id`. Either `email` or `id` must be included.",
+          "type": "string"
+        },
+        "last_name": {
+          "description": "The subscriber's last name.",
+          "type": "string"
+        },
+        "optin_ip": {
+          "description": "IP address from which the subscriber confirmed their opt-in.",
+          "type": "string"
+        },
+        "optin_timestamp": {
+          "description": "The date and time the subscribers confirmed their opt-in in ISO 8601 format.\nE.g. `2023-01-02T15:04:05.999Z`.",
+          "type": "string"
+        },
+        "segment_ids": {
+          "description": "The segments this subscriber will be added to. Cap at `50`.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "title": "CreateOrUpdateSubscriberItem represents a single subscriber payload.",
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

changedInput schema / properties / confirm / description

Previous value: -"Must be true for the requested mutation or exclusive private output file."New value: +"Set true only when the user asked for exactly this action."

addedInput schema / properties / payload / properties / subscribers / $ref
```
Added value: +"#/$defs/subscribers"
```
removedInput schema / properties / payload / properties / subscribers / description
```
Removed value: -"List of subscribers to create or update. Maximum 50 items."
```

removedInput schema / properties / payload / properties / subscribers / items

Removed value: -{
-  "properties": {
-    "custom_fields": {
-      "additionalProperties": {
-        "type": "string"
-      },
-      "description": "An object containing custom field data.\nE.g. ``` \"favorite_color\": \"Lavender\" ```.",
-      "type": "object"
-    },
-    "double_optin": {
-      "description": "Whether or not to require the subscriber to confirm subscription via email.\n\nThis option is only available to set with new subscriber creation. Default to `false` if not indicated.",
-      "type": "boolean"
-    },
-    "email": {
-      "description": "The subscriber's `email`. Either `email` or `id` must be included.",
-      "type": "string"
-    },
-    "first_name": {
-      "description": "The subscriber's first name.",
-      "type": "string"
-    },
-    "id": {
-      "description": "The subscriber's `id`. Either `email` or `id` must be included.",
-      "type": "string"
-    },
-    "last_name": {
-      "description": "The subscriber's last name.",
-      "type": "string"
-    },
-    "optin_ip": {
-      "description": "IP address from which the subscriber confirmed their opt-in.",
-      "type": "string"
-    },
-    "optin_timestamp": {
-      "description": "The date and time the subscribers confirmed their opt-in in ISO 8601 format.\nE.g. `2023-01-02T15:04:05.999Z`.",
-      "type": "string"
-    },
-    "segment_ids": {
-      "description": "The segments this subscriber will be added to. Cap at `50`.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    }
-  },
-  "title": "CreateOrUpdateSubscriberItem represents a single subscriber payload.",
-  "type": "object"
-}

removedInput schema / properties / payload / properties / subscribers / type
```
Removed value: -"array"
```
addedInput schema / properties / subscribers / $ref
```
Added value: +"#/$defs/subscribers"
```

removedInput schema / properties / subscribers / description

Removed value: -"List of subscribers to create or update. Maximum 50 items."

removedInput schema / properties / subscribers / items

Removed value: -{
-  "properties": {
-    "custom_fields": {
-      "additionalProperties": {
-        "type": "string"
-      },
-      "description": "An object containing custom field data.\nE.g. ``` \"favorite_color\": \"Lavender\" ```.",
-      "type": "object"
-    },
-    "double_optin": {
-      "description": "Whether or not to require the subscriber to confirm subscription via email.\n\nThis option is only available to set with new subscriber creation. Default to `false` if not indicated.",
-      "type": "boolean"
-    },
-    "email": {
-      "description": "The subscriber's `email`. Either `email` or `id` must be included.",
-      "type": "string"
-    },
-    "first_name": {
-      "description": "The subscriber's first name.",
-      "type": "string"
-    },
-    "id": {
-      "description": "The subscriber's `id`. Either `email` or `id` must be included.",
-      "type": "string"
-    },
-    "last_name": {
-      "description": "The subscriber's last name.",
-      "type": "string"
-    },
-    "optin_ip": {
-      "description": "IP address from which the subscriber confirmed their opt-in.",
-      "type": "string"
-    },
-    "optin_timestamp": {
-      "description": "The date and time the subscribers confirmed their opt-in in ISO 8601 format.\nE.g. `2023-01-02T15:04:05.999Z`.",
-      "type": "string"
-    },
-    "segment_ids": {
-      "description": "The segments this subscriber will be added to. Cap at `50`.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    }
-  },
-  "title": "CreateOrUpdateSubscriberItem represents a single subscriber payload.",
-  "type": "object"
-}

removedInput schema / properties / subscribers / type
```
Removed value: -"array"
```

First observedv2.0.0Oct 3, 2026

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds nothing about what a destructive update actually overwrites, how partial failures in a 50-item batch are handled, or whether duplicates are matched by id or email. The only added fact (the 50 cap) is already in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence with the key constraint front-loaded and no filler. It is efficient, though arguably too terse for a destructive 5-parameter batch tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent batch mutation with nested objects and no output schema, the description should address partial success, matching semantics, and the confirm/payload_file interplay. None of that is present, leaving an agent under-informed about consequences of a 50-record write.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so the schema already documents account, confirm, payload, subscribers, and payload_file. The description adds no meaning beyond the existing 50-item maximum, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (create or update) plus resource (subscribers) and adds the batch scope ('up to 50 subscribers in a single request'), which implicitly distinguishes it from the singular create_or_update_subscriber sibling. It never names that sibling or the related preview_subscriber_batch/submit_subscriber_batch tools, so differentiation stays inferential rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to prefer this over create_or_update_subscriber for a single record, or over preview_subscriber_batch to validate before committing. No mention of preconditions, rate limits, or the confirm flag's role.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Batch create or update subscribers.

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools