Skip to content

Connections

Implemented

The connection lifecycle of supported channels, from the agent handoff to the owner consent, the saved status and the disconnect.

Provider connections start in the owner's browser. Agent tools return protected handoff URLs and saved metadata; they do not return OAuth state, tokens, or provider credentials.

Instagram, X, YouTube, TikTok, Facebook and Threads share one start link: /connect/{provider} with the workspace ID and a return page (setup or connections). The owner opens it and goes straight to the provider. The link starts an authorization and changes nothing until the owner approves at the provider. The provider state stores the return page as one of these two words, never as a URL.

get_onboarding_status.socialConnections reports saved social identities for the selected workspace. Each row names its provider. One connected row can exist per workspace and provider. The row does not prove current access or a publishing destination. Instagram has the owner selection flow below. TikTok publishing is in development. X customer publishing is available when configured. TikTok Ads access stays in the separate advertiser connection flow.

Instagram#

Call start_instagram_connection with one stable requestId, then give connectionUrl to the owner. The owner opens it and goes straight to Instagram to connect a professional account. An agent's request stays bound to its grant. Use get_instagram_connection or list_instagram_connections to resume and read the current lifecycle. Connected status does not prove video readiness or authorize publication.

The server checks Meta's returned grants and exact account IDs before it saves the connection. An unconfirmed result stays unconfirmed until the owner cancels the request and starts a new one.

For a post, prepare_instagram_destination opens /posts/review so the owner can select the account. Then call prepare_instagram_readiness and read get_instagram_readiness. A saved readiness result can become stale after media, draft, account, credential, or authority changes.

Updated 2026-11-12: with Publish and an automatic Reel, the agent does not use these two steps. It calls publish_instagram_reel or prepare_post_schedule, which use the one connected account; see Instagram. prepare_instagram_readiness still needs the account that the owner selected.

Instagram insights renewal is a separate optional grant. Denying it keeps a valid existing publishing connection. Stored insight permission does not prove a successful dashboard read.

Facebook Pages and Threads#

The owner connects these channels from Connections. Facebook returns authorized Page choices and requires an explicit Page selection. Threads verifies its own product identity and requires owner confirmation before a reconnect can replace the selected profile. They have no MCP start or publishing tool; get_onboarding_status.channels.startTool is null. Use the owner Connect link.

Facebook saves the end date of its User access, and the worker refreshes that access automatically while it ends in 30 days or less. Updated 2026-11-19: a Facebook connection whose access has ended, or whose saved credential is missing, reads reconnect-required in get_onboarding_status (channels[].state and socialConnections[].status). It no longer reads connected. A working connection reports the end date in socialConnections[].expiresAt. When the access ended, the owner uses the Facebook Connect link again. See Access lifetime and refresh.

Threads token expiry and data-access grant expiry are separate. Either expiry requires reconnect; a valid token does not extend an expired private-profile grant. Local disconnect removes app authority and fences late connection/refresh results. It keeps native posts. Provider-side revocation and provider-data erasure are separate flows. See Facebook Pages and Threads.

Updated October 11, 2026: the internal Meta erasure service requires a current authenticated owner and an exact saved product/app/connection authority set across affected workspaces, including each server-generated consent generation. Reusing a request or connection UUID cannot make an old binding select fresh consent. Its app and worker database roles are separate. It has no owner button or MCP tool. Updated 2026-10-12: six signed Meta callback routes start deauthorization or deletion; see Instagram, Facebook Pages and Threads. A verified deauthorization disconnects every matching connection and keeps history. A verified deletion request erases the subject for every owner that saved it, and one status link completes after the last owner. Live Meta acceptance remains unproved. A saved opaque token can open /data-deletion/{token}. This read-only page shows Pending, Processing or Completed through a separate status-only database role. It sends no account details, IDs, dates or token to page content, external assets or analytics. Unknown, malformed, expired and unavailable links show the same page. Links expire 30 days after completion. Reads cannot start or reopen deletion. Native callback acceptance remains unproved.

The approved erasure policy keeps independent owner uploads, draft text and business facts. Provider credentials, identities, avatars, cached metrics and result links are removed in the selected scope. Cached follow-up data cannot restore those fields after erasure or source removal. Manual owner metrics and valid unrelated evidence remain. An in-flight provider request can still finish; its late provider fields must not restore erased data or authorize a second send. A Reel finish acknowledgement alone keeps unknown status until native publication is proved. Neutral no-retry evidence lasts only while its retained owner post exists. Internal status needs current authentication and the opaque token; the token holder can read only neutral status, not the original owner's identity. It expires 30 days after completion; expiry cannot reopen work. Native social posts remain at the provider.

Updated 2026-10-16: erasure also covers scheduled posts. A pending schedule of an erased Instagram, Facebook or Threads account is cancelled and cannot send. The saved copy of its content and account is removed. A publication that was already created follows the rules above.

Updated 2026-10-18: the saved text generation records no longer exist, so erasure has no step for them.

Operator configuration uses SHIPCONTENT_META_LIFECYCLE_DATABASE_URL on the app and SHIPCONTENT_META_LIFECYCLE_WORKER_DATABASE_URL on the worker. The separate NOINHERIT logins have only shipcontent_meta_lifecycle or shipcontent_meta_lifecycle_worker, with no direct table access. Keep them separate from owner, agent and provider logins. Provision with SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_PASSWORD and SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_WORKER_PASSWORD plus the four Facebook/Threads bootstrap passwords. The worker cannot plan or start erasure.

TikTok Ads#

ads_start_connection returns /advertising/connect; the owner authorizes TikTok and selects advertisers. Use ads_list_connections, ads_get_connection, and ads_list_advertisers to inspect saved access. Provider reads need a current connection; saved status alone is not a live access check.

Only the owner can change connection state. connections:write is a defined server action, but it is not issued to the MCP client through the current owner grant options. Do not ask the owner for credentials in chat.

YouTube#

Use start_youtube_connection for the owner channel handoff and get_youtube_status for saved progress. The first channel is saved when Google returns it. A reconnect that returns a different channel waits for the owner's confirmation. One YouTube connection can coexist with Instagram. Disconnect removes local credentials and stops new uploads; it does not undo uploaded videos. See YouTube.

The TikTok organic channel is listed as Not configured. Its draft contract is available, but account authorization is in development. The existing advertiser connection cannot supply an organic publishing destination.

TikTok Accounts#

The owner opens /connect/tiktok from Connections to authorize one Personal/creator or Business account, subject to TikTok access. The server saves inspected app/account identity and granted scopes with encrypted tokens. A different reconnect account waits for confirmation. Agents can read safe metadata and use granted read capabilities; they cannot confirm or disconnect an account, or obtain its credentials. Disconnect stops local access and preserves saved media and posts. See TikTok setup.

Updated October 11, 2026: the operator provisions the separate public status login with SHIPCONTENT_BOOTSTRAP_META_STATUS_PASSWORD and sets its runtime URL as SHIPCONTENT_META_STATUS_DATABASE_URL on the app only. Keep the bootstrap password outside app and worker services. The status role has no table, provider or lifecycle authority.

Updated 2026-10-16: In enforce mode, the final Instagram, X, YouTube, TikTok, Facebook or Threads save checks the owner's connected-channel limit across active owner workspaces. Starting OAuth or listing Facebook Page choices does not use capacity. A connected replacement uses its net increase; a reconnect-required connection uses a new place. Refusal preserves the previous saved connection and credentials. Disconnect and erasure can reduce usage above the limit.