Solving the 4MB MCP Limit: Why Most Agents Cannot Take Your Video

You asked ChatGPT to schedule the launch video. It said yes. You hit the paperclip. Nothing reached posterly. Or the tool call died with a 413. This is the most common MCP media failure we see, and it is not an MCP-protocol file limit.

Vercel caps request bodies to posterly API routes at about 4MB. Hosted MCP (POST /api/mcp) is JSON on that same path. A base64 file inside upload_media counts against it. Base64 also inflates the file, so hosted upload_media is only for small images.

Most social MCP servers only offer that base64 path. The agent stuffs bytes into the tool argument, the host rejects the body, and the blog post you read said "just attach the file". posterly does not stop there.

This post is the map. The tables also live in the MCP docs. Use this when you want the why, then the exact tool to call.

The limit that is not MCP

Three different ceilings get mixed up:

Ceiling	What it actually is	Typical size
Vercel function body	JSON (or multipart) into /api/mcp or POST /api/v1/media/upload	About 4MB
posterly plan video cap	Starter / Pro / Power / Agency	500MB / 750MB / 1GB / 4GB
Platform cap	Instagram, TikTok, LinkedIn, YouTube, and the rest	Varies; often 1GB to 4GB+

The 4MB number is the function body. It is not posterly's storage plan. It is not TikTok. Agents that only know upload_media with base64 hit the first ceiling and never see the other two.

Chat attachments never become MCP arguments on ChatGPT, Claude, Cursor, Poke, Hermes, OpenClaw, or Grok Bot. The paperclip is a chat feature. It is not upload_media.

What most MCP servers do

The naive MCP media tool looks like this:

1. Agent reads the file (or the chat attachment, which it cannot).
2. Base64-encodes it.
3. Sends it as a JSON string in the tool call.

That works for a 200KB PNG. It dies for a 40MB MP4. Some servers then tell you to pass a public URL instead. posterly will fetch a small public URL (upload_media with url), but a 500MB R2 or S3 object fails with remote_media_too_large (about 5MB on the relay path, 60MB remote-fetch hard cap). A huge object-storage URL is not a bypass. It is a second trap.

The legacy PUT /api/v1/media/signed-upload/upload relay is the same Vercel body. Do not use it. Large videos return FUNCTION_PAYLOAD_TOO_LARGE.

What posterly does instead

Three bypasses. Pick the one your runtime can actually perform.

1. create_signed_upload, then PUT to object storage

For agents that can HTTP PUT (Cursor Desktop, Claude Code, Codex, many Cloud Agents):

Free download

Prompts for a social campaign

Prompts that run a campaign through the posterly MCP, plus a plan-a-week walkthrough, using only tools the server has.

Get the prompts

Or start a free 7-day trial

1. Call create_signed_upload with filename, content_type, and exact size.
2. PUT the raw bytes to the returned upload_url (R2 or Supabase). Do not PUT to a poster.ly API route.
3. Pass public_url into validate_post / create_post.

The JSON call is tiny. The video never touches Vercel. Plan caps apply: Starter 500MB, Pro 750MB, Power 1GB, Agency 4GB.

2. Stdio upload_media with file_path

For agents on the same machine as the file (Cursor Desktop, Claude Desktop, Claude Code, Codex, Hermes):

Give a real local path. The npm package posterly-mcp-server reads the disk and uses signed upload for large files. No base64 in the tool JSON.

3. create_media_drop, then list_media

For ChatGPT web, Claude.ai, and Gemini web, which cannot PUT a laptop file and cannot see file_path:

1. Call create_media_drop.
2. Send the user https://www.poster.ly/drop/<token>.
3. They open it with no dashboard login and drop the file. The browser PUTs to object storage.
4. Call list_media with drop_session_id.
5. Pass public_url into validate_post / create_post.

That is what list_media is for: it lists newest library files (optionally one drop session) so the agent can attach public_url. It does not pick Instagram vs LinkedIn. It does not schedule. The drop page takes JPEG, PNG, GIF, WebP, MP4, MOV, WebM, and PDF up to 50MB (a PDF is for LinkedIn document posts); HEIC is rejected. The link lasts 24 hours. The storage PUT lasts one hour.

Walkthroughs: ChatGPT, Claude, Cursor, Poke, Hermes, OpenClaw, Grok Bot.

A decision table you can paste into an agent

Runtime	Use this
Cursor Desktop, Claude Code, Claude Desktop, Hermes on your laptop	file_path or create_signed_upload then PUT
Cursor Cloud Agents that can PUT	create_signed_upload then PUT
ChatGPT web, Claude.ai, Poke, OpenClaw on a phone	create_media_drop then list_media
Tiny PNG already on the public web	upload_media with url, or media_url on create_post
500MB file sitting on R2	Download it, then signed upload or drop. Do not pass the R2 URL in

What still fails (on purpose)

• The paperclip. Never MCP.
• Hosted upload_media with a big base64 string. Hits ~4MB.
• Giant third-party URLs. remote_media_too_large.
• HEIC on the drop page. Export it as JPEG or PNG first. PDFs are accepted (up to 50MB) for LinkedIn document posts.
• A 5GB export on Agency. Agency video is 4GB. Re-export.

None of those are "MCP is too small". They are the wrong tool for the size.

Start with the runtime you actually have

If the agent can see a disk path, use it. If it can PUT, use create_signed_upload. If it is a chat box in a browser, use create_media_drop. Then validate_post, then create_post with confirm: true.

Short client pages: ChatGPT, Claude, Cursor, Poke, Hermes, OpenClaw, Grok Bot, MCP hub. Docs table: MCP media upload.