sprkly.app-mcp

Two ways to authenticate. Pick by what your client supports.
- 1. Addhttps://sprkly.app/api/mcpas a custom connector.
- 2. Click Connect and approve the permissions.
- 3. Ask your agent what you have scheduled.Per-client setup, right below →

curl -s https://sprkly.app/api/mcp \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

TOKEN="sk_live_…" MCP="https://sprkly.app/api/mcp" # 1. Initialize (no credentials needed) curl -s "$MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize", "params":{"protocolVersion":"2025-11-25", "capabilities":{}, "clientInfo":{"name":"curl","version":"1.0"}}}' # 2. Which accounts can I post to? curl -s "$MCP" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2025-11-25" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name":"sprkly_list_profiles","arguments":{}}}' # 3. Check the caption before committing to it curl -s "$MCP" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call", "params":{"name":"sprkly_validate_post_policy", "arguments":{"caption":"Launch day.", "platforms":["instagram"], "mediaUrlsCount":1}}}' # 4. Queue it curl -s "$MCP" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":4,"method":"tools/call", "params":{"name":"sprkly_schedule_post", "arguments":{"caption":"Launch day.", "profile_ids":["profile_…"], "media_urls":["https://example.com/launch.jpg"], "scheduled_time":"2026-08-04T18:00:00.000Z"}}}'

Four things are always required: a caption, at least one platform, a time, and media for the platforms that demand it. Two platforms want more, andsprkly_schedule_postrefuses the call rather than guessing.

Array order is slide order.For a carousel or a photo set, the sequence you send inmedia_urlsormedia_idsis the sequence that publishes. Slide 1 carries the most weight: Instagram crops every other slide to match its shape, and Threads and Facebook publish only that one.

A file listing is not a sorted listing. Google Drive, Dropbox and most automation nodes return files in upload order, which rarely matches intent. Sort on the file name before you build the array, and name the files so that sorting works:01.jpg,02.jpg,03.jpg. Pad the zero, because as text10sorts before2. When the order was inferred rather than given, say so in the reply instead of presenting it as certain.

16 tools. Arguments below are exactly whattools/listreturns.

sprkly_add_media_from_urlWriteIdempotent

Download an image or video from a public link into sprkly and get a media_id back, for reuse across several posts. You usually do NOT need this: sprkly_schedule_post accepts a link directly in media_urls and pulls it into storage itself whenever the target platform requires that. Reach for this tool only when the user wants one media_id to attach to more than one post. Google Drive and Dropbox share links are converted automatically; the file must be shared publicly. Limit 50 MB.

You say“Use this clip for all three of this week posts:https://cdn.example.com/clips/launch.mp4”

sprkly_add_media_from_url({ "url": "https://cdn.example.com/clips/launch.mp4" })

sprkly_delete_scheduled_post({ "post_id": "post_abc123" })

sprkly_draft_post({ "content_hint": "first look at the new studio space", "platforms": [ "instagram" ], "tone": "casual" })

Plan tier, trial state, connected account count, scheduled post counts by status, and the next three upcoming posts. Never returns tokens or secrets.

You say“How is my sprkly account looking?”

How the user's published posts actually performed: total views and engagement, week-on-week / month-on-month / year-on-year change, their best posting hour, weekday and content category, and the top posts behind those numbers. Every recommendation carries a samples count — say how thin the evidence is rather than presenting a one-post pattern as a finding. Every period-on-period percentage carries the post counts and raw totals it came from: quote those, because a big percentage off a tiny base is not a big change. topPosts is grouped by platform and ranked only inside each group; relativeToPlatformBest compares a post with others on its OWN platform and never across platforms, so use the absolute value and its metric label to weigh one platform against another. Instagram contributes likes and comments only, and Threads and Facebook produce no metrics at all, so read coverage before comparing platforms.

You say“How did my posts do last month, and when should I be posting?”

sprkly_get_analytics({ "days": 30 })

Returns the numbers and the evidence behind them. The advice is yours to give: check samples and coverage before calling anything a pattern.

You say“Which of my TikTok posts worked best this week?”

sprkly_get_analytics({ "days": 7, "profile_ids": [ "prof_tiktok_main" ] })

Subscription status, current plan, period end, purchased handles and the last few billing events. No payment method details; the Stripe customer id is truncated.

You say“What plan am I on and when does it renew?”

sprkly_get_post_approval_statusRead-only

Whether a post is awaiting human review, approved or rejected, including reviewer notes and timestamps.

You say“Has the launch post been approved yet?”

sprkly_get_post_approval_status({ "post_id": "post_abc123" })

Full detail for one post: status, targets, scheduled and published times, permalink, and the failure reason if it did not publish. Media comes back as mediaIds in slide order, not as links. Ids and profile ids are plumbing: talk to the user about accounts by handle and about posts by their caption, and do not read ids out unless they ask for one.

You say“Did last night's reel actually go out?”

sprkly_get_post_status({ "post_id": "post_abc123" })

sprkly_get_tiktok_posting_optionsRead-only

This creator's allowed TikTok privacy levels and interaction settings, fetched live from TikTok. You usually do NOT need this before scheduling: sprkly_schedule_post checks privacyLevel against this same list itself and, when it is wrong, returns the levels that would work. Call this only when the user asks what their options are, or you want to offer them a choice.

You say“What privacy options do I have on TikTok?”

sprkly_get_tiktok_posting_options({ "profile_id": "prof_tt_studio" })

For showing the user their choices. Do NOT run it before sprkly_schedule_post as a matter of course: that call validates privacyLevel itself and names the allowed levels when one is wrong.

sprkly_list_connected_social_accountsRead-only

Every ACTIVE social account linked to this sprkly account: platform, handle, follower count, and whether it needs reconnecting. Disconnected/inactive accounts are never listed, so any profileId returned here is a valid posting target. Never returns access tokens.

You say“Which social accounts do I have connected?”

sprkly_list_connected_social_accounts({})

The profile ids needed to target a post, with each one's platform and handle. Call this before sprkly_schedule_post.

Agents call this first: the profile ids it returns are what sprkly_schedule_post targets.

The post queue, newest first, with a caption preview, targets, status and failure reason. Supports a status filter and cursor pagination.

You say“What have I got queued this week?”

sprkly_list_scheduled_posts({ "status": "scheduled", "limit": 20 })

Submit a draft post for human review. Moves the post to pending_approval and returns an approval id to poll with sprkly_get_post_approval_status. Use this when the user wants a person to sign off before anything publishes.

You say“Queue the week, but let me sign off before anything goes out.”

sprkly_request_post_approval({ "post_id": "post_abc123", "note": "Captions drafted from the Tuesday shoot. Check the TikTok hook." })

Queue a post for publishing, in ONE call. Attach media by passing the user's link straight to media_urls: sprkly downloads it into storage itself for the platforms that need that, so no upload tool has to run first. Runs the same quota, duplicate-content and platform pre-flight checks as the sprkly app. Instagram and TikTok require media at submission time; YouTube and TikTok require a title, and TikTok also requires platform_meta.tiktok.privacyLevel — just send the level the user asked for and this tool names the allowed values if it is not one of them. It reads the real bytes of the media and the response says what will actually publish on each platform (a Reel, a 3-slide carousel, a photo set, a Page feed video) plus anything worth passing on: relay that to the user. Confirm the date, time and target accounts with the user first. If a target platform has more than one connected account and profile_ids is not given, the tool returns needsAccountChoice with the options instead of scheduling — put that choice to the user, then re-call.

You say“Schedule this to Instagram and TikTok on Thursday at 6pm.”

sprkly_schedule_post({ "caption": "Behind the scenes of the studio setup", "platforms": [ "instagram", "tiktok" ], "scheduled_time": "2026-08-13T18:00:00+08:00", "media_id": "media_abc123", "title": "Behind the scenes of the studio setup", "platform_meta": { "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE" } } })

With two Instagram accounts connected, this returns needsAccountChoice and the agent asks: "You have 2 Instagram accounts, which one?" Then it re-calls with profile_ids. TikTok posts need a title and a privacyLevel from sprkly_get_tiktok_posting_options.

You say“Yes, the studio account. Same for TikTok.”

sprkly_schedule_post({ "caption": "Behind the scenes of the studio setup", "platforms": [ "instagram", "tiktok" ], "profile_ids": [ "prof_ig_studio", "prof_tt_studio" ], "scheduled_time": "2026-08-13T18:00:00+08:00", "media_id": "media_abc123", "title": "Behind the scenes of the studio setup", "platform_meta": { "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE" } } })

You say“Post these five cards as a carousel to Instagram and TikTok.”

sprkly_schedule_post({ "caption": "Five things nobody tells you about scheduling", "platforms": [ "instagram", "tiktok" ], "scheduled_time": "2026-08-14T09:00:00+08:00", "media_ids": [ "media_c1", "media_c2", "media_c3", "media_c4", "media_c5" ], "title": "Five things nobody tells you about scheduling", "platform_meta": { "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE" } } })

media_ids order is slide order, and the ids come from media already in sprkly. Had the user pasted five links instead, media_urls takes them in the same order and sprkly pulls each one in while scheduling.

You say“Post this to TikTok tomorrow at 9am, just to me for now:https://drive.google.com/file/d/1AbCdEf/view?usp=sharing”

sprkly_schedule_post({ "caption": "Testing the new scheduler", "platforms": [ "tiktok" ], "scheduled_time": "2026-08-16T09:00:00+08:00", "media_urls": [ "https://drive.google.com/file/d/1AbCdEf/view?usp=sharing" ], "title": "Testing the new scheduler", "platform_meta": { "tiktok": { "privacyLevel": "SELF_ONLY" } } })