Servidor MCP do Praeko

Um endereço, https://praeko.app/mcp, e uma de duas credenciais: a mesma chave de API da REST ou o login OAuth do seu agente. O agente lê estas docs, consulta a sua conta e, com a sua aprovação, cria, agenda, edita e cancela posts. Toda escrita que publica ou muda conteúdo tem dois passos: nada acontece na primeira chamada.

O que é

O MCP (Model Context Protocol) é o jeito padrão de um agente de IA chamar ferramentas. O servidor do Praeko roda no mesmo endereço da API e não guarda sessão: cada chamada é um POST com JSON-RPC e a resposta é um objeto JSON. Por dentro, cada ferramenta chama a mesma rota REST que você chamaria, com o contrato em inglês (X-Praeko-Contract: en). Por isso a validação, o escopo, o isolamento por workspace e os erros são os da API, e os nomes de campo são os do contrato.

Dois servidores MCP: o remoto publica, o local faz o vídeo

Um agente pode usar os dois ao mesmo tempo. Este, praeko, é o remoto: roda em praeko.app/mcp e é o único que cria, agenda, edita e cancela posts. O praeko-studio é o servidor local do Praeko Studio (@praeko/studio-mcp): roda na sua máquina por stdio, serve a um agente sem terminal e nunca publica. Precisa de Node, de Chrome/Remotion para renderizar e das suas chaves, tudo no seu computador.

O fluxo completo: criar e renderizar o vídeo no servidor local, subir o resultado com studio_upload (devolve só o mediaId, em duas etapas) e publicar com create_post neste servidor, com a sua aprovação. Detalhes e a lista das 14 ferramentas locais em Studio no Claude Desktop: o servidor MCP local.

Conectar

O endpoint aceita duas credenciais, sempre em Authorization: Bearer … e em toda chamada: uma chave de API (praeko_…), que você cria e cola na configuração do agente, ou um token OAuth (mcpat_…), que o agente obtém sozinho depois que você entra e aprova a conexão. Os dois dão as mesmas ferramentas, com o mesmo escopo e a mesma confirmação em dois passos.

URL            https://praeko.app/mcp
Transporte     Streamable HTTP (só POST; sem sessão, sem stream)
Autenticação   Authorization: Bearer praeko_…   (chave de API, em TODA chamada; nunca na URL)
               Authorization: Bearer mcpat_…    (token OAuth, obtido pelo agente no login)
OAuth          https://praeko.app/.well-known/oauth-protected-resource/mcp

Com chave de API

Crie a chave no painel (Desenvolvedores, Chaves de API) ou com praeko key create (que exige uma chave admin). Escopo read basta para ler; as ferramentas que escrevem pedem write ou admin. Guarde a chave em variável de ambiente, nunca em arquivo versionado. Cada agente registra o servidor de um jeito: escolha o seu em Agentes de IA e copie o bloco pronto.

Com login (OAuth)

Adicione https://praeko.app/mcp no agente sem cabeçalho nenhum. A primeira chamada recebe 401 com resource_metadata no WWW-Authenticate; o agente descobre o servidor de autorização do Praeko e abre o navegador. Não há chave para copiar nem para vazar.

# registra o servidor sem cabeçalho; o login acontece no navegador
claude mcp add --transport http praeko https://praeko.app/mcp
# dentro do Claude Code: /mcp, escolha praeko e entre

Respostas de autenticação

Ferramentas

Dezoito ferramentas. A lista que o agente recebe em tools/list varia com o escopo: read vê as dez de leitura e docs; write e admin veem as dezoito (o servidor não expõe nada a mais para admin: evite admin em agente). A coluna "O agente recebe" é a descrição literal, em inglês, que o servidor entrega; o texto de dois passos que fecha as seis ferramentas que publicam ou mudam conteúdo está logo depois da tabela. create_media_upload e complete_media_upload são as únicas escritas sem dois passos (veja "Arquivo local").

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.

As anotações vão em tools/list (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) e a coluna as escreve em palavras: "somente leitura" é readOnlyHint, "destrutiva" é destructiveHint, "idempotente" é idempotentHint e "rede externa" é openWorldHint (o que fala com uma rede social ou baixa da internet). O cliente decide se confia nelas: a especificação manda tratá-las como dicas.

O que cada escrita faz

• create_post: um post com um item por rede. Sem draft nem queue, nasce como rascunho; com queue: true, pega a próxima vaga livre do canal. Nunca publica na hora e recusa scheduledFor.
• schedule_post: o mesmo post, mas scheduledFor (ISO-8601 com fuso) é obrigatório em todo item e vale o horário fixo. Sem queue nem draft. O post sai sozinho, na conta real.
• update_post: edita o que ainda não saiu (título, textos, mídia, etiquetas, itens, moveTo). Um vídeo do YouTube que o Praeko já subiu e que ainda está privado ou agendado também muda de horário, título, descrição, videoTags, categoryId e comentário fixo ainda não postado; modo, fila e rascunho não mudam nele. O servidor confere ao vivo no YouTube antes de escrever e, se o vídeo já está público, o horário passou ou o vídeo sumiu, não escreve e o erro traz o motivo e o link do YouTube Studio. O novo horário precisa estar pelo menos 5 minutos à frente, e a ferramenta nunca torna um vídeo público. A prévia lista por item will_change ou cannot_change (em itemChanges, com o motivo); a resposta traz itemResults, item a item. Mande só o que muda.
• cancel_post: cancela os itens pendentes; o que já saiu fica. Não impede a publicação de um vídeo do YouTube já subido e agendado (o YouTube o publica na hora marcada; a prévia e a resposta avisam): mude o horário com update_post ou resolva no YouTube Studio. A ferramenta não tem dismiss nem apaga vídeo; pela REST, DELETE /v1/posts/{id}?dismiss=true tira o horário (o vídeo fica privado) e dismiss=true&delete_video=true apaga o vídeo privado.
• upload_media: baixa uma URL pública https para a biblioteca (veja abaixo).
• create_idea: um cartão no quadro de ideias. Nada é publicado.

Escrita em dois passos

A confirmação é do servidor, não do agente: mesmo que o agente esteja configurado para aprovar tudo, uma ferramenta de escrita nunca executa na primeira chamada. Vale igual para chave de API e para login OAuth.

{
  "name": "schedule_post",
  "arguments": {
    "title": "O teste que só falhava na segunda",
    "media": {
      "video": "01KA3VQ7M2T9XE4HB8N5RZ6C0D"
    },
    "texts": {
      "youtube": {
        "title": "O teste que só falhava na segunda",
        "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": "O teste que só falhava na segunda",
  "items": [
    {
      "network": "youtube",
      "channel": {
        "id": "…",
        "name": "Meu canal",
        "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": "O teste que só falhava na segunda",
    "media": {
      "video": "01KA3VQ7M2T9XE4HB8N5RZ6C0D"
    },
    "texts": {
      "youtube": {
        "title": "O teste que só falhava na segunda",
        "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"
      }
    ]
  }
}

O código de confirmação

Mudar qualquer argumento, repetir o código, usar um vencido ou de outra credencial, ferramenta ou workspace falha. A resposta é um erro de execução (isError: true) com error.code confirmation_invalid e o motivo em error.reason (a message vem em inglês):

{
  "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: mídia por URL

A ferramenta recebe uma URL pública https e o servidor baixa o arquivo. O arquivo nunca passa pela conversa com o agente.

O Worker não resolve o DNS antes de baixar: contra um nome público que resolva para IP privado, a proteção é a própria rede da Cloudflare, que não alcança a rede privada de ninguém.

Arquivo local: create_media_upload e complete_media_upload

O caso mais comum de um agente com shell (Claude Code, Codex, Gemini CLI, opencode, Cursor, Kimi, Cline): o vídeo está no disco. O MCP não carrega arquivo grande, então o servidor só prepara o envio e quem envia é o curl do próprio agente, direto para a API, com a chave que já está no ambiente do usuário.

{
  "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)."
}

Por que sem código de confirmação

Criar o espaço de envio não publica nada, não envia nada para uma rede e não altera post. O que protege a conta é o passo seguinte, create_post ou schedule_post, que segue em dois passos. Por isso estas duas ferramentas são de um passo só, com limites no lugar do código:

Protocolo

O endpoint fala duas eras do MCP no mesmo endereço, como a especificação prevê. Os clientes de hoje, na maioria, ainda usam a 2025-11-25; a 2026-07-28 (a mais nova na data da conferência, 07/11/2026) não tem initialize nem sessão.

• A resposta é sempre application/json (a especificação permite no lugar de SSE). O servidor não emite Mcp-Session-Id e não olha o Accept. Notificação e resposta do cliente: 202 sem corpo.
• tools/call devolve content (texto com o JSON) e structuredContent (o mesmo objeto). Não há outputSchema.
• Ferramenta desconhecida é erro de protocolo (-32602). Argumento inválido, regra de negócio e falha da API são erro de execução (isError: true, com structuredContent.error = { code, message, status, details? }), para o modelo se corrigir.

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"}'

Segurança

Clientes conferidos

Testado com o Claude Code real: com chave de API (inicialização, tools/list, list_channels e a prévia de create_idea) e com login OAuth (descoberta, registro pelo documento de metadados do cliente, consentimento, conexão e revogação). Os blocos dos demais agentes em Agentes de IA vêm da documentação de cada fabricante. O login pelo ChatGPT não foi conferido em fonte primária.