MCP tools
Choose the right MCP tools for stories, campaigns, contacts, pitches, coverage, and newsroom settings.
Your client discovers Prezly's tool names and input schemas when it connects. Use this guide to choose a workflow and understand its limits. The catalog includes tools that personal API tokens cannot use; those are separated below.
Scopes are one part of authorization. Your Prezly user must also have the required permissions and newsroom access. See setup and token permissions. A tool appearing in the client does not guarantee it will succeed with your token.
Find, inspect, then act
- Search or list records. Reuse returned identifiers exactly; do not guess an ID from a title.
- Get the selected record. Request full content only when the task needs it.
- Before a change, read the current record again and pass its returned
expected_*values unchanged. - Inspect the result. If the outcome is uncertain, read the affected record before deciding whether another action is needed.
Use exact titles or subjects together with identifiers when reviewing targets. A timestamp or digest precondition protects against a stale edit; it does not prove that the user approved the action.
Searches generally default to 20 records and accept at most 100; coverage search accepts at most 50. Settings lists are bounded, typically at 100 items, and report total/truncation metadata. Do not treat a truncated result as the complete account state.
Where sorting is supported, pass a structured sort object with field and direction (asc or desc). Supported fields vary by tool; story searches support updated_at, for example. Use each tool's advertised filters rather than assuming every search accepts raw Prezly Query Language.
Stories
| Tool | Use it to… |
|---|---|
prezly_search_stories | Find summaries by search/filter; use newsroom_id to narrow the newsroom. Results omit the story body. |
prezly_get_story | Inspect a story by returned UUID or legacy ID. Use include_content: true only when needed. |
prezly_get_story_analytics | Read aggregate site traffic for a published story over 7d, 30d, or 90d (default 30d). Requires permission to view newsroom tracking data as well as story access. |
prezly_create_story_draft | Create a private draft from a title, optional subtitle, and ordered heading/paragraph blocks. |
prezly_update_story_draft | Update a draft with fresh expected_updated_at; replacing format 3–6 content also requires expected_content_version. |
prezly_publish_story | Publish after checking current status and update time. |
prezly_schedule_story | Schedule public or embargo publication after the same fresh-state checks. |
prezly_unpublish_story | Return a published story to draft. |
prezly_unschedule_story | Cancel scheduled or embargo publication and return to draft. |
prezly_delete_story | Soft-delete one inspected story after exact identity, title, timestamp, status, and pin-state checks. |
Reads use stories:read. Draft changes/deletion use stories:write; lifecycle actions use stories:publish as well as the reads needed for preconditions. Related newsroom lookups need sites:read, and deletion checks related campaigns with campaigns:read.
Story creation produces Content Format v6. Its block input supports text headings and paragraphs; advanced media, embeds, galleries, and uploads are outside that creation tool. Draft updates can preserve an existing legacy format. The server calculates the next content version from the fresh version you supply.
Publishing, scheduling, unpublishing, and unscheduling require expected_status and expected_updated_at from a fresh get. Deletion can detach unsent campaigns that reference the story and return those campaigns to draft. Inspect related campaigns before deleting. MCP has no story-restore tool.
Story analytics contain aggregate metrics and daily points, not visitor identities. Check tracked, tracking_enabled, and is_publicly_accessible before interpreting zero metrics. Reports use period.timezone; today is partial. Unavailable analytics return an error rather than a fabricated zero-traffic report.
Campaigns and recipients
| Tool | Use it to… |
|---|---|
prezly_search_campaigns | Find campaign summaries and aggregate performance, optionally scoped to a newsroom. Bodies and clicked-link URLs are omitted. |
prezly_get_campaign | Inspect a campaign's state, aggregate performance, and bounded top clicked links. Content is opt-in. |
prezly_search_campaign_recipients | Find recipients by typed delivery, subscription, ID, exact-email, or partial-name filters. |
prezly_get_campaign_recipient | Inspect a recipient using its returned stable ID and campaign ID. |
prezly_create_campaign_draft | Create a campaign with zero recipients. |
prezly_update_campaign_draft | Change selected draft fields after exact subject and update-time checks. |
prezly_add_campaign_recipients | Add up to 100 explicit contact IDs to a draft. |
prezly_remove_campaign_recipients | Remove up to 100 explicit contact or campaign-recipient IDs from a draft. |
prezly_send_campaign | Send an inspected draft immediately after update-time and recipient-count checks. |
prezly_delete_campaign | Permanently delete a draft and its recipients after subject, update-time, and recipient-count checks. |
Campaign reads use campaigns:read, draft/recipient changes use campaigns:write, and sending uses campaigns:send. Recipient reads and changes also need contacts:read. Keep the read permissions needed for each tool's preflight checks.
Creating a draft or adding recipients never sends it. Sending requires at least one recipient. Repeating an add can refresh metadata on recipients already present, so do not assume it is harmless to repeat.
Recipient tools expose delivery and subscription health, not per-person open/click counts. Search omits alternate addresses and tags. A recipient get returns at most 20 contact email addresses and 100 tags, with truncation information; it omits phone numbers, physical addresses, social profiles, and contact notes. Use campaign aggregates for performance analysis.
Some writes are deferred by Prezly. Personal tokens cannot poll the jobs endpoint: a write can be accepted and then return unknown_outcome when completion cannot be verified. Read the campaign and its recipients before deciding what to do next; never resend a campaign to resolve a polling error.
Pitches
| Tool | Use it to… |
|---|---|
prezly_search_pitches | Find one-to-one email summaries with typed status/newsroom filters and supported sorting. |
prezly_get_pitch | Inspect the exact subject, primary recipient, sender, state, statistics, and bounded validation warnings. Content is opt-in. |
prezly_create_pitch | Create a draft with a non-empty subject and optional sender, primary recipient, content, newsroom, story, and tracking fields. |
prezly_update_pitch | Update an unscheduled, unprocessed draft after exact subject and update-time checks. |
prezly_send_pitch | Submit one inspected draft for immediate delivery after checking its subject, timestamp, primary contact ID, and recipient email. |
Use pitches:read, pitches:write, or pitches:send as appropriate, retaining the precondition reads. Your user also needs the corresponding email-management/sending permissions and sending allowance.
Create and update never send or schedule. Inputs do not support CC/BCC changes, bulk recipients, or scheduling. Content is a serialized Prezly editor document, not arbitrary plain text. Search/get return the primary delivery address; other copy recipients are represented by a count.
A send rejects a scheduled, processing, finalized, sent, or otherwise changed pitch. If sending has an uncertain result, get that same pitch and check its current state. Do not submit it again automatically.
Coverage
| Tool | Use it to… |
|---|---|
prezly_search_coverage | Find up to 50 placement summaries, optionally scoped to a story, with bounded text search and sorting. |
prezly_get_coverage | Read a placement and its current mutation preconditions, including bounded plain-text notes. |
prezly_create_coverage | Create a placement from explicit fields, with API enrichment disabled. |
prezly_update_coverage | Change selected fields after checking the exact headline, type, and update time. |
prezly_delete_coverage | Soft-delete an inspected placement after the same checks. |
Reads use coverage:read; changes use coverage:write. Create/update also require contacts:write because they can create contacts. The tools do not accept raw query objects, attachment payloads, integration runs, provider overrides, or external metadata.
Omitted update fields stay unchanged; nullable fields can be cleared with null. Deleted placements are excluded from MCP search/get. After an ambiguous create, search using the intended headline and URL. After an ambiguous update or deletion, get the same returned identifier.
Contacts and tags
| Tool | Use it to… |
|---|---|
prezly_search_contacts, prezly_get_contact | Find contacts, then read the selected profile and bounded collections. |
prezly_create_contact | Create one person or organization from bounded profile fields; it never sends a message. |
prezly_update_contact | Replace selected profile fields after exact type, display-name, and modification-time checks. |
prezly_delete_contact | Permanently delete one inspected contact after the same identity/state checks. |
prezly_list_contact_tags | Find tag IDs, names, usage counts, and optional groups. |
prezly_create_contact_tag | Create one tag without force-merging an existing tag. |
prezly_update_contact_tag | Rename/regroup a tag after exact name, usage-count, and update-time checks. |
prezly_tag_contacts, prezly_untag_contacts | Add/remove up to 20 known tags on up to 100 explicitly selected contacts. |
prezly_delete_contact_tag, prezly_delete_contact_tags | Permanently delete one tag or up to 20 explicitly selected tags, with per-tag preconditions. |
Use contacts:read for inspection and retain it alongside contacts:write for changes. Contact fields depend on whether the record is a person or organization.
Supplied collections replace the complete collection: email addresses, phone numbers, social accounts, URLs, languages, and organization IDs. Empty clears; omitted preserves. A supplied address replaces the address object. Read the complete current values first and preserve entries you want to keep; do not write back a truncated collection.
Deleting a contact can remove recipients from draft or scheduled campaigns. Inspect those campaigns first. Sent campaign history retains historical recipients. Deleting a tag removes its assignments from contacts.
Tag assignment/removal accepts explicit unique IDs, not a query selector. The server validates the selection, submits one change, and observes the requested membership. Success verifies membership at that observation; search indexing and aggregate tag counts can lag. Unverifiable results are unknown_outcome, with no automatic resubmission.
Newsrooms and settings
Read operations use sites:read; changes need sites:write plus the user's relevant permissions and precondition reads. Newsroom creation also requires the owner's Create newsroom and Manage newsroom related data permissions. It creates an inactive newsroom without demo content, never a live site.
Inspect the current configuration
| Tools | Returned information |
|---|---|
prezly_list_newsrooms, prezly_get_newsroom | Accessible newsrooms and the selected newsroom's identity/current state. |
prezly_list_newsroom_categories, prezly_list_newsroom_languages | Category/language metadata and opaque settings digests for protected updates. |
prezly_list_newsroom_themes | Theme metadata, safe setting descriptors, and digests, excluding setting values and custom code. |
prezly_list_newsroom_galleries, prezly_get_newsroom_gallery | Bounded gallery metadata/order, excluding content, captions, media, and URLs. |
prezly_list_newsroom_domains | Linked domain names/state, excluding DNS records. |
prezly_list_newsroom_hub_members | Up to 100 members with total/truncation information. |
Make a deliberate change
| Tools | Change and boundary |
|---|---|
prezly_update_newsroom_settings | Selected settings after newsroom identity/state checks; tracking policy also requires a compatible theme. |
prezly_create_newsroom_category, prezly_update_newsroom_category | Category translations/featured state; updates need the latest category settings digest. |
prezly_enable_newsroom_language, prezly_update_newsroom_language, prezly_make_newsroom_language_default | Enable a language, change bounded company information with its digest, or change the default with its current-value precondition. |
prezly_update_newsroom_theme_settings, prezly_apply_newsroom_theme | Change advertised primitive settings without activating, or explicitly apply a theme. Both use exact digests. |
prezly_link_newsroom_domain, prezly_check_newsroom_domain, prezly_unlink_newsroom_domain | Manage a domain with its current snapshot/status. These actions can affect public configuration. |
prezly_take_newsroom_online, prezly_take_newsroom_offline | Change public availability after identity, status, and online-state checks. Going online also needs available account capacity. |
prezly_reorder_newsroom_galleries | Reorder the complete set, supplying every gallery ID exactly once; unavailable above 100 galleries. |
prezly_create_newsroom | Create an inactive newsroom within the account's authorization limits. |
prezly_archive_newsroom, prezly_unarchive_newsroom | Change archive state after exact lifecycle checks. |
prezly_link_newsroom_hub_member, prezly_unlink_newsroom_hub_member | Change membership using the complete current member-ID set as a precondition. |
prezly_delete_newsroom | Permanently delete an inspected newsroom after lifecycle and story/campaign/pitch/coverage count checks. |
Theme settings accept only advertised primitive values. Custom CSS, JavaScript, HTML, nested/media settings, and automatic acknowledgement of lost theme features are outside these tools. Treat settings digests as opaque: return the exact digest from a fresh list rather than constructing one.
Gallery creation/editing/deletion, language disabling, forced language switching, privacy-request actions, subscriber mutations, and editor recovery are not exposed through MCP. Use the appropriate Prezly interface for these tasks.
Advertised tools unavailable to personal tokens
These tools appear in discovery but their endpoints currently reject personal tokens. Adding write, send, or every available scope does not resolve that restriction. Use the Prezly interface or discuss an appropriate supported integration with your administrator; do not switch credentials automatically after a denial.
| Area | Unavailable tools and intended behavior |
|---|---|
| Story preview | prezly_preview_story: bounded text/optional HTML preview. An ordinary story read can still contain an existing preview link. |
| Story copies | prezly_duplicate_story, prezly_translate_story_draft: create draft copies. The translation tool copies and links; it does not machine-translate text. |
| Story placement | prezly_move_story, prezly_pin_story, prezly_unpin_story: move or change prominent placement. |
| Campaign copies and scheduled delivery | prezly_duplicate_campaign, prezly_schedule_campaign, prezly_unschedule_campaign, prezly_send_campaign_test: copy, schedule/cancel, or send a test to 1–5 explicit addresses. |
| Bulk contact deletion | prezly_delete_contacts: delete up to 100 inspected contacts. The distinct single-record prezly_delete_contact endpoint permits personal tokens. |
| Newsroom conversion | prezly_convert_newsroom_to_hub: irreversible conversion to a hub. |
| Webhooks | prezly_list_newsroom_webhooks, prezly_create_newsroom_webhook, prezly_update_newsroom_webhook, prezly_delete_newsroom_webhook: inspect/manage delivery configuration; list results omit full URLs and secrets. |
| Sender identities | prezly_list_sender_addresses, prezly_create_sender_address, prezly_update_sender_address, prezly_delete_sender_address: manage identities; creation may send verification email. |
| Snippets | prezly_list_snippets, prezly_get_snippet, prezly_create_snippet, prezly_update_snippet: reusable editor content; full bodies are opt-in and updates replace them completely. |
| Templates | prezly_list_templates, prezly_get_template, prezly_create_template, prezly_update_template: campaign-template editor content with the same body-replacement boundary. |
| Notification preferences | prezly_list_notification_preferences, prezly_update_notification_preference: inspect/change optional email settings; required emails cannot be disabled. |
Tool descriptions and input schemas in your connected client specify exact fields and bounds. Availability remains subject to authorization and the deployed server version. If a permitted write is accepted but subsequent job polling fails, treat it as an uncertain outcome and inspect current state before acting again.
Read safety and privacy for approval and data-handling boundaries, or troubleshooting for denied calls, stale state, and uncertain results.