# VixAI Connect — complete agent documentation

VixAI Connect is a remote MCP server that gives AI assistants an authorized route to social publishing. It is designed for a two-part operating model: the agent creates and coordinates work; the human owns the account, social connection, permissions, and final approval.

Canonical MCP endpoint: https://mcp.vixai.app/mcp
Canonical resource identifier: https://mcp.vixai.app
OAuth issuer and authorization server: https://social.vixai.app
Protected-resource metadata: https://mcp.vixai.app/.well-known/oauth-protected-resource
Authorization-server metadata: https://social.vixai.app/.well-known/oauth-authorization-server
Public capability manifest: https://mcp.vixai.app/capabilities
Human documentation: https://vixai.app/en/developers/

## Protocol and identity

The server uses MCP Streamable HTTP and OAuth 2.1 Authorization Code with PKCE S256. The authenticated identity always comes from the bearer token. Tools never accept a user ID, Meta token, Instagram password, or social credential as an argument. Access tokens are short-lived, audience-bound, and scope-limited. Refresh tokens are opaque, rotating, hashed at rest, and revocable. A verified VixAI email is required to grant publishing and scheduling access.

Supported OAuth scopes:
- social.accounts.read
- social.posts.read
- social.posts.write
- social.posts.publish
- social.posts.schedule

## Supported clients and destinations

VixAI Connect is currently used with ChatGPT, Claude, Grok, and standards-compatible remote MCP clients. Instagram is the first MCP publishing destination. The wider VixAI web product also manages additional social networks, but agents must rely on the live MCP tools/list response and must not infer an unavailable MCP tool.

## Media and beta limits

A draft accepts one image, one Reel, or one ordered carousel with 2–10 images. Images may be JPEG, PNG, or WebP up to 10 MiB each and are normalized to compatible JPEG sRGB. Reels may be MP4 or MOV up to 200 MiB and are validated and normalized when required. VixAI never silently crops incompatible content. The free beta permits 10 accepted publication or scheduling actions per user in a rolling 24-hour window. A schedule must be at least 2 minutes and at most 30 days in the future.

## Recommended tool sequence

1. Call list_social_accounts before creating content when the destination is not already known.
2. For one existing image or Reel passed directly by the client, call create_post_draft. For 2–10 attached images that belong in one ordered carousel, call create_carousel_post_draft.
3. When ChatGPT or Grok generates 2–10 images natively and exposes temporary HTTPS URLs, call create_carousel_post_draft_from_urls in final slide order. Prefer native client generation unless the user explicitly requests VixAI generation. VixAI imports and stores the normalized images; the source URLs are not persisted.
4. When a client cannot pass attachments, call create_media_upload with image, carousel or reel, ask the user to complete the secure VixAI upload, then call create_post_draft_from_upload.
5. For one original image generated by VixAI, call generate_image_post_draft with a stable request_id. For a complete 2–10 slide carousel generated by VixAI, call generate_carousel_post_draft with one coherent carousel brief, one prompt per slide, and a stable request_id. This is the preferred creation route for Claude, which does not provide native image generation to this connector. Do not request manual uploads in either VixAI generation flow.
6. Use get_post_draft when the draft must be reviewed again.
7. Call prepare_post_action with the post revision and the intended action. For scheduling, provide an ISO 8601 timestamp with timezone.
8. Show the complete immutable preview to the human: account, media, full caption, action, and schedule time when present.
9. Call publish_post or schedule_post only after the human explicitly approves that exact preview.
10. Use get_post_status to follow queue and provider processing. A confirmed schedule remains in VixAI's durable queue even after the assistant closes.

## Tool catalog

list_social_accounts: read-only. Lists only social accounts owned by the bearer-token user.
create_post_draft: creates a draft from one attached image or Reel. Does not publish or schedule.
create_carousel_post_draft: creates one ordered Instagram carousel draft from 2–10 attached images. Does not publish or schedule.
create_carousel_post_draft_from_urls: imports 2–10 temporary HTTPS image URLs generated by the AI client and creates one ordered carousel draft without consuming VixAI generation credits. Source URLs are not persisted.
create_media_upload: creates an authenticated, temporary upload flow for clients that cannot forward files. Does not create a post by itself.
generate_image_post_draft: generates an original image in VixAI and creates a draft. It consumes VixAI image-generation credits but does not publish.
generate_carousel_post_draft: generates 2–10 original, visually coherent images in VixAI and creates one ordered carousel draft. It costs 2 VixAI credits per slide and is the preferred creation route for Claude or any client without native image generation.
create_post_draft_from_upload: consumes a completed secure upload and creates a draft.
get_post_draft: read-only. Returns the draft, media summary, revision, and status.
prepare_post_action: creates a short-lived immutable preview and single-use intent. It does not publish or schedule.
publish_post: external action. Requires explicit approval of the corresponding prepared intent.
schedule_post: external future action. Requires explicit approval of the corresponding prepared intent.
cancel_scheduled_post: destructive action. Cancels only before publication has started.
get_post_status: read-only. Returns draft, scheduled, queued, publishing, published, failed, or cancelled state as applicable.
list_posts: read-only. Lists recent drafts and posts owned by the authenticated user.

## Confirmation and idempotency

Draft creation and preview preparation must never be treated as approval. Publishing and scheduling consume a short-lived action intent tied to the exact post revision and action. The consumed intent also acts as an idempotency boundary, so a retry cannot create a second accepted action. Single-image and complete-carousel VixAI generation use a caller-provided stable request_id for safe retry. Provider processing may continue after a tool response; agents should query status rather than creating a replacement post blindly.

## Error handling

An authentication or scope failure requires a new OAuth authorization flow, not a social credential in chat. A media-validation error is correctable and should be presented to the user without calling publish. If a provider action has already been accepted, a later provider failure still consumes the beta quota. On uncertain publication state, call get_post_status before preparing or accepting another action. Never expose tokens, temporary file URLs, internal database IDs, or debug payloads to users.

## Human control plane

The VixAI web application at https://social.vixai.app is where people create accounts, verify email, connect Instagram, inspect status, revoke AI connections, and manage their content. AI clients are execution interfaces, not credential owners. The human may connect multiple supported assistants to the same VixAI account; each client receives its own revocable grant.

## Sources of truth

The live MCP initialize and tools/list responses are authoritative for executable protocol features, names, schemas, annotations, and current availability. This file and the VixAI JSON capability manifest are documentation surfaces intended to improve discovery and planning. They do not replace OAuth discovery or MCP negotiation.