Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.magicpost.in/llms.txt

Use this file to discover all available pages before exploring further.

The MagicPost MCP server exposes 8 tools your LLM client can call to read analytics, manage drafts, schedule posts, and publish to LinkedIn. This page documents every tool’s inputs, outputs, and special behaviors — use it as a reference when building prompts or integrating MagicPost into an agent workflow.

​
get_metrics_summary

Returns a compact summary of your LinkedIn analytics, including top-line totals and the top N posts by impressions. Use this when you want an overview of how your content is performing.
InputTypeDefaultDescription
period'7d' | '30d' | '90d' | '180d' | 'all''30d'Time window to summarize
top_nint5Number of top posts to return (clamped to 1–20)
Output 
{
  "period": "30d",
  "profile": {"name": "Naïlé Titah", "headline": "...", "followers_total": 24174},
  "access": {"linkedin_connected": true, "impressions_access": true},
  "totals": {"posts_count": 10, "impressions": 56147, "likes": 740, "comments": 319, "reposts": 11},
  "averages_per_post": {"impressions": 5614.7},
  "top_posts": [{"urn": "...", "post_url": "...", "text_preview": "...", "num_impressions": 12500}]
}

​
refresh_my_posts

Triggers a fresh pull of your LinkedIn posts and waits until the sync job completes. Polls the job status every 2 seconds.
InputTypeDefaultDescription
max_wait_secondsint90How long to keep polling before giving up
Only call this when the user explicitly asks to refresh or re-sync their data. For routine analytics questions, use get_metrics_summary instead — it reads from cached data, which is sufficient in most cases.
Returns {success, job_id, status, detail} on completion. If the job is still running when max_wait_seconds is reached, returns {success: false, status: "timeout", ...}. The job continues running on the server regardless.

​
list_my_posts

Lists your posts filtered by lifecycle status. Use this to see what’s coming up, what’s in progress, or what has already been published.
InputTypeDefaultDescription
status'draft' | 'scheduled' | 'published''scheduled'Which posts to return
limitint20Page size (max 100)
offsetint0Pagination offset
Status values:
  • draft — created but not scheduled and not yet published
  • scheduled — planned for future publication, sorted by schedule date ascending
  • published — already on LinkedIn, sorted by created date descending

​
get_post

Fetches the full record for a single post you own.
InputTypeDescription
post_idstringThe post UUID
Returns the complete post object with all fields. Returns an error if the post does not exist or is not owned by your account.

​
create_or_update_post

Creates a new draft post or updates the text of an existing one. Omit post_id to create; include it to update.
InputTypeDescription
contentstringPost text (line breaks are preserved)
post_idstring | nullIf provided, updates the existing post; if null, creates a new one
Returns {success: true, post_id, created: bool}. Use the returned post_id (not id) when chaining into schedule_post or publish_post_now.
Text only in v1. Images, videos, polls, and @mentions must be added from the MagicPost web UI after the draft is created.

​
schedule_post

Schedules a post for future publication on LinkedIn. Checks for same-day and exact-slot conflicts before confirming.
InputTypeDefaultDescription
post_idstring—The post to schedule
at_isostring—ISO 8601 datetime, e.g. 2026-06-01T14:00 or 2026-06-01T14:00:00+02:00
timezonestring | nullUser’s stored timezoneIANA timezone name override
confirm_same_daybooltrueWarn if other posts are already scheduled that day
confirm_exact_slotbooltrueWarn if a post exists within ±5 minutes of the requested time

​
Warning flow

When confirm_same_day or confirm_exact_slot is true (the default) and a conflict exists, the tool returns HTTP 200 with success: false and a warning field. Surface the warning to the user verbatim and only retry with confirm_same_day: false or confirm_exact_slot: false after they explicitly confirm. 
{
  "success": false,
  "warning": "same_day_posts",
  "message": "User has 2 other post(s) scheduled on 2026-06-01 (Europe/Paris).",
  "existing": [
    {"post_id": "abc", "preview": "5 leçons leadership…", "date_post": "2026-06-01", "hour_post": "09:00"},
    {"post_id": "def", "preview": "Mon erreur en 2025…", "date_post": "2026-06-01", "hour_post": "18:00"}
  ],
  "hint": "Ask the user to confirm, then retry with confirm_same_day=false."
}
An exact_slot_conflict (within ±5 minutes) takes precedence over same_day_posts and is returned on its own if both apply.

​
Token expired

If your LinkedIn token has expired, the response includes actionable: true and a hint. Surface this to the user — do not retry automatically. 
{
  "success": false,
  "error_type": "token_expired",
  "actionable": true,
  "hint": "Tell the user to reconnect LinkedIn from MagicPost > Settings."
}

​
cancel_scheduled_post

Cancels a scheduled post and moves it back to draft status.
InputTypeDescription
post_idstringThe post to un-schedule
This tool is idempotent: calling it on a post that is already in draft status returns success. Calling it on a post that has already been published returns 409 already_published.

​
publish_post_now

Publishes a post to LinkedIn immediately, ignoring any previously set schedule.
InputTypeDescription
post_idstringThe post to publish
Returns 409 already_published if the post is already live on LinkedIn. If your LinkedIn token has expired, returns actionable: true with a reconnect hint — surface this to the user and do not retry automatically.