MCP Server

Endpoint

The MCP endpoint is available at the root /mcp path, not under /api. Use your API key as a Bearer token for authentication.

Ampost uses the Streamable HTTP transport on this single endpoint. Clients initialize with POST /mcp, then continue the same session on GET, POST, and DELETErequests by sending the returned Mcp-Session-Id header.

Available Tools

Authentication

The MCP endpoint uses the same Bearer token authentication as the REST API. Pass your API key in the Authorization header. Ampost keys are scope-free, so tool access is determined by the public MCP surface and your plan limits rather than key-level permissions.

{
  "mcpServers": {
    "ampost": {
      "url": "https://api.ampost.io/mcp",
      "headers": {
        "Authorization": "Bearer amp_live_YOUR_KEY"
      }
    }
  }
}

Use the hosted API domain configuration above. Ampost does not require a local npm-based MCP wrapper command, and dashboard or OAuth flows remain on https://ampost.io.

Post Creation

posts_create takes platform names plus a required platformSetId. Supported platforms are instagram, facebook, linkedin, tiktok, threads. The tool resolves the active connection for each requested platform from the selected platform set, so you do not pass connection IDs in the create payload. Use accounts_list to inspect which active connections are available inside a set, and use platformOverrides to set per-platform text, LinkedIn member-post settings, or creator controls.

TikTok requires explicit media descriptors. LinkedIn also requires explicit descriptors for video and is safest when all LinkedIn media is sent that way. When you target tiktok or LinkedIn video, send media through a media array with url, type, mimeType, sizeBytes, and video durationSeconds when relevant. Bare mediaUrls are kept only for legacy simple cases and are rejected for TikTok and LinkedIn video.

TikTok and LinkedIn posts can be drafted, published immediately, or scheduled. When MCP clients send a future scheduledFor value with media, Ampost copies the referenced media into Blob storage before storing the post. Do not use text-only TikTok payloads because TikTok requires photo or video media.

TikTok visibility is also app-state sensitive. MCP clients should inspect accounts_list or accounts_get for the current creator privacy options and treat private-only visibility as a valid launch posture when the connected TikTok app is still in audit or Direct Post review.

MCP clients should treat LinkedIn as member-profile publishing only: no organization/Page posting and no promise of analytics, comments, or read APIs beyond the stored account metadata returned by accounts_list.

{
  "text": "TikTok launch clip",
  "platforms": ["tiktok"],
  "scheduledFor": null,
  "media": [
    {
      "url": "https://cdn.example.com/launch.mp4",
      "type": "video",
      "mimeType": "video/mp4",
      "sizeBytes": 18432000,
      "fileName": "launch.mp4",
      "width": 1080,
      "height": 1920,
      "durationSeconds": 24
    }
  ],
  "platformOverrides": {
    "tiktok": {
      "settings": {
        "privacyLevel": "SELF_ONLY",
        "disableComment": true,
        "brandContentToggle": true
      }
    }
  },
  "platformSetId": "set_uuid"
}

LinkedIn Publishing

LinkedIn MCP posts can be text-only, image, article, or single-video posts. Put LinkedIn-specific text overrides in platformOverrides.linkedin.text and LinkedIn-specific settings in platformOverrides.linkedin.settings. Supported settings include visibility, isReshareDisabledByAuthor, articleTitle, articleDescription, and videoTitle. Organization posting, analytics, and comment-management APIs remain outside the current launch surface.

Explicit media descriptors are recommended for all LinkedIn media and required for LinkedIn video. Bare mediaUrls remain available only for legacy image-only payloads and are rejected for video-like URLs.

{
  "text": "Shipping the new LinkedIn contract today.",
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "platformOverrides": {
    "linkedin": {
      "settings": {
        "visibility": "PUBLIC",
        "isReshareDisabledByAuthor": true
      }
    }
  },
  "platformSetId": "set_uuid"
}

{
  "text": "LinkedIn image post",
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "media": [
    {
      "url": "https://cdn.example.com/product-shot.png",
      "type": "image",
      "mimeType": "image/png",
      "sizeBytes": 248120,
      "fileName": "product-shot.png",
      "width": 1600,
      "height": 900,
      "altText": "Product dashboard with the LinkedIn publish flow open."
    }
  ],
  "platformOverrides": {
    "linkedin": {
      "settings": {
        "visibility": "CONNECTIONS"
      }
    }
  },
  "platformSetId": "set_uuid"
}

{
  "text": "LinkedIn demo clip",
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "media": [
    {
      "url": "https://cdn.example.com/demo.mp4",
      "type": "video",
      "mimeType": "video/mp4",
      "sizeBytes": 18432000,
      "fileName": "demo.mp4",
      "width": 1920,
      "height": 1080,
      "durationSeconds": 38,
      "thumbnailUrl": "https://cdn.example.com/demo-thumb.jpg"
    }
  ],
  "platformOverrides": {
    "linkedin": {
      "settings": {
        "visibility": "PUBLIC",
        "videoTitle": "Ampost LinkedIn demo"
      }
    }
  },
  "platformSetId": "set_uuid"
}

{
  "text": "This will be rejected",
  "platforms": ["linkedin"],
  "mediaUrls": ["https://cdn.example.com/demo.mp4"],
  "platformSetId": "set_uuid"
}

The invalid example fails validation because LinkedIn video posts must use explicit media metadata.

Placement

Control how content appears on Instagram and Facebook using the platformOverrides parameter in posts_create. Pass placement in the settings object:

{
  "platformOverrides": {
    "instagram": {
      "settings": { "placement": "reel" }
    },
    "facebook": {
      "settings": { "placement": "feed" }
    }
  }
}

Instagram placements: feed, story, reel, carousel. Facebook placements: feed, story, reel. Placement is validated against the media configuration (e.g. carousel requires 2+ images, reel requires exactly one video).

Browser-assisted account connection

When hosted connection rollout is enabled, call accounts_connect with one of instagram, facebook, linkedin, tiktok, threads and an optional platformSetId. The tool uses the same service, ownership checks, plan feature, quota checks, expiry semantics, and connectPlatform rate limit as REST.

{
  "platform": "instagram",
  "platformSetId": "22222222-2222-4222-8222-222222222222"
}

Show connectRequest.connectUrl to the user and tell them to open it in a browser. Social consent cannot be completed by the agent or inside the conversation. After the user finishes the Ampost-hosted confirmation and provider flow, poll every 2–5 seconds:

{
  "connectRequestId": "11111111-1111-4111-8111-111111111111"
}

Status is exactly one of pending, awaiting_selection, connected, failed, or expired. A connected result includes connectionId, which can be passed to accounts_get. Status uses the apiRead rate limit and remains available for recovery while creation is disabled.

Never ask the user to paste an access token, OAuth authorization code, password, state value, URL fragment, or Facebook Page token into chat. The create URL is returned once; status output contains only safe Ampost error codes and never provider credentials or raw provider errors.

This MVP does not add profiles, webhooks, customer callbacks, custom redirects, headless authorization, or public reconnect, disconnect, and refresh tools. Facebook Page selection stays in the Ampost-hosted browser UI. Creation is not listed as an available MCP tool while PLATFORM_CONNECT_ENABLED is false; an operator enables it only after live smoke verification.

Platform Sets

Group connected accounts into named sets for organized multi-account management. Use platform_sets_list to view your sets, platform_sets_create to create new ones (max 20), platform_sets_rename to rename any set, and platform_sets_delete to delete a set when at least one other set remains (revoking all active connections within it).

Pass platformSetId in posts_create or posts_update to scope a post to a specific set. Filter posts with posts_list and accounts with accounts_list by platformSetId.

{
  "platform_sets_create": { "name": "Client A" },
  "accounts_list": { "platformSetId": "set_uuid" },
  "posts_list": { "platformSetId": "set_uuid", "platform": "threads" }
}

accounts_list and accounts_get include scopes, platform set membership, token health, and non-secret platform metadata. For TikTok this lets agents inspect creator privacy options and max video duration before attempting a publish.

Post Update

posts_update modifies a draft or scheduled post. You can update text, platforms, schedule, media, platformOverrides, and platformSetId. If you change the set or platforms, Ampost re-resolves the active connections from that selected platform set.

For TikTok updates, keep using explicit media objects so Ampost can validate media type, duration, and creator restrictions before publish.