Medialister Client MCP—LLM Reference

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 user is always a client buyer.

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

Data model

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

• IDs are UUIDs. Orders also have public IDs like Q26030039; order tools accept either.

• Purchasable unit is a format (one offer on one media), not a media. One media has many formats.

Context & switching

Switches cascade. To traverse multiple campaigns/orgs, iterate with switch_* between calls.

Roles

Returned per org by list_organizations.

Write-gated tools (ADMIN or MANAGER unless noted): create_project (ADMIN), create_campaign, update_campaign, delete_campaign, send_order_to_review, approve_order_placement, delete_text (ADMIN/MANAGER/EDITOR).

Terminology

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

• Extras — separate add-ons (Personal PR Writing, Extended Guarantee, condition upgrades). In get_order read purchasedExtras/availableExtras. Never mix with options.

• Campaign goal reshapes marketplace filters and default columns.

Order statuses

Single backend status. Use backend values when filtering.

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 ~200 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."

• 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 ≥1M monthly visits + permanent placement + ≥2000 chars of content.

• 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.

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

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

• 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.

Marketplace: marketplace_search, locations.

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. Max qty 99. No checkout via MCP — user pays in web app.

Orders: list_orders, show_all_orders, get_order, get_order_activities, get_order_chat, send_order_to_review, approve_order_placement.

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.

Gotchas

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

2. Marketplace search is fuzzy — verify domain matches manually.

3. 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.

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

5. Options ≠ extras. Different fields.

6. Status filters use backend constants, not UI labels.

7. Cart → no checkout tool. Direct user to web app.

8. Text attach = copy, not link.

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

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

11. delete_campaign not implemented.

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

Common workflows

• Find publishers for campaign: list_campaigns → get_campaign (goal) → marketplace_search with goal-aligned filters → optionally 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 cart: loop add_to_cart(formatId, campaignId, qty) → get_cart to confirm → tell user to book in web app.

• 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

Checkout/payment, billing CRUD, invoices, moving orders between campaigns, rich-text image sizing, user-owned saved views CRUD, member invites/role changes, any publisher-side work. Direct the user to the web app.