Medialister MCP

Medialister is a B2B marketplace where clients (agencies, brands, SMBs) buy media placements from publishers for PR, content distribution, and link building. The unit of work is an order: a booked placement of a piece of content on a media site. The MCP serves one side: client buyers (organizations with projects → campaigns → orders). The user's role determines which tools apply.

Endpoint: https://api.medialister.com/mcp. Remote HTTP MCP. Auth handled by host. Session is stateful with "current" pointers (org, project, campaign)—many tools read/write to them implicitly.

Data Model

Buyer side:

Organization → Project → Campaign → Order
                         Campaign → Texts (reusable within campaign)

IDs are UUIDs. Orders also have public IDs like Q26030039; order tools accept either. The purchasable unit is a format (one offer on one media), not a media—one media has many formats.

Context & Switching

There are three current pointers: organization, project, and campaign.

switch_organization sets the current campaign based on the user's role and available projects. Switches cascade. To traverse multiple campaigns/orgs, iterate with switch_* between calls.

Roles

Returned per org by list_organizations (as a numeric code; map to the names below).

Write-gated tools (ADMIN or MANAGER unless noted):

• Client side: create_project (ADMIN), create_campaign, update_campaign, delete_campaign (ADMIN/MANAGER, not implemented), send_order_to_review, approve_order_placement, move_order_to_campaign, delete_text (ADMIN/MANAGER/EDITOR).

Terminology

• Options = Conditions—booking parameters (word/symbol limits, hyperlinks, images, turnaround, permanent placement, indexing). In get_order read options/conditions/extraOptions/otherOptions. "Options" and "conditions" are synonyms.

• Extras—separate optional add-on services (Personal PR Writing, Extended Guarantee, condition upgrades). In get_order read purchasedExtras (already bought) / availableExtras. Use list_order_extras for the full purchasable list on an order. Never mix with options/conditions—different fields, different tools.

• Campaign goal reshapes marketplace filters and default columns.

Order Statuses

Single backend status. Use backend values when filtering.

New orders booked in the web app enter BOOKED ("To Publish")—the normal entry point before sending content to review.

Preconditions: send_order_to_review needs BOOKED or TO_MAKE_CHANGES_CLIENT with content + accepted conditions. approve_order_placement needs ARTICLE_TO_APPROVE.

Listing Orders (Critical)

• list_orders—current campaign only. Filter by backend status.

• show_all_orders—tree across account. ADMIN: full tree. MANAGER: current campaign only. Under MANAGER, backfill by iterating switch_campaign + list_orders.

Marketplace Search

Fuzzy text search (Meilisearch), not structured lookup. Media are matched on name, domain, and category keywords.

Search Strategy

• Keyword/name: pass natural phrase in query (e.g. "tech news").

• Single domain: pass the domain in query. Results are fuzzy—verify exact match yourself: lowercase, strip www., compare per result. Do not trust order.

• Bulk domains: comma/semicolon/newline-separated list in query, up to 50 per call. Still verify exact matches per result.

• Filter-only browsing: omit query and rely on filters (category, location, price, metrics). This is how to answer questions like "find finance blogs in Germany under $400."

• By topic of content: use semantic_search instead (see Tool Index). It matches the meaning of a keyword against the pages media have published, not their names.

Filters combine with AND. Each of formatType, mediaCategory, acceptedTopic, mediaBadge, formatBadge, mediaType, language, location, audienceByCountry, hyperlinksType takes exactly one value. Passing comma/pipe-separated lists fails silently in two ways: formatType and mediaCategory ignore the filter and return the full marketplace (looks like success but filter didn't apply); acceptedTopic returns zero results. Always fan out into multiple calls and merge client-side when OR logic is needed.

Accuracy tradeoff: one domain per call is most reliable when precision matters (e.g., pricing a specific publisher). Bulk mode is fine for availability checks.

Location vs Audience — These Are Different

• location = where the media is based or what geography it covers (Local Coverage). Nesting: picking a country returns media tagged to any sub-region of that country. E.g. picking "United States" returns media tagged to NYC, Washington, California, etc.

• audienceByCountry = where readers come from. Applied only to media with >30% of traffic from that country. Use for intent like "publications read mostly by Germans."

• locations tool returns only places where media actually exist in our DB. If empty, fall back to parent region.

Categories (mediaCategory, One Value per Call)

Agriculture, Animals, Architecture & Construction, Arts, Automotive, Business, Cryptocurrency, E-commerce, Fashion & Beauty, Financial, Food & Cuisine, Gambling & Betting, Gaming, General News, Green Energy & Ecology, Health & Medicine, Hobbies & Leisure, Human Resources, Kids & Parenting, Legal, Lifestyle, Local News, Logistics, Manufacturing & Industrial, Marketing & PR, Men's, Music & Movie, Real Estate, Religion, Science & Education, Sensitive, Sports, Technology, Trading, Transportation, Travel, Women's.

Sensitive Topics (acceptedTopic, One Value per Call)

Adult, Alcohol, Betting, CBD, Crypto, Dating, Gambling, Loans, Medicine, Politics News, Smoking, Trade. Returns only media that explicitly accept this topic. Many publishers refuse sensitive topics, so this filter narrows results significantly.

Format Types (formatType, One Value per Call)

• Article—staff-written news, features, or opinions. Editor controls content.

• Contributor Post—guest-author piece. Content guaranteed placement only via direct link (not in main feed). Editors can add their own links. Conditions vary. Use direct-submission formats if the client needs guarantees.

• Interview—Q&A format, one or several topics.

• Listicle—numbered or bulleted article (e.g. "10 Best PR Tools"). Strong for contextual brand inclusions and product mentions.

• Mention—backlink inserted into an existing article. No new content; client provides the link and placement instructions. Use for SEO link-building into existing pages.

• Paid News—factual news targeting general audiences (vs Press Release targeting press).

• Press Release—standard concise news announcement.

• Thought Leadership—named-author column (like Forbes Councils). For founders, execs, experts building personal authority.

Badges — Media vs Format (Important Distinction)

Badges apply at two different levels. Pick the right parameter.

mediaBadge—applies to the whole media outlet. Only two values:

• Editor's Choice—curated by Medialister team.

• Verified—publisher org passed KYB.

formatBadge—applies to individual offers. Values:

• Client's Choice—top-performing historically (ABC segmentation on order data).

• LLM-Friendly—optimized for AI/LLM answer inclusion. Requires ≥250,000 monthly visits + permanent placement.

• Best Price—verified cheaper than competitors (via Fatgrid).

• Unique Offer—exclusive to Medialister per Fatgrid data.

• New—media listed in the last 60 days.

UI lets users pick multiple badges (OR logic). MCP takes one per call—fan out for multiple.

Other Filter Notes

• sortBy: price, name, turnAroundTime, createdAt, updatedAt, audience, ahrefsDr, semrushOrganicTraffic, rating, estimatedViews, mai.

• estimatedViews is derived from SimilarWeb with small randomness—directional, not exact.

• audienceMin/audienceMax = monthly visits (what the UI calls "Visits").

• mai is the Medialister Attention Index, or for how long viewers will remember content in days.

• Only Ahrefs DR and Semrush organic traffic are exposed as metric filters in MCP. Moz, Majestic, and other SEO metrics from the UI are not filterable here.

Tool Index

• Connectivity: ping, health_check.

• Orgs & context: list_organizations, get_organization, switch_organization, get_balance.

• Projects: list_projects, get_project, create_project, get_project_activities, switch_project.

• Campaigns: list_campaigns, get_campaign, create_campaign, update_campaign, delete_campaign (not implemented), switch_campaign. Budget: TRY|BEGINNER|MEDIUM|BIG|ENTERPRISE. Publishing period: WEEK|MONTH|QUARTER|YEAR|NOT_DECIDED.

• Media projects (publisher side): not in this MCP. Media projects, offers and batch import are in the separate Medialister Publisher MCP. It also has list_media_types, which returns the IDs to pass as mediaTypeId.

• Marketplace: marketplace_search, locations, semantic_search. semantic_search takes a keyword (for example a striking-distance query) and returns purchasable media domains ranked by how well their published pages match it, each with its top matching pages and a relevance percentage. limit: default 10, max 50. minRelevance: 60–80 (values outside are clamped); raise it for stricter matches.

• Insights: get_insight—striking-distance keyword recommendations for the current campaign's project, from its Google Search Console or DataForSEO data: each keyword with impressions, average position and matched media with offers (format ID, type, price). Alphabetical, as on the dashboard's Insights screen. Paginated with page and perPage (default 10, max 50). Works only when recommendations are built for the project; check connected and built in the response.

• Bookmarks: get_bookmark_groups, get_bookmarks, create_bookmark_group, add_to_bookmark_group, public_bookmark_groups, public_saved_views. Max 500 formats/group.

• Cart: get_cart, add_to_cart (formatId required; campaignId optional, defaults to current campaign; qty default 1, max 99), remove_from_cart (by cartItemId, or domain/formatType), set_cart_item_excluded (excluded item stays in cart but is skipped at checkout).

• Orders: list_orders, show_all_orders, get_order, get_order_activities, get_order_chat, list_order_extras, send_order_to_review, approve_order_placement, move_order_to_campaign.

• Texts: list_campaign_texts, get_text, create_text, delete_text, link_text_to_orders (comma-separated orderIds, action: attach|detach). Only ready texts attach. Attachment copies content—source edits don't propagate. No update_text via MCP.

Booking / Checkout

There is no way to book placements via MCP; only cart management is possible. To book, the user goes to this page manually: https://app.medialister.com/cart. Use set_cart_item_excluded to skip items without removing them, and remove_from_cart to drop them entirely. Check get_balance (available vs reserved) before checkout.

Extras

list_order_extras returns the purchasable extras for an order: public extras available for purchase plus pending custom extras proposed by the publisher in chat. Prices include the client service fee. Accepts UUID or public ID. Note: there is no purchase-extra tool in MCP—extras are surfaced for review here and in get_order (purchasedExtras / availableExtras), but the actual purchase is completed in the web app.

Gotchas

• MANAGER + show_all_orders = current campaign only. Check role first.

• Marketplace search is fuzzy—verify domain matches manually.

• Single-value-only filters (formatType, mediaCategory, acceptedTopic, mediaBadge, formatBadge, etc.). Multi-value inputs fail silently—you'll get either the full unfiltered marketplace or zero hits with no error. Fan out for OR logic.

• location ≠ audienceByCountry. First is coverage, second is reader geography (≥30% threshold).

• Options ≠ extras. Different fields and different tools. Conditions/options are read in options/conditions; extras are read in purchasedExtras/availableExtras and listed with list_order_extras.

• Status filters use backend constants, not UI labels.

• move_order_to_campaign: the target campaign must belong to the same organization. After a move the order leaves the source campaign's list_orders (current-campaign-only)—confirm with get_order or by switching to the target campaign.

• Three current pointers (org, project, campaign). switch_organization picks the campaign from the user's role and available projects—re-assert the pointer you need.

• Text attach = copy, not link.

• Timestamps are UTC. Convert if user mentioned a timezone.

• Switches cascade—current org/project/campaign can change unexpectedly.

• get_insight reads the current campaign's project. Switch to the right project before calling it.

• delete_campaign not implemented. Cannot delete the current campaign or the last campaign in a project; don't switch campaigns to work around it—ask the user to switch manually.

• Order tools accept UUID or public ID (Q26030039).

• list_organizations returns role as a numeric code—confirm the code→name mapping in your client.

Common Workflows

• Find publishers for campaign: list_campaigns → get_campaign (goal) → marketplace_search with goal-aligned filters → optionally add_to_bookmark_group.

• Find media for SEO keywords: switch_project to the client's project → get_insight for its striking-distance keywords and matched offers → or semantic_search(keyword) for any keyword → add_to_cart or add_to_bookmark_group.

• Check domain availability: marketplace_search(query=domain) → verify exact match (lowercase, strip www.) → list matching formats.

• Find media by topic + country: marketplace_search with mediaCategory + location (or audienceByCountry if the intent is about readers).

• Prepare & book cart: loop add_to_cart(formatId, campaignId, qty) → get_cart to confirm → optionally remove_from_cart / set_cart_item_excluded → check get_balance covers the total → User manually goes to https://app.medialister.com/cart to book → list_orders to confirm new BOOKED orders. If the available balance is short, stop and tell the user to top up in the web app. Exception: an organization on post-payment books against its credit limit, so a short or negative balance does not block it—tell the user to book in the web app.

• Review an order's extras: list_order_extras(orderId) (purchase itself is web-app only).

• Move an order to another campaign: get_order → list_campaigns (same org) to pick the target → move_order_to_campaign(orderId, campaignId) → verify under the target campaign.

• Order status: get_order for summary; add get_order_activities for history, get_order_chat for messages.

• All orders across account: if ADMIN → show_all_orders. If MANAGER → loop list_organizations → switch_organization → list_projects → switch_project → list_campaigns → switch_campaign → list_orders.

• Approve published article: get_order (confirm ARTICLE_TO_APPROVE) → approve_order_placement.

Out of Scope via MCP

Billing CRUD, invoices, balance top-up and payments, rich-text image sizing, user-owned saved views CRUD, member invites/role changes, purchasing extras (list-only via MCP)—no tools exposed. Direct the user to the web app for these.