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

# MCP overview

> What the MagicPost MCP server is and how it fits into your LLM client.

The MagicPost MCP server lets any [Model Context Protocol](https://modelcontextprotocol.io)
client — Claude Desktop, Cursor, claude.ai, custom agents — operate your
MagicPost account from within a conversation, without leaving the chat.

## What it does

* **Generates** posts in your own voice — or in an imported creator's writing style
* **Reads** your analytics, lists your draft / scheduled / published posts
* **Writes** new drafts, schedules posts (same-day & exact-slot warnings), cancels, publishes now
* **Attaches media** supplied by the chat to a draft before scheduling or publishing
* **Finds inspiration** in a global catalogue of high-performing posts
* **Detects & manages leads** from your posts' engagement, scored against your ICPs and synced to your CRM
* **Manages your org** (super\_admins) — read teammates' analytics and posts, schedule on their behalf
* **Refreshes** your LinkedIn data and waits for completion

It's a thin, stateless proxy over our [REST API](https://dev.magicpost.in/api-reference/overview.md).
Everything you can do with curl, you can do via the MCP — just from an LLM
conversation.

## Architecture

```
   ┌─────────────────────┐
   │   MCP client        │  Claude Desktop, Cursor, claude.ai, ...
   │  (your LLM tool)    │
   └──────────┬──────────┘
              │  HTTPS, Authorization: Bearer mp_*
              ▼
   ┌─────────────────────┐
   │ mcp.magicpost.in    │  Validates the PAT (cached 60s),
   │  (MCP server)       │  forwards calls to api.magicpost.in
   └──────────┬──────────┘
              │  HTTPS, same PAT
              ▼
   ┌─────────────────────┐
   │ api.magicpost.in    │  Our Flask backend.
   │  /api/v1/*          │  Runs your operation against Supabase,
   └─────────────────────┘  Airtable, LinkedIn OAuth tokens, etc.
```

## Endpoint

```
https://mcp.magicpost.in/mcp
```

Transport: `streamable-http` (current MCP standard, stateless mode,
JSON responses).

## Available tools

The server exposes 38 tools — see the full [catalog](https://dev.magicpost.in/mcp/tools.md).

#### Generation & styles

| Tool | Purpose |
| - | - |
| `generate_post` | Generate a new LinkedIn post and persist it as a draft. |
| `list_my_writing_styles` | List the LinkedIn profiles the user has imported as writing-style candidates, including which one is currently active in the UI. |
| `find_writing_style_profile` | Search the global LinkedIn profile catalog by name or LinkedIn URL. |
| `add_writing_style_profile` | Attach a LinkedIn profile to the user's account as a writing-style candidate, scraping its posts if needed. |

#### Posts

| Tool | Purpose |
| - | - |
| `list_my_posts` | List the user's posts filtered by lifecycle status. |
| `get_post` | Fetch the full record for a single MagicPost owned by the user. |
| `create_or_update_post` | Create a new draft post (no post\_id) or update an existing one's text. |
| `attach_media_to_post` | Attach one chat-provided image, video, or PDF to a draft. |
| `prepare_post_media_upload` | Prepare a short-lived upload for a local image, video, or PDF. |
| `complete_post_media_upload` | Validate an uploaded local file and attach it to its draft. |
| `update_post_media` | Edit an existing draft attachment without losing its scheduled comments. |
| `score_post` | Run MagicPost's Post AI score on a LinkedIn post: the same scan as the editor's "Score IA". |

#### Ideas

| Tool | Purpose |
| - | - |
| `add_idea_to_notebook` | Save a post idea to the user's MagicPost Idea notebook, to write later. |

#### Scheduling

| Tool | Purpose |
| - | - |
| `schedule_post` | Schedule a post for future publication on LinkedIn. |
| `cancel_scheduled_post` | Cancel a scheduled post. |
| `publish_post_now` | Publish a post to LinkedIn immediately (no schedule). |
| `schedule_post_comment` | Arm a comment that MagicPost publishes on LinkedIn under the user's post, `minutes_after` minutes after the post goes live (0 = right after publication). |
| `delete_post_comment` | Remove a comment armed with schedule\_post\_comment, before it is published on LinkedIn. |

#### Comments

| Tool | Purpose |
| - | - |
| `list_received_comments` | List the comments people left on one of the user's published LinkedIn posts: text, author (name, headline, profile URL), date, and whether it is a reply (with its parent comment). |
| `sync_received_comments` | Fetch the latest comments of one of the user's published posts from LinkedIn (through MagicPost's data provider), in the background. |

#### Analytics

| Tool | Purpose |
| - | - |
| `list_linkedin_post_metrics` | List per-post LinkedIn metrics for an inclusive date range. |
| `get_metrics_summary` | Get a compact summary of the user's LinkedIn analytics. |
| `get_metrics_freshness` | Check when LinkedIn post metrics were last updated. |
| `refresh_my_posts` | Trigger a fresh pull of the user's LinkedIn posts and wait until done. |

#### Inspiration

| Tool | Purpose |
| - | - |
| `search_inspiration_posts` | Search the global LinkedIn inspiration catalogue (NOT the user's own posts) for high-performing examples to draw inspiration from. |

#### Leads & CRM

| Tool | Purpose |
| - | - |
| `list_leads` | List the user's LinkedIn leads (prospects detected from the engagement on their posts and qualified against their ICPs). |
| `get_lead` | Full detail of one lead: profile, interactions (likes/comments on the user's posts), qualification reasoning, icebreaker, and CRM sync state (`deliveries` to connected external CRMs). |
| `list_icps` | List the user's ICPs (Ideal Customer Profiles). |
| `get_leads_summary` | Leads quota status: trial state (is\_trial, trial\_days\_remaining, trial\_ends\_at), monthly quota (leads\_monthly\_included, leads\_consumed\_in\_period, leads\_remaining), top-ups (topup\_leads\_remaining, topups\_detail), and renewal date (period\_end). |
| `get_detection_status` | Poll the status of running lead detections (they are async and typically take 2-15 minutes). |
| `detect_leads` | Detect new leads from the engagement (likes + comments) on one of the user's LinkedIn posts. |
| `update_lead` | Update a lead's pipeline fields. |

#### Org / team

| Tool | Purpose |
| - | - |
| `list_org_members` | List the active members of your organisation. |
| `get_org_metrics_summary` | Compact analytics for the org or one specific member. |
| `list_org_member_posts` | List posts across the org, optionally scoped to one member. |
| `get_org_member_post` | Fetch the full record of ONE post owned by a member of your org. |
| `create_member_post` | Create a draft owned by a specific organisation member. |
| `schedule_member_post` | Schedule a post on behalf of an org member. |

## What it does NOT do (yet)

* **Media library browsing** — the MCP can attach a file supplied by the chat
  host or uploaded from a supported local client, but it cannot search or reuse
  media already stored in MagicPost.
* **Multiple media files** — one image, video, GIF, or PDF can be attached to a
  draft.
* **@mentions** that need LinkedIn tag resolution — the LLM cannot pick the
  right LinkedIn profile from a name. Finalize @mentions in the web UI.

Most tools are scoped to your own account. Org `super_admins` additionally
get read/scheduling access to their teammates' posts and analytics via the
`*_org_*` / `*_member_*` tools.

## Next steps

> [card] [Setup Claude Desktop](https://dev.magicpost.in/mcp/setup-claude-desktop.md)
>
> The flagship LLM client.

> [card] [Setup Claude Code](https://dev.magicpost.in/mcp/setup-claude-code.md)
>
> Remote MCP with local-file media uploads.

> [card] [Setup Cursor](https://dev.magicpost.in/mcp/setup-cursor.md)
>
> Same backend, IDE workflow.

> [card] [Tool catalog](https://dev.magicpost.in/mcp/tools.md)
>
> Inputs, outputs, examples for the 38 tools.

> [card] [Attach media](https://dev.magicpost.in/mcp/media-attachments.md)
>
> Add a chat-provided or local image, video, GIF, or PDF before publishing.

> [card] [API reference](https://dev.magicpost.in/api-reference/overview.md)
>
> The REST endpoints behind the MCP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.