Drive Supapost from any MCP-capable agent.

Quick start

The fastest way to connect, browser OAuth, no API key to manage:

claude mcp add --transport http supapost https://mcp.supapo.st

When you first use a Supapost tool, your browser opens supapo.st/mcp/authorize. You sign in with Google, approve access to your workspace, and the MCP client stores an access token. From then on every tool call is authenticated automatically.

Connecting other clients

Cursor, Windsurf, VS Code

Add the server to your client's .mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "supapost": {
      "url": "https://mcp.supapo.st"
    }
  }
}

Raw HTTP clients with Bearer token

Skip OAuth entirely by creating an API key at Settings → Developer and passing it as a Bearer token. Keys start with sp_live_.

{
  "mcpServers": {
    "supapost": {
      "url": "https://mcp.supapo.st",
      "headers": { "Authorization": "Bearer sp_live_..." }
    }
  }
}

Local stdio fallback

When you need a local process, for custom SUPAPOST_API_URL, air-gapped networks, or MCP clients that don't support HTTP, use the stdio package from npm:

claude mcp add supapost --env SUPAPOST_API_KEY=sp_live_... -- npx -y @supapost/mcp

The @supapost/mcp package is open source and thin: it translates MCP tool calls into REST calls against api.supapo.st.

Transports explained

Remote HTTP (Streamable HTTP)

The MCP specification's current transport. One HTTP endpoint accepts POST JSON-RPC messages; the server streams responses over the same connection when needed. Authed via OAuth 2.1 with PKCE (Cloudflare Workers OAuth Provider handles the ceremony). Best for: everyone who isn't specifically blocked from reaching mcp.supapo.st.

Local stdio

The original MCP transport. Your client launches a local Node process and talks to it over stdin/stdout. No network, no OAuth, just SUPAPOST_API_KEY as an env var. Best for: scripting, dev environments, custom endpoints.

Verify the connection

After registering the MCP, call list_models once. You should get a JSON list of available generation models. If you get 401 Invalid API key, your key is wrong, expired, or missing the sp_ prefix, regenerate at Settings → Developer.

Tool reference

Every tool is a function the agent can call. Each tool validates its arguments with Zod and returns JSON. The full 20+ tool list:

Example workflows

Build a 10-slide TikTok deck from a prompt

1. Agent calls generate_slides with { prompt: 'morning routine for new moms, warm pastel, 10 slides' }.
2. The server returns a project with slides, background images, and text layers.
3. Agent optionally calls upsert_project to tweak metadata (status = draft → published).
4. Agent opens https://app.supapo.st/studio/slides/<id> in your browser for final review.

Create a consistent AI influencer

1. generate_image with the character description. Pick the best.
2. create_influencer with that URL in images[]. The first image becomes the identity anchor.
3. For every new scene, generate_image with influencerId set. Describe scene only, the anchor handles the face.

Schedule a post for next Tuesday 9am

1. list_social_accounts → find the TikTok account id.
2. schedule_post with platform: "tiktok", socialAccountId, ISO 8601 scheduledAt, and either a projectId (existing deck) or imageUrls[].
3. Delivery runs through Cloudflare Queues with automatic retries, your post goes live within seconds of the scheduled time.

Security

• OAuth tokens are short-lived and scoped to one workspace. Revoke any time from Settings → Developer.
• API keys are verified by Unkey and scoped to one team. Generate per-use, rotate freely.
• All tool calls run through the same authentication and authorisation middleware as the web app, Row-Level Security on every database read, team scoping on every write.
• All input is validated with Zod schemas shared between the web editor and the API, no shape mismatches, no surprise fields.

FAQ