Reference

MCP tools reference

The 19 owner-scoped FavStash tools and their current calling conventions.

The generic hosted /mcp endpoint exposes 19 owner-scoped tools. ChatGPT uses /chatgpt/mcp, with 24 tools including account-resolution, analytics, and draft-review helpers plus inline widgets. Your AI discovers the current catalogue automatically with tools/list.

Setup instructions live in AI Connect. MCP and ChatGPT access are free on every plan. Analytics calls are not metered separately; the free plan includes one connected channel and a 7-day history window.

Saved content#

Tool	Use it for	Main input
`search_saved_content`	Find saves by meaning, creator, topic, hook, transcript, or on-screen text	`query`; optional filters and `limit`
`list_recently_saved_content`	List saves newest-first or within a date range	Optional `since`, `until`, `collectionId`, `limit`
`get_saved_content`	Open one known save and optionally retrieve its full transcript/text	`id`; optional `includeFullText`, `textLimit`
`save_content_url`	Save one public URL for asynchronous metadata and enrichment	`url`, `clientRequestId`; optional `collectionId`, `userNote`
`get_stash_summary`	Count saves without retrieving their text	Optional date/collection filters
`list_stash_collections`	Resolve collection names to IDs	Optional `limit`
`list_stash_tags`	Resolve user-created tag names to IDs	Optional `limit`

Call list_connected_social_accounts before an account-dependent core tool so the agent uses a current, owner-scoped connectionId. If it returns connectionRequired: true, open the returned connectUrl and connect Instagram, YouTube, TikTok, or LinkedIn before asking for scheduling. Analytics requests require an analytics-capable provider; LinkedIn personal profiles are publishing-only.

Tool	Use it for	Main input
`list_connected_social_accounts`	Discover valid account IDs or the FavStash setup link when no account is connected	None
`get_social_account_analytics`	Aggregate totals and reported trends for exactly one account	`connectionId`; optional `days` (1–90, plan-capped)
`analyze_social_content_performance`	Rank one account, inspect one item, or compare typed account queries	`connectionId` + `platform`; `providerContentId`; `favstashPostId`; or `queries[]`
`get_account_plan_and_usage`	Check live plan capacity before batch work	None

analyze_social_content_performance includes content not published through FavStash. Each result keeps the native ID, title/caption/description, permalink, publish date, thumbnail, and available metrics together. Provider limitations are stated explicitly; unavailable metrics are not represented as zeros. Ranked-list mode accepts portable sort keys for views, reach, interactions, watch time, average viewing, and subscribers gained; provider-unavailable metrics fail clearly instead of silently returning discovery order.

For the generic MCP endpoint, a multi-account or cross-platform comparison is one analyze_social_content_performance call containing two to six typed entries in queries[]. Keep each row attached to its account and platform: cross-platform metrics are directional rather than directly equivalent.

Planning and publishing#

Tool	Use it for	Main input
`get_social_publishing_options`	Fetch current provider content types, privacy choices, declarations, quota, and media requirements	`connectionId`; optional media type/duration
`import_post_media`	Copy media into stable owner-scoped storage when explicit staging is needed	Hosted generic: HTTPS `url`; ChatGPT: native file; local bridge: `url`, `path`, or `files[]`
`create_social_post`	Create a planned draft, future schedule, or immediate publish across one or more accounts	`clientRequestId`, typed `targets[]`; exactly one of `draft`, `publishAt`, `postNow`
`list_social_posts`	List planned drafts and publish-time posts in one calendar range	Optional range, state, account, limit
`get_social_post`	Poll one post for current state, release URL, warnings, or errors	`id`
`update_social_post`	Move a draft's planned day or edit a post before its publishing window	`id`, `expectedUpdatedAt`; changed fields and optional typed `target`
`cancel_social_post`	Cancel a draft, queued, or paused post	`id`
`search_instagram_audio`	Find audio for a compatible single-video Instagram Reel	`connectionId`; optional query/type

Call get_social_publishing_options before provider-sensitive publishing. Publishing, updates, and cancellations require confirmation unless the user already authorized the exact action.

Requests, retries, and channel variants

Give save_content_url and create_social_post a stable clientRequestId. Use a UUID or another 16–128 character key using letters, numbers, :, _, or -, beginning with a letter or number. Reuse it only for an exact retry; changed content needs a new key. A changed create request under the same key returns IDEMPOTENCY_KEY_REUSED.
Before update_social_post, read the post with get_social_post or list_social_posts and pass its updatedAt as expectedUpdatedAt. If someone edited it meanwhile, SOCIAL_POST_VERSION_CONFLICT means read it again and review the newer content before retrying.
Each create target contains connectionId, platform, and that platform's typed settings. Top-level content and media are shared defaults; targets[].content and targets[].media override them for one destination. Updates operate on one post and use singular target; omitted settings are preserved, while target.clearSettings removes supported optional values.
LinkedIn personal-profile targets accept text, 1–20 JPEG/PNG images, one MP4, or one PDF document. Use kind: "document" and a descriptive title for a PDF, and do not mix it with other attachments. Documents are LinkedIn-only.
Local upload limits are 8 MB per image, 200 MB per video, 100 MB per PDF, and 2 MB per JPEG/PNG thumbnail. Provider-specific limits may be lower; use get_social_publishing_options for the current destination requirements.

Local files and attachments

The generic hosted MCP tool does not accept a local filesystem path or raw file bytes. Its url must be an HTTPS media location that FavStash's backend can fetch. Do not interpret the word “attached” as a generic hosted capability.

The ChatGPT profile is different: ChatGPT supplies attached or generated files as temporary downloadable descriptors, and FavStash imports them without asking the user to host them. Web and mobile upload local files through their own first-party upload client.

Filesystem-capable agents use a separately installed local @sketric/favstash-mcp stdio bridge; see availability and setup. They can pass localPath and thumbnailPath directly to create_social_post or update_social_post; the bridge validates and uploads the files inside that single call. It also supports import_post_media.path and ordered files[] for explicit staging. A generic agent must not extract its MCP bearer credential, call FavStash's REST routes directly, or open the web composer as an upload workaround.

plannedDate is a date-only YYYY-MM-DD value accepted only for DRAFT posts. It places an idea in the calendar without creating a publishing job. Supplying publishAt later turns that draft into a real schedule.

Saved-content enrichment

New eligible video saves can use in-house transcription, with provider fallback when needed. get_saved_content reports available recreation signals such as creativeFormat, onScreenText, visualSummary, and visualAnalysisSource. These fields depend on processing results and can be absent on older saves. Full enrichment follows the plan allowance; an absent transcript is not permission to infer spoken content.

Conventions#

Timestamps are UTC ISO 8601 (2026-07-10T18:30:00Z).
Social post states are DRAFT, QUEUE, PROCESSING, PAUSED, PUBLISHED, ERROR, and CANCELLED.
Owner enforcement is server-side; tools never accept a user ID.
Long saved-content text is bounded by default. availableTextFields tells an agent whether a full-text follow-up is useful.
Normalized analytics metrics carry key, label, value, and grain, plus optional unit and date.
Analytics results can include machine-readable nextActions that identify the correct follow-up tool and arguments.
Tool errors are returned as inspectable tool results so an agent can correct its inputs; malformed JSON-RPC remains a protocol error.