🆕 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

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)

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

Manage your media library (upload and reference images/videos in posts)

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 17 tools organised into five 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_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.

Available metric names 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_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_upload_confirm`	Finalises processing after a file has been uploaded to the storage backend.
`swonkie_media_delete`	Removes a media item from the library.

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
`pinterest`	Pinterest
`google_my_business`	Google Business Profile
`tiktok`	TikTok
`threads`	Threads
`twitter`	X (Twitter)
`tumblr`	Tumblr
`blogger`	Blogger
`wordpress` / `wordpressorg`	WordPress

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#

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

Workflow Stages

Supported Networks

Quick Connect

Claude.ai (web)

Claude Desktop (UI)

Claude Desktop (config file)

ChatGPT

n8n

Other MCP clients

Security Best Practices