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 now serves one sides: client buyers (organizations with projects → campaigns → orders). The user's role and the org's type determine 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 four current pointers: organization, project, campaign, and media project.

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):

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

• Cart / checkout: checkout_cart needs ADMIN/MANAGER in the project, or ADMIN in the organization.

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 created by checkout_cart 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."

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, 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): list_media_projects, get_media_project, create_media_project, update_media_project, archive_media_project, switch_media_project. create/update take name, website, optional mediaTypeId (opaque ID—no list_media_types tool exposed; source it elsewhere). archive soft-deletes the project and all its formats.

• 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 (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), checkout_cart.

• 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

checkout_cart purchases all non-excluded items in the current cart using the organization's prepaid balance. It checks role (ADMIN/MANAGER in the project, or ADMIN in the org), item availability, and sufficient balance, then creates orders in BOOKED. There is no card-payment step in MCP—if balance is insufficient, the user tops up in the web app, then books. 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.

• Cart → checkout_cart now books non-excluded items, but it spends prepaid balance and has no card step. Verify get_balance first; on insufficient funds, route the user to top up in the web app, then book. Checkout is scoped to the current campaign/cart, so assert the campaign pointer first.

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

• Four current pointers now (org, project, campaign, media project). switch_organization may land you on a media project instead of a campaign depending on role—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/media project can change unexpectedly.

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

• 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 → checkout_cart → list_orders to confirm new BOOKED orders. If balance is short, stop and tell the user to top up 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 card payment (checkout_cart spends prepaid balance only—top-ups happen in the web app), 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.