🆕 MCP Server

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants and automation tools to call external services as native tools — no copy-pasting, no custom integrations. When you connect Swonkie via MCP, your AI agent can query your analytics, manage posts, move content through approval workflows, and publish — all from a natural conversation or automated workflow.

Swonkie's MCP server uses the Streamable HTTP transport, which means it works in cloud-hosted AI tools (Claude.ai, ChatGPT) and local clients (Claude Desktop, n8n) without running any local process.

What You Can Do

Once connected, an AI agent can:

List your connected social profiles and competitor profiles

Discover which analytics metrics are available per network, then pull daily analytics and per-post insights for any profile or competitor

Create, update, and delete posts (with per-network captions, media, and platform-specific options)

Look up the merged platform limits (caption length, media counts, sizes, ratios, duration) before composing a post

Schedule posts, send them for team review, approve or reject them

Manage your media library: upload files, import media straight from a public URL, and reference images/videos in posts

Generate production-ready images from a text prompt with Andie, Swonkie's AI assistant

Create and list labels for content organisation

Prerequisites

A Swonkie workspace with API access enabled

An API client created at Settings → Workspace → API

A visible API key — keys are only shown immediately after creation or after a rotation. If your key is hidden, rotate it to reveal a new one.

Your MCP Server URL

https://mcp.swonkie.dev/mcp?apiId=YOUR_APP_ID&apiKey=YOUR_API_KEY

You have two URLs — one per key slot (Primary and Secondary). Use different URLs for different clients so you can rotate one independently without breaking the other.

Security: Treat the MCP URL like a password. It contains your live API key embedded in the URL. Do not share it publicly or commit it to version control.
We will add OAuth support soon.

Find your App ID and keys at Settings → Workspace → API. The MCP URL is displayed automatically once your API client is set up.

Available Tools

The Swonkie MCP server exposes 24 tools organised into six groups.

Profiles

Tool	What it does
`swonkie_profiles_list`	Lists your connected social profiles. Supports pagination (`skip`, `take` up to 20), text search, and filtering by network. Profile IDs from this tool are required by the analytics and post tools.
`swonkie_competitors_list`	Lists monitored competitor profiles. Same parameters as `swonkie_profiles_list`. Competitor IDs feed into the competitor analytics tools.

Analytics

Tool	What it does
`swonkie_profile_insights_metrics`	Lists the metric codes available for connected-profile insights. Requires a `net` (network code); optional `insightType` (`daily` or `posts`), `search`, and pagination. Feed the returned codes into the `metrics[]` argument of the profile insights tools.
`swonkie_competitor_insights_metrics`	Lists the metric codes available for competitor insights. Same parameters as `swonkie_profile_insights_metrics`. Feed the returned codes into the competitor insights tools.
`swonkie_profile_insights_daily`	Returns aggregated daily metrics for one of your connected profiles over a date range. Requires `profileId`, `since` (ISO 8601), `until` (ISO 8601), and `metrics[]`.
`swonkie_profile_insights_posts`	Returns per-post metrics for one of your connected profiles over a date range. Same parameters as daily insights.
`swonkie_competitor_insights_daily`	Returns aggregated daily metrics for a monitored competitor. Requires a competitor `profileId` from `swonkie_competitors_list`.
`swonkie_competitor_insights_posts`	Returns per-post metrics for a monitored competitor. Same parameters as competitor daily insights.

Start with the metric-discovery tools to find the valid metrics[] codes for each network. Available metric names also depend on your plan and the connected network. See docs.swonkie.dev for the full list.

Posts

Tool	What it does
`swonkie_posts_list`	Lists posts in your workspace with optional filters: date range, workflow stages, post types, profile IDs, label IDs, and free-text search.
`swonkie_posts_rules_get`	Returns the merged platform constraints (caption length, media counts, image/video size, aspect ratio, resolution, fps, duration) for a post `type` across one or more `nets`. Returns the strictest effective limit across the selected networks. Call this before building media-heavy posts so payloads already match platform limits.
`swonkie_posts_get`	Loads a single post by ID. Returns the full post payload.
`swonkie_posts_create`	Creates a post. Requires `type` and `profileIds[]`. Supports per-network captions, media attachments, link previews, scheduled publish time, platform-specific options (Facebook carousels, TikTok flags, etc.), briefings, and labels.
`swonkie_posts_update`	Updates an existing post. Same schema as create — this is a full replacement, not a partial patch. Requires `postId`, `type`, and `profileIds[]`.
`swonkie_posts_delete`	Permanently deletes a post by ID.
`swonkie_posts_validate`	Runs publish validation rules on a post and returns whether it is ready to go live along with any validation messages.
`swonkie_posts_stage_change`	Moves a post through the approval workflow. See Workflow Stages below.

Post types: STATUS, MEDIA, STORY, LINK, REEL

Labels

Tool	What it does
`swonkie_labels_list`	Lists workspace labels. Paginated. Use label IDs when creating or filtering posts.
`swonkie_labels_create`	Creates a new label. Name must be 1–50 characters.

Media

Tool	What it does
`swonkie_media_get`	Returns metadata for an uploaded media item by ID.
`swonkie_media_create`	Starts a media upload — creates an entry in the media library and returns upload details. Follow with `swonkie_media_upload_confirm` after the file is uploaded. `destinationType` is either `POST_MEDIA` or `POST_LINK`.
`swonkie_media_create_from_url`	Imports media directly from a public HTTPS `fileUrl`. Swonkie fetches the file server-side (basic URL security checks apply — no localhost/private hosts) and starts processing immediately, so no client-side upload or confirm step is needed. Videos are limited to 200 MB for this URL flow. Use this when your client cannot upload local binaries.
`swonkie_media_upload_confirm`	Finalises processing after a file has been uploaded to the storage backend.
`swonkie_media_delete`	Removes a media item from the library.

AI (Andie)

Tool What it does

swonkie_andie_generate_image Generates a production-ready social media image from a text prompt using Andie, Swonkie's AI assistant. Pick an aspectRatio (e.g. 1:1, 4:5, 9:16, 16:9); optionally set quality (auto/low/medium/high) or a custom targetWidth/targetHeight. The image is uploaded to your media library and returned as a complete media object — its id can be used immediately as a mediaLibId in swonkie_posts_create or swonkie_posts_update. Typical generation time is 15–45 seconds.

Tool	What it does
`swonkie_andie_generate_image`	Generates a production-ready social media image from a text `prompt` using Andie, Swonkie's AI assistant. Pick an `aspectRatio` (e.g. `1:1`, `4:5`, `9:16`, `16:9`); optionally set `quality` (`auto`/`low`/`medium`/`high`) or a custom `targetWidth`/`targetHeight`. The image is uploaded to your media library and returned as a complete media object — its id can be used immediately as a `mediaLibId` in `swonkie_posts_create` or `swonkie_posts_update`. Typical generation time is 15–45 seconds.

Resources

Beyond tools, the server exposes read-only resources — structured JSON context that MCP clients can load to ground the agent before it acts.

Resource URI	What it provides
`mcp://swonkie/capabilities`	Overview of the server: tool groups, API base URL, docs and credentials links, authentication, and safe-automation rules.
`mcp://swonkie/workspace`	The authenticated workspace and user context for the current session.
`mcp://swonkie/profiles`	First page of connected social profiles.
`mcp://swonkie/competitors`	First page of monitored competitor profiles.
`mcp://swonkie/labels`	First page of workspace labels.
`mcp://swonkie/posts/{postId}`	Full details for a single post (templated by encrypted `postId`).
`mcp://swonkie/media/{mediaId}`	Media library metadata and processing status for a single item (templated by encrypted `mediaId`).
`mcp://swonkie/post-workflow`	Post stages and the allowed stage actions for approval, scheduling, and publishing.
`mcp://swonkie/post-schema`	Reference for post types, payload fields, and network-specific post options.
`mcp://swonkie/media-workflow`	The canonical create → upload → confirm → poll media flow, plus the URL-import alternative and limits.
`mcp://swonkie/insights-guide`	How to discover metrics and query profile/competitor insights, with required arguments.

Prompts

The server also ships ready-made prompts — guided, safety-aware workflows your client can offer as slash commands or templates.

Prompt	What it does
`create-post`	Walks through creating a post safely: gather profiles, type, content, media, and schedule, then validate.
`schedule-post`	Schedules a post after ensuring `publishAt` is set and validation passes.
`publish-now`	Publishes a post immediately, with validation and explicit confirmation.
`upload-media`	Guides the media upload flow (create → upload → confirm → poll), or the URL-import shortcut.
`content-calendar`	Reviews posts in a date range and summarises calendar status, gaps, and next actions.
`weekly-report`	Prepares a weekly performance report from profile insights.
`competitor-analysis`	Analyses monitored competitors using the competitor insights tools.
`organize-with-labels`	Uses labels to organise and filter posts safely.

Workflow Stages

Use swonkie_posts_stage_change to move a post through the content approval pipeline.

Stage	What it does
`publishNow`	Publishes the post immediately
`schedule`	Schedules the post for its `publishAt` time
`unschedule`	Removes the scheduled time and returns the post to draft
`teamReview`	Sends the post to the team review queue
`approve`	Approves the post (from a review state)
`reject`	Rejects the post (from a review state)

Supported Networks

The following network codes are accepted in profile filters, post profileIds, and per-network caption/media slots:

Code	Network
`facebook`	Facebook
`instagram` / `instagram_v2`	Instagram
`meta_ads`	Meta Ads
`linkedin`	LinkedIn
`youtube`	YouTube
`google_my_business`	Google Business Profile
`tiktok`	TikTok
`threads`	Threads
`twitter`	X (Twitter)

Quick Connect

Claude.ai (web)

Go to Claude.ai Connectors

Click + → Add custom connector

Enter a name, e.g. Swonkie

Paste your MCP server URL and click Add

Claude Desktop (UI)

Open Claude Desktop → Customize → Connectors (or use the deep link claude://settings/connectors)

Click + → Add custom connector

Enter a name, e.g. Swonkie

Paste your MCP server URL and click Add

Claude Desktop (config file)

Make sure Claude Desktop is up to date: Claude menu → Check for Updates...

Open Settings → Developer → Edit Config (or use claude://settings/developer)

Add the following to your config file:

{
  "mcpServers": {
    "swonkie": {
      "type": "http",
      "url": "https://mcp.swonkie.dev/mcp?apiId=YOUR_APP_ID&apiKey=YOUR_API_KEY"
    }
  }
}

Save the file and restart Claude Desktop

ChatGPT

Go to Settings → Apps → Advanced and enable Developer Mode (or open directly)

Go to Connectors and click Create app (or open directly)

Enter a name, e.g. Swonkie

Paste your MCP server URL as the connector URL

n8n

Open your workflow and add an MCP Client node (n8n MCP docs)

Set the transport to Streamable HTTP

Paste the following config into the node settings:

{
  "transport": "streamable-http",
  "url": "https://mcp.swonkie.dev/mcp?apiId=YOUR_APP_ID&apiKey=YOUR_API_KEY"
}

Other MCP clients

Open or create your MCP configuration file (e.g. .mcp.json, mcp.json, or your client's equivalent)

Add the following entry to the mcpServers section:

{
  "mcpServers": {
    "swonkie": {
      "type": "http",
      "url": "https://mcp.swonkie.dev/mcp?apiId=YOUR_APP_ID&apiKey=YOUR_API_KEY"
    }
  }
}

Save the file and restart your client

Security Best Practices

Use separate keys per client. Assign the Primary URL to one tool and the Secondary URL to another. If one is compromised you can rotate it without affecting the other.

Rotate if exposed. Go to Settings → Workspace → API and rotate the affected key. The new key becomes valid immediately; the old one is invalidated.

Never share MCP URLs publicly. The URL contains your live API key. Do not post it in public repos, Slack channels, or support tickets.

Revoke by rotating. There is no separate revoke action — rotating a key is the way to invalidate a URL.

What is MCP?#

What You Can Do#

Prerequisites#

Your MCP Server URL#

Available Tools#

Profiles#

Analytics#

Posts#

Labels#

Media#

AI (Andie)#

Resources#

Prompts#

Workflow Stages#

Supported Networks#

Quick Connect#

Claude.ai (web)#

Claude Desktop (UI)#

Claude Desktop (config file)#

ChatGPT#

n8n#

Other MCP clients#

Security Best Practices#

What is MCP?

What You Can Do

Prerequisites

Your MCP Server URL

Available Tools

Profiles

Analytics

Posts

Labels

Media

AI (Andie)

Resources

Prompts

Workflow Stages

Supported Networks

Quick Connect

Claude.ai (web)

Claude Desktop (UI)

Claude Desktop (config file)

ChatGPT

n8n

Other MCP clients

Security Best Practices