MCP Tools Reference

The schedpilot-mcp package exposes six tools to MCP-compatible AI agents. This page documents each tool's inputs, outputs, and typical usage patterns.

All tools authenticate using the SCHEDPILOT_TOKEN environment variable. Both API keys (smm_...) and OAuth tokens (sp_tok_...) are accepted.

Tool 1: get_accounts​

Retrieve all social media accounts connected to the authenticated SchedPilot user.

Inputs​

This tool takes no input parameters.

Returns​

An array of connected account objects.

Example agent prompt​

"Show me all my connected SchedPilot accounts."

Tool 2: list_posts​

Retrieve a paginated list of posts, optionally filtered by status or date range.

Inputs​

Returns​

A paginated list of post objects, each including post_id, content, platform, account_id, status, scheduled_date, and (for published posts) platform_post_id.

Example agent prompts​

"Show me my last 5 scheduled posts."

"List all posts that failed to publish this week."

"Show me everything scheduled between June 1 and June 7."

Tool 3: create_post​

Schedule a new post on one or more connected accounts.

Inputs​

Returns​

The newly created post object, including the assigned post_id.

Example agent prompts​

"Schedule a tweet saying 'Big news tomorrow!' for June 20 at 9am Eastern time."

"Post the image I just uploaded to both my Twitter and LinkedIn accounts at noon UTC today."

Tool 4: delete_post​

Delete a scheduled or draft post. Published posts cannot be deleted through the API.

Inputs​

Returns​

A confirmation object indicating the post was deleted.

Example agent prompts​

"Delete post 1042."

"Cancel the tweet I just scheduled — delete post 1055."

Tool 5: upload_media​

Download a publicly accessible image or video from a URL and add it to the SchedPilot media library. Returns a media_id that can be used in create_post.

Inputs​

Returns​

An object with media_id, type ("image" or "video"), and mime_type. Pass the media_id to create_post.

Example agent prompts​

"Upload the image at https://example.com/promo.jpg so I can use it in a post."

"Fetch the video from https://cdn.example.com/demo.mp4 and schedule a LinkedIn post with it."

Tool 6: get_analytics​

Retrieve engagement analytics for a published post.

Inputs​

Returns​

An analytics object containing platform-reported metrics such as impressions, likes, shares, comments, and clicks (fields vary by platform).

Example agent prompts​

"Get the analytics for post 987."

"How did my tweet from last Monday perform? The post ID is 1001."

Typical Agent Workflows​

Workflow A: Schedule a tweet with an image​

This is the most common multi-step workflow. The agent calls three tools in sequence:

1. get_accounts
   → finds the Twitter account id (e.g. id: 3, type: "twitter")

2. upload_media  { url: "https://example.com/banner.jpg" }
   → returns { media_id: "image-55", type: "image", ... }

3. create_post  {
     content: "Check out our summer sale! 🌞",
     scheduled_date: "2024-06-20 09:00:00",
     timezone: "America/New_York",
     accounts: [{ id: 3, type: "twitter" }],
     image_ids: ["image-55"]
   }
   → returns { post_id: 1099, status: "scheduled", ... }

Workflow B: Review analytics on recent posts​

1. list_posts  { status: "posted", per_page: 5 }
   → returns 5 recently published posts with their post_ids

2. get_analytics  { post_id: 1085 }
3. get_analytics  { post_id: 1086 }
4. get_analytics  { post_id: 1087 }
   → agent compares engagement across posts and summarizes for the user

Authentication Note​

All six tools read the SCHEDPILOT_TOKEN environment variable set in your MCP client config. You do not need to pass the token as a tool parameter — it is handled transparently by the MCP server.

Both authentication methods work: