MCP quickstart: schedule social posts from Claude Code

Connect the Turboyap MCP server to Claude Code or Cursor and let your agent upload slides, preview each platform's version, and schedule posts to TikTok and Instagram. Start with a test key.

Early access: the MCP server is built and being tested. @turboyap/mcp isn’t published to npm yet, so the npx commands below work once it is. Ask for early access to hear first.

The Turboyap MCP server runs on your machine, so your agent can upload files straight from disk, including a whole folder of slides. You need a Turboyap agent key. Start with a test key (ty_agent_test_…): it runs the whole flow against simulated accounts and never posts anywhere real. Switch to a live agent key (ty_agent_…) when you’re ready.

Claude Code

claude mcp add turboyap -e TURBOYAP_API_KEY=ty_agent_test_… -- npx -y @turboyap/mcp

Cursor and other MCP clients

{
  "mcpServers": {
    "turboyap": {
      "command": "npx",
      "args": ["-y", "@turboyap/mcp"],
      "env": { "TURBOYAP_API_KEY": "ty_agent_test_…" }
    }
  }
}

The server reads TURBOYAP_API_KEY, plus an optional TURBOYAP_API_URL that defaults to https://api.turboyap.com.

With a test key, create test accounts first

A test key only sees test accounts, and the MCP server has no tool that creates them. Create a simulated TikTok and Instagram account once, with the same key:

for platform in tiktok instagram; do
  curl https://api.turboyap.com/v1/accounts/test \
    -H "Authorization: Bearer ty_agent_test_…" \
    -H "Content-Type: application/json" \
    -d "{\"platform\": \"$platform\"}"
done

They start on autonomy level 1, like real accounts, so your agent’s posts wait for approval. Approve them with your human test key (ty_human_test_…), as the test mode quickstart shows.

Try it

Ask your agent something like:

Upload the slides in ~/content/icecream and schedule them to our TikTok and Instagram for Tuesday 6pm ET. Dry-run first and fix anything Instagram can’t take.

The agent works through the tools in this order:

1. list_accounts finds your connected accounts and their autonomy level.
2. get_platform_rules reads slide limits, formats and aspect ratios.
3. upload_media uploads the folder in natural filename order (slide-2 before slide-10).
4. create_post with dry_run: true shows what each platform will get, plus every problem with a fix.
5. create_post applies the fixes, for example fit: { overflow: "truncate", aspect: "pad" }, and schedules.
6. get_post reports each account’s status and a next_step to relay to you.

Tools

Agents can’t approve posts. On accounts set to autonomy level 1, agent posts wait for a human; see the autonomy dial.

Scopes

Agent keys default to read, draft and schedule. They can schedule a future time but not publish with "now", and a key without schedule saves drafts (no schedule_at) for a human to schedule. A key can also be limited to some accounts. When a call fails with insufficient_scope or account_not_allowed, the agent can call get_workspace to see what its key may do.

Every post records which agent made it

The MCP server sends an X-Turboyap-Client header with every call, filled in from the name and version your MCP client reports when it connects, or turboyap-mcp if it reports none. Turboyap stores it in each post’s created_by.client and in the audit log, so you can tell which agent made a post.

Errors are written for agents

Every error includes a code, the field that caused it, and a fix:

{
  "error": {
    "code": "too_many_items",
    "message": "instagram allows 10 slides per post; got 12.",
    "field": "media_ids",
    "fix": "Set fit.overflow to \"truncate\" to post the first 10, or pass targets[1].media_ids with your best 10 slides (keep your call-to-action slide)."
  }
}

Agents apply the fix and retry without asking you, unless the fix needs a human (like reconnecting an account).

This page as markdown: /docs/mcp-quickstart.md. All docs for LLMs: /llms.txt and /llms-full.txt.