Swonkie

🆕 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.

---

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)

1. Go to Claude.ai Connectors
2. Click + → Add custom connector
3. Enter a name, e.g. Swonkie
4. Paste your MCP server URL and click Add

---

Claude Desktop (UI)

1. Open Claude Desktop → Customize → Connectors (or use the deep link claude://settings/connectors)
2. Click + → Add custom connector
3. Enter a name, e.g. Swonkie
4. Paste your MCP server URL and click Add

---

Claude Desktop (config file)

1. Make sure Claude Desktop is up to date: Claude menu → Check for Updates...
2. Open Settings → Developer → Edit Config (or use claude://settings/developer)
3. 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"
    }
  }
}

4. Save the file and restart Claude Desktop

---

ChatGPT

1. Go to Settings → Apps → Advanced and enable Developer Mode (or open directly)
2. Go to Connectors and click Create app (or open directly)
3. Enter a name, e.g. Swonkie
4. Paste your MCP server URL as the connector URL

---

n8n

1. Open your workflow and add an MCP Client node (n8n MCP docs)
2. Set the transport to Streamable HTTP
3. 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

1. Open or create your MCP configuration file (e.g. .mcp.json, mcp.json, or your client's equivalent)
2. 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"
    }
  }
}

3. 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.