Cross-post to Medium

post_to_medium cross-posts a published blog post to Medium. It preserves the canonical URL back to your site, carries the tags over, and keeps SEO credit on the original. You call it once and the story lands on Medium as a draft or a public post.

This page covers the lead image control. For everything else the tool does, see the tool description in your MCP client.

Which image leads the story

Medium has no separate "featured image" field in its publishing API. The image at the top of the story body becomes the lead image (the large image shown above the title on Medium and in shares). So whichever image comes first in the content is the one Medium uses.

By default, the hero you designed for your own site often reads wrong as a Medium lead. It carries on-site styling, overlaid text, or framing that only makes sense in context. The OG image is usually the cleaner choice for an off-site lead.

post_to_medium resolves the lead image in this order:

• og (default) uses the post's OG image. If the post has no OG image, it falls back to the hero.
• hero uses the on-site hero image (featured_image).
• An explicit image URL uses that image directly.

The chosen image is injected as the first image in the Medium content, so it becomes the lead image on the published story, not just the social card.

Usage

Default. Leads with the OG image, falling back to the hero if the post has no OG image:

{
  "id": "<post-id>",
  "confirm": true
}

Keep the on-site hero as the Medium lead:

{
  "id": "<post-id>",
  "confirm": true,
  "featured_image": "hero"
}

Use a specific image:

{
  "id": "<post-id>",
  "confirm": true,
  "featured_image": "https://cdn.example.com/lead.png"
}

The response includes featured_image_source (the choice that was applied) and featured_image_url (the resolved URL, or null when the post had no matching image to inject).

Notes

• The image choice behaves the same for draft and public cross-posts. The injection happens when the content is formatted, before the publish status is applied.
• If neither an OG image nor a hero is set on the post, no lead image is injected and the cross-post still succeeds.
• Re-running on an already cross-posted post returns the existing Medium URL unless you pass force: true.

Related

• Post Distribution Dashboard