Praeko MCP server

One address, https://praeko.app/mcp, and one of two credentials: the same API key you use with the REST API, or your agent's OAuth sign-in. The agent reads these docs, looks up your account and, with your approval, creates, schedules, edits and cancels posts. Every write that publishes or changes content takes two steps: the first call does nothing.

What it is

MCP (Model Context Protocol) is the standard way for an AI agent to call tools. Praeko's server runs on the same host as the API and keeps no session: each call is a JSON-RPC POST and the response is a JSON object. Under the hood, each tool calls the same REST route you would call, with the English contract (X-Praeko-Contract: en). So validation, scopes, workspace isolation and errors are the API's own, and field names match the contract.

Two MCP servers: the remote one publishes, the local one makes the video

An agent can use both at once. This one, praeko, is the remote server: it runs at praeko.app/mcp and is the only one that creates, schedules, edits and cancels posts. praeko-studio is the local server of Praeko Studio (@praeko/studio-mcp): it runs on your machine over stdio, serves an agent without a terminal and never publishes. It needs Node, Chrome/Remotion to render and your own keys, all on your computer.

The full flow: create and render the video on the local server, upload the result with studio_upload (it returns only the mediaId, in two steps) and publish with create_post on this server, with your approval. Details and the list of the 14 local tools in Studio in Claude Desktop: the local MCP server.

Connect

The endpoint accepts two credentials, always in Authorization: Bearer … and on every call: an API key (praeko_…) that you create and paste into the agent's config, or an OAuth token (mcpat_…) that the agent gets by itself after you sign in and approve the connection. Both give the same tools, with the same scopes and the same two-step confirmation.

URL            https://praeko.app/mcp
Transport      Streamable HTTP (POST only; no session, no stream)
Auth           Authorization: Bearer praeko_…   (API key, on EVERY call; never in the URL)
               Authorization: Bearer mcpat_…    (OAuth token, obtained by the agent at sign-in)
OAuth          https://praeko.app/.well-known/oauth-protected-resource/mcp

With an API key

Create the key in the panel (Developers, API keys) or with praeko key create (which needs an admin key). The read scope is enough to read; the tools that write need write or admin. Keep the key in an environment variable, never in a versioned file. Each agent registers the server its own way: pick yours in AI agents and copy the ready-made block.

With sign-in (OAuth)

Add https://praeko.app/mcp to the agent with no header at all. The first call gets a 401 with resource_metadata in WWW-Authenticate; the agent discovers Praeko's authorization server and opens your browser. There is no key to copy or to leak.

# registers the server with no header; sign-in happens in the browser
claude mcp add --transport http praeko https://praeko.app/mcp
# inside Claude Code: /mcp, pick praeko and sign in

Authentication responses

Tools

Eighteen tools. The list the agent gets from tools/list depends on the scope: read sees the ten read and docs tools; write and admin see all eighteen (the server exposes nothing extra for admin: avoid admin for agents). The "What the agent gets" column is the literal description the server sends, in English; the two-step text that closes the six tools that publish or change content is right after the table. create_media_upload and complete_media_upload are the only writes without two steps (see "Local file").

TWO-STEP: the first call (without `confirm`) executes NOTHING: it returns a preview and a single-use `confirmation_code` (10 minutes). Show the preview (action, channels, time in BRT and UTC, media, text, warnings) to the user and WAIT for explicit approval. Only then call this tool again with the SAME arguments plus `confirm: "<code>"`. Changing any argument invalidates the code.

Annotations go in tools/list (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and the column spells them out: "read-only" is readOnlyHint, "destructive" is destructiveHint, "idempotent" is idempotentHint and "open-world" is openWorldHint (it talks to a social network or downloads from the internet). The client decides whether to trust them: the spec says to treat them as hints.

What each write does

• create_post: a post with one item per network. Without draft or queue, it is created as a draft; with queue: true, it takes the channel's next free slot. It never publishes immediately and refuses scheduledFor.
• schedule_post: the same post, but scheduledFor (ISO-8601 with time zone) is required on every item and the fixed time applies. No queue or draft. The post goes out by itself, on the real account.
• update_post: edits what has not gone out yet (title, texts, media, tags, items, moveTo). A YouTube video that Praeko already uploaded and that is still private or scheduled can also change its time, title, description, videoTags, categoryId and a pinned comment not yet posted; mode, queue and draft do not change on it. The server checks the video live on YouTube before writing and, if it is already public, its time has passed or it was deleted, nothing is written and the error gives the reason and the YouTube Studio link. The new time must be at least 5 minutes ahead, and the tool never makes a video public. The preview lists will_change or cannot_change per item (in itemChanges, with the reason); the response carries itemResults, item by item. Send only what changes.
• cancel_post: cancels the pending items; what already went out stays. It does not stop a YouTube video that was already uploaded and scheduled (YouTube publishes it at the set time; the preview and the response warn you): move the time with update_post or handle it in YouTube Studio. The tool has no dismiss and never deletes a video; over REST, DELETE /v1/posts/{id}?dismiss=true removes the schedule (the video stays private) and dismiss=true&delete_video=true deletes the private video.
• upload_media: downloads a public https URL into the library (see below).
• create_idea: a card on the idea board. Nothing is published.

Two-step writes

The confirmation lives on the server, not in the agent: even if the agent is set to approve everything, a write tool never runs on the first call. This holds the same for API keys and OAuth sign-in.

{
  "name": "schedule_post",
  "arguments": {
    "title": "The test that only failed on Mondays",
    "media": {
      "video": "01KA3VQ7M2T9XE4HB8N5RZ6C0D"
    },
    "texts": {
      "youtube": {
        "title": "The test that only failed on Mondays",
        "text": "…"
      }
    },
    "items": [
      {
        "network": "youtube",
        "mode": "scheduled",
        "scheduledFor": "2026-11-13T20:30:00Z"
      }
    ]
  }
}

{
  "preview": true,
  "executed": false,
  "tool": "schedule_post",
  "action": "Create a post and schedule it at fixed times",
  "title": "The test that only failed on Mondays",
  "items": [
    {
      "network": "youtube",
      "channel": {
        "id": "…",
        "name": "My channel",
        "connected": true
      },
      "mode": "network default",
      "timing": "fixed_time",
      "scheduledFor": {
        "utc": "2026-11-13T20:30:00.000Z",
        "brt": "2026-11-13 17:30 (BRT, UTC-03:00)"
      }
    }
  ],
  "media": [
    {
      "id": "01KA3VQ7M2T9XE4HB8N5RZ6C0D",
      "found": true,
      "type": "video",
      "state": "ready"
    }
  ],
  "warnings": [
    "Confirming schedules a REAL publication on the connected account(s) at the time above. It can be edited or cancelled until then (update_post, cancel_post)."
  ],
  "confirmation_code": "K7MQ-2VXZ-9RT4",
  "expires_at": "2026-11-13T12:10:00.000Z",
  "expires_in_seconds": 600,
  "next_step": "NOTHING was done yet. Show this preview to the user and wait for approval. …"
}

{
  "name": "schedule_post",
  "arguments": {
    "title": "The test that only failed on Mondays",
    "media": {
      "video": "01KA3VQ7M2T9XE4HB8N5RZ6C0D"
    },
    "texts": {
      "youtube": {
        "title": "The test that only failed on Mondays",
        "text": "…"
      }
    },
    "items": [
      {
        "network": "youtube",
        "mode": "scheduled",
        "scheduledFor": "2026-11-13T20:30:00Z"
      }
    ],
    "confirm": "K7MQ-2VXZ-9RT4"
  }
}

{
  "preview": false,
  "executed": true,
  "tool": "schedule_post",
  "result": {
    "id": "…",
    "items": [
      {
        "network": "youtube",
        "state": "scheduled"
      }
    ]
  }
}

The confirmation code

Changing any argument, reusing the code, or using an expired code or one from another credential, tool or workspace fails. The response is a tool execution error (isError: true) with error.code confirmation_invalid and the reason in error.reason (the message is in English):

{
  "error": {
    "code": "confirmation_invalid",
    "message": "this confirmation code expired (10 minutes). Request a new preview and show it to the user again.",
    "reason": "expired"
  }
}

upload_media: media from a URL

The tool takes a public https URL and the server downloads the file. The file never goes through the conversation with the agent.

The Worker does not resolve DNS before downloading: against a public name that resolves to a private IP, the protection is Cloudflare's own network, which cannot reach anyone's private network.

Local file: create_media_upload and complete_media_upload

The most common case for an agent with a shell (Claude Code, Codex, Gemini CLI, opencode, Cursor, Kimi, Cline): the video is on disk. MCP does not carry large files, so the server only prepares the upload and the agent's own curl sends it straight to the API, with the key that is already in the user's environment.

{
  "executed": true,
  "tool": "create_media_upload",
  "upload": {
    "mediaId": "01KB7J3V9Q2W8E5R1T6Y4N0M3P",
    "state": "uploading",
    "expectedSize": 48213377,
    "mime": "video/mp4",
    "expiresAt": "2026-11-08T12:00:00.000Z",
    "keyHandling": "The API key is already in the user's shell environment as PRAEKO_KEY (…)",
    "method": "single_put",
    "http": {
      "method": "PUT",
      "url": "https://praeko.app/v1/media/01KB7J3V9Q2W8E5R1T6Y4N0M3P/content",
      "headers": {
        "Authorization": "Bearer $PRAEKO_KEY",
        "Content-Type": "video/mp4"
      },
      "body": "the raw bytes of the file (exactly 48213377 bytes)"
    },
    "command": "curl -sS --fail-with-body -X PUT -H \"Authorization: Bearer $PRAEKO_KEY\" -H \"Content-Type: video/mp4\" -H \"Expect:\" -T \"/path/to/file\" \"https://praeko.app/v1/media/01KB7J3V9Q2W8E5R1T6Y4N0M3P/content\""
  },
  "next_step": "Run `upload.command` in the shell (replace /path/to/file; the key comes from the environment, do not print it), then call complete_media_upload with this mediaId, then create_post or schedule_post with media.video = mediaId (those keep their two-step preview/confirmation)."
}

Why there is no confirmation code

Creating the upload slot publishes nothing, sends nothing to a network and changes no post. What protects the account is the next step, create_post or schedule_post, which still takes two steps. So these two tools are single-step, with limits instead of a code:

Protocol

The endpoint speaks two MCP eras at the same address, as the spec allows. Most clients today still use 2025-11-25; 2026-07-28 (the newest when this was checked, Nov 7, 2026) has no initialize and no session.

• The response is always application/json (the spec allows it instead of SSE). The server sends no Mcp-Session-Id and ignores Accept. Client notifications and responses: 202 with no body.
• tools/call returns content (text with the JSON) and structuredContent (the same object). There is no outputSchema.
• An unknown tool is a protocol error (-32602). Invalid arguments, business rules and API failures are tool execution errors (isError: true, with structuredContent.error = { code, message, status, details? }), so the model can correct itself.

curl -s https://praeko.app/mcp \
  -H "Authorization: Bearer $PRAEKO_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Security

Clients checked

Tested with the real Claude Code: with an API key (initialization, tools/list, list_channels and the create_idea preview) and with OAuth sign-in (discovery, registration through the client metadata document, consent, connection and revocation). The blocks for the other agents in AI agents come from each vendor's documentation. Sign-in from ChatGPT has not been checked against a primary source.