sprkly.app-mcp

O sprkly.app permite que usuários publiquem seu conteúdo de formato curto no tiktok, facebook, instagram, youtube e threads por meio de linguagem natural.

Ver em sprkly.app

Documentação

Início rápido

Duas formas de autenticar. Escolha a que seu cliente suporta.

Recomendado

Conectar com OAuth

Para Claude Cowork, claude.ai, Claude Desktop, Claude Code e ChatGPT. Adicione o endpoint como um conector personalizado e faça login. Nada para copiar, e a conexão está vinculada ao seu login sprkly em vez de um segredo de longa duração.

1. Adicione https://sprkly.app/api/mcp como um conector personalizado.
2. Clique em Conectar e aprove as permissões.
3. Pergunte ao seu agente o que você tem agendado. Configuração por cliente, logo abaixo →

Scripts, CI, agentes auto-hospedados

Enviar uma chave de API

Crie uma chave em Configurações → Chaves de API e envie-a como um token bearer. Não há etapa de troca nem token de curta duração para renovar.

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

O MCP está disponível nos planos Creator e Power, e no teste gratuito. Uma chave funciona para MCP e para a API REST. No plano Free, chamadas MCP retornam 403 com plan_required; a API REST ainda funciona. Chamadas em excesso retornam 429: aguarde o número de segundos em Retry-After.

Configuração do cliente

Cada cliente, passo a passo. Agentes hospedados fazem login com OAuth; qualquer coisa rodando localmente pode usar uma chave de API de Configurações → Chaves de API em vez disso.

Claude Cowork

Faça login com OAuth

Dê ao Cowork sua fila de publicações para que ele possa planejar e agendar junto com o resto do seu trabalho.

1.No Cowork, abra Configurações (seu avatar, canto inferior esquerdo) e clique em Conectores.
2.Clique em Adicionar conector personalizado.
3.No diálogo, cole o URL do servidor abaixo no campo URL. O nome pode ser qualquer coisa. "sprkly" fica melhor.
4.Clique em Adicionar. sprkly aparece na lista de conectores. Clique em Conectar ao lado dele.
5.Uma aba de login do sprkly abre. Faça login e clique em Aprovar na tela de consentimento.

O formulário, campo por campo

Nome

sprkly

URL

https://sprkly.app/api/mcp

Concluído quando: O cartão do conector muda para Conectado, e perguntar ao Cowork "o que eu tenho agendado esta semana?" responde com sua agenda real.

O Cowork conecta-se pela nuvem da Anthropic, não pelo seu laptop. Nada para instalar. "Não foi possível alcançar o servidor MCP" quase sempre significa URL digitado errado. Copie, não redigite.

Os limites são reais, não apenas informativos

Não há ferramenta de publicar agora. Tudo passa pela mesma fila, limites de plano e caminho de aprovação que suas próprias publicações.
Excluir é uma exclusão suave que você pode desfazer por 30 dias; um agente não pode tocar em uma publicação já feita.
Um agente só vê suas próprias contas, e uma chave de API pode ser limitada a um subconjunto delas.
Cada chamada de ferramenta é registrada. Desconecte a qualquer momento em Configurações.

Perguntas

Quais agentes de IA podem se conectar ao sprkly?

Qualquer cliente que fale o Model Context Protocol. Isso inclui Claude Cowork, claude.ai, Claude Desktop, Claude Code, ChatGPT em modo desenvolvedor, Codex, Cursor, VS Code e ferramentas de automação como n8n. Qualquer outra coisa pode chamar o endpoint via HTTP simples com uma chave de API.

Preciso instalar algo?

Não. O sprkly executa um servidor MCP hospedado, então você cola um URL no seu agente e faz login. Não há nada para rodar na sua máquina e nada para manter atualizado.

Um agente de IA pode publicar sem me perguntar?

Ele só pode agendar para contas que você já conectou, e somente se você pedir. Você também pode exigir aprovação humana, então qualquer coisa que um agente enfileirar espera seu aval antes de publicar. Publicações já feitas não podem ser excluídas por um agente de forma alguma.

Quanto custa?

Nada extra nos planos Creator e Power, e está incluído no teste gratuito. Contas Free mantêm a API REST, mas não o MCP. As solicitações contam para um total mensal com a API REST: 7.500 no Creator, 15.000 no Power.

Posso limitar quais contas um agente vê?

Sim. Limite uma chave de API a contas específicas em Configurações e o agente só pode ler e publicar nessas. Os escopos também controlam se ele pode escrever ou apenas ler.

Exemplo prático

Inicialize, liste as ferramentas e depois agende uma publicação. Substitua pela sua própria credencial.

TOKEN="sk_live_…"
MCP="https://sprkly.app/api/mcp"

# 1. Initialize (no credentials needed)
curl -s "$MCP" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-11-25",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Which accounts can I post to?
curl -s "$MCP" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"sprkly_list_profiles","arguments":{}}}'

# 3. Check the caption before committing to it
curl -s "$MCP" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"sprkly_validate_post_policy",
                 "arguments":{"caption":"Launch day.",
                              "platforms":["instagram"],
                              "mediaUrlsCount":1}}}'

# 4. Queue it
curl -s "$MCP" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call",
       "params":{"name":"sprkly_schedule_post",
                 "arguments":{"caption":"Launch day.",
                              "profile_ids":["profile_…"],
                              "media_urls":["https://example.com/launch.jpg"],
                              "scheduled_time":"2026-08-04T18:00:00.000Z"}}}'

O que toda publicação precisa

Quatro coisas são sempre obrigatórias: uma legenda, pelo menos uma plataforma, um horário e mídia para as plataformas que exigem. Duas plataformas querem mais, e sprkly_schedule_post recusa a chamada em vez de adivinhar.

Campo	Obrigatório para	Observações
caption	toda publicação	Verificado contra o limite de comprimento de cada plataforma antes de qualquer coisa ser enfileirada.
title	TikTok, YouTube	Ambas as plataformas exibem o título, não a legenda. O YouTube limita a 100 caracteres.
platform_meta.tiktok.privacyLevel	TikTok	O TikTok rejeita uma publicação sem isso. Envie o nível que o usuário pediu; se não for um que este criador permite, o erro nomeia os níveis permitidos. Ou leia-os primeiro com `sprkly_get_tiktok_posting_options`.
media_urls / media_ids	Instagram, TikTok	Nenhuma aceita publicação só de texto. Passe um link direto e o sprkly puxa para o armazenamento automaticamente.

A ordem do array é a ordem dos slides. Para um carrossel ou conjunto de fotos, a sequência que você envia em media_urls ou media_ids é a sequência que publica. O slide 1 tem mais peso: o Instagram corta todos os outros slides para combinar com a forma dele, e Threads e Facebook publicam apenas esse.

Uma listagem de arquivos não é uma listagem ordenada. Google Drive, Dropbox e a maioria dos nós de automação retornam arquivos em ordem de upload, que raramente corresponde à intenção. Ordene pelo nome do arquivo antes de montar o array e nomeie os arquivos para que a ordenação funcione: 01.jpg, 02.jpg, 03.jpg. Preencha com zero, porque como texto 10 ordena antes de 2. Quando a ordem foi inferida em vez de fornecida, diga isso na resposta em vez de apresentá-la como certa.

Ferramentas

19 ferramentas. Os argumentos abaixo são exatamente o que tools/list retorna.

sprkly_add_media_from_url WriteIdempotent

Baixe uma imagem ou vídeo de um link público para o sprkly e receba um media_id de volta, para reutilização em várias publicações. Você geralmente NÃO precisa disso: sprkly_schedule_post aceita um link diretamente em media_urls e puxa para o armazenamento sempre que a plataforma de destino exigir. Use esta ferramenta apenas quando o usuário quiser um media_id para anexar a mais de uma publicação. Links de compartilhamento do Google Drive e Dropbox são convertidos automaticamente; o arquivo deve estar compartilhado publicamente. Limite de 50 MB.

Argumento	Tipo	Descrição
urlobrigatório	string	Link https direto para o arquivo de imagem ou vídeo. Deve ser publicamente acessível.

Você diz "Use este clipe para as três publicações desta semana: https://cdn.example.com/clips/launch.mp4”

O agente chama

sprkly_add_media_from_url({
  "url": "https://cdn.example.com/clips/launch.mp4"
})

Retorna um mediaId que você pode anexar a várias publicações. Para UMA ÚNICA publicação, não chame isso: coloque o link direto em media_urls no sprkly_schedule_post e ele é puxado para o armazenamento lá.

sprkly_delete_scheduled_post WriteDestructiveIdempotent

Remova uma publicação da fila. Isso é uma exclusão suave. O usuário pode restaurá-la na aba Excluídas por 30 dias. Publicações já feitas não podem ser excluídas assim. Sempre confirme com o usuário antes de chamar.

Argumento	Tipo	Descrição
post_idobrigatório	string	O id da publicação agendada para excluir.

Você diz "Cancele a publicação de terça, está desatualizada agora."

O agente chama

sprkly_delete_scheduled_post({
  "post_id": "post_abc123"
})

Exclusão suave: restaurável da aba Excluídas por 30 dias. Agentes confirmam com o usuário antes de chamar.

sprkly_draft_post Write

Componha uma legenda a partir de uma dica de conteúdo e salve como rascunho no sprkly, moldada ao limite de legenda mais restrito entre as plataformas de destino. Retorna um id de rascunho; o rascunho aparece em /drafts para o usuário revisar.

Argumento	Tipo	Descrição
content_hintobrigatório	string	Sobre o que a publicação deve ser: um tópico, frase ou mensagem-chave.
platforms	string[]	Plataformas pretendidas, usadas para escolher o teto de comprimento da legenda.
tone	string	Voz para o rascunho. casual · profissional · promocional
name	string	Rótulo opcional para o rascunho.
profile_ids	string[]	Contas opcionais para pré-selecionar no rascunho. De sprkly_list_profiles.

Você diz "Escreva algo acolhedor sobre o novo espaço do estúdio para o Instagram."

O agente chama

sprkly_draft_post({
  "content_hint": "first look at the new studio space",
  "platforms": [
    "instagram"
  ],
  "tone": "casual"
})

sprkly_export_automation_template Somente leitura

Baixe uma resposta automática do Instagram como modelo compartilhável. O arquivo contém o gatilho, a palavra-chave e a mensagem, e nunca um id de publicação, id de perfil ou detalhes de conta, então é seguro enviar para outra pessoa. Uma resposta automática que ainda é rascunho não tem nada publicado para exportar. (em breve, pendente de revisão da Meta)

Argumento	Tipo	Descrição
automation_idobrigatório	string	O id da automação para exportar.

Você diz "Envie-me minha resposta automática GUIDE para reutilizar em outra conta."

O agente chama

sprkly_export_automation_template({
  "automation_id": "flow_abc123"
})

sprkly_get_account_summary Somente leitura

Nível do plano, estado do teste, contagem de contas conectadas, contagens de publicações agendadas por status e as próximas três publicações futuras. Nunca retorna tokens ou segredos.

Sem argumentos.

Você diz "Como está minha conta sprkly?"

O agente chama

sprkly_get_account_summary({})

sprkly_get_analytics Somente leitura

Como as publicações do usuário realmente performaram: total de visualizações e engajamento, variação semana a semana / mês a mês / ano a ano, melhor horário de publicação, dia da semana e categoria de conteúdo, e as principais publicações por trás desses números. Cada recomendação carrega uma contagem de samples\ — diga o quão fina é a evidência em vez de apresentar um padrão de uma publicação como descoberta. Cada porcentagem período a período carrega as contagens de publicações e totais brutos de onde veio: cite-os, porque uma grande porcentagem sobre uma base minúscula não é uma grande mudança. topPosts\ é agrupado por plataforma e classificado apenas dentro de cada grupo; relativeToPlatformBest\ compara uma publicação com outras na PRÓPRIA plataforma e nunca entre plataformas, então use o value\ absoluto e seu rótulo metric\ para pesar uma plataforma contra outra. O Instagram contribui com alcance, salvamentos, compartilhamentos e visualizações apenas para contas conectadas ou reconectadas com a permissão de insights, e curtidas e comentários apenas para o restante. Threads e Facebook não produzem métricas. Leia coverage\ antes de comparar plataformas e nunca classifique plataformas em uma métrica que uma delas não possui.

Argumento	Tipo	Descrição
days	inteiro (1 a 730)	Quantos dias para trás analisar. Padrão 30. Planos Free leem no máximo 30 dias; planos pagos leem até 730.
profile_ids	string[]	Limite a estas contas. Omita para todas as contas que esta conexão pode ver.

Você diz "Como foram minhas publicações no mês passado e quando devo publicar?"

O agente chama

sprkly_get_analytics({
  "days": 30
})

Retorna os números e a evidência por trás deles. O conselho é seu para dar: verifique samples\ e coverage\ antes de chamar qualquer coisa de padrão.

Você diz "Qual das minhas publicações do TikTok foi melhor esta semana?"

O agente chama

sprkly_get_analytics({
  "days": 7,
  "profile_ids": [
    "prof_tiktok_main"
  ]
})

sprkly_get_billing_summary Somente leitura

Status da assinatura, plano atual, fim do período, handles comprados e os últimos eventos de cobrança. Sem detalhes de método de pagamento; o id do cliente Stripe é truncado.

Sem argumentos.

Você diz "Em qual plano estou e quando renova?"

O agente chama

sprkly_get_billing_summary({})

sprkly_get_post_approval_status Somente leitura

Se uma publicação está aguardando aprovação do proprietário, aprovada ou rejeitada, com as notas do revisor, quem pediu e carimbos de data/hora. Uma publicação rejeitada volta a ser rascunho: corrija e solicite aprovação novamente.

Argumento	Tipo	Descrição
post_idobrigatório	string	O id da publicação agendada.

Você diz "A publicação de lançamento já foi aprovada?"

O agente chama

sprkly_get_post_approval_status({
  "post_id": "post_abc123"
})

sprkly_get_post_status Somente leitura

Detalhe completo de uma publicação: status, alvos, horários agendados e publicados, link permanente e o motivo da falha se não publicou. A mídia volta como mediaIds em ordem de slide, não como links. Ids e ids de perfil são detalhes técnicos: fale com o usuário sobre contas pelo handle e sobre publicações pela legenda, e não leia ids em voz alta a menos que ele peça um.

Argumento	Tipo	Descrição
post_idobrigatório	string	O id da publicação agendada.

Você diz "O reel de ontem à noite realmente saiu?"

O agente chama

sprkly_get_post_status({
  "post_id": "post_abc123"
})

sprkly_get_tiktok_posting_options Somente leitura

Os níveis de privacidade e configurações de interação permitidos do TikTok deste criador, obtidos ao vivo do TikTok. Normalmente você NÃO precisa disso antes de agendar: sprkly_schedule_post verifica privacyLevel com esta mesma lista e, quando estiver errado, retorna os níveis que funcionariam. Chame isso apenas quando o usuário perguntar quais são as opções, ou se você quiser oferecer uma escolha a ele.

Argumento	Tipo	Descrição
profile_id obrigatório	string	O id do perfil do TikTok a consultar, de sprkly_list_profiles.

Você diz "Quais opções de privacidade eu tenho no TikTok?"

O agente chama

sprkly_get_tiktok_posting_options({
  "profile_id": "prof_tt_studio"
})

Para mostrar as escolhas ao usuário. NÃO execute antes de sprkly_schedule_post por padrão: essa chamada valida privacyLevel por conta própria e nomeia os níveis permitidos quando um está errado.

sprkly_import_automation_template Gravação

Lê um modelo de resposta automática e, opcionalmente, o configura. Sem profile_id NADA é gravado: o modelo é verificado e devolvido, o que é a primeira chamada segura. Com um profile_id, a automação é criada e entra no ar quando o gatilho puder ser satisfeito. Um gatilho que observa uma postagem (uma palavra-chave em uma postagem, ou todos os comentários em uma postagem) também precisa de post_id. Sem ele, salva como rascunho que não envia nada até que uma postagem seja escolhida. Uma palavra-chave em qualquer postagem e um DM de Perfil não precisam de post_id. Um modelo que envia DM para todos os comentaristas da conta inteira é desativado e recusado. (em breve, pendente de revisão da Meta)

Argumento	Tipo	Descrição
template obrigatório	objeto	O modelo, como um objeto ou como o texto do arquivo.
profile_id	string	A conta do Instagram na qual configurar. Deixe de fora para apenas verificar o modelo.
post_id	string	A postagem publicada a observar. Apenas para um gatilho que observa uma postagem. Deixe de fora para uma palavra-chave em qualquer postagem ou um DM de Perfil.

Você diz "Verifique este modelo que alguém me enviou."

O agente chama

sprkly_import_automation_template({
  "template": {
    "sprklyTemplate": 1,
    "name": "GUIDE reply"
  }
})

Sem profile_id, então nada é criado. Leia primeiro e depois importe de verdade.

sprkly_list_connected_social_accounts Somente leitura

Toda conta social ATIVA vinculada a esta conta sprkly: plataforma, identificador, contagem de seguidores e se precisa ser reconectada. Contas desconectadas/inativas nunca são listadas, então qualquer profileId retornado aqui é um alvo de publicação válido. Nunca retorna tokens de acesso.

Sem argumentos.

Você diz "Quais contas sociais eu tenho conectadas?"

O agente chama

sprkly_list_connected_social_accounts({})

sprkly_list_profiles Somente leitura

Os ids de perfil necessários para segmentar uma postagem, com a plataforma e o identificador de cada um. Chame isso antes de sprkly_schedule_post.

Sem argumentos.

Você diz "Onde você pode publicar para mim?"

O agente chama

sprkly_list_profiles({})

Os agentes chamam isso primeiro: os ids de perfil que retorna são o alvo de sprkly_schedule_post.

sprkly_list_scheduled_posts Somente leitura

A fila de postagens, da mais recente para a mais antiga, com uma prévia da legenda, alvos, status e motivo da falha. Suporta um filtro de status e paginação por cursor.

Argumento	Tipo	Descrição
status	string	Filtrar por status. draft · pending_approval · scheduled · posted · failed
limit	inteiro (1 a 50)	Número máximo de postagens a retornar.
cursor	string	Cursor de paginação. Passe o valor nextCursor de uma resposta anterior.

Você diz "O que eu tenho na fila esta semana?"

O agente chama

sprkly_list_scheduled_posts({
  "status": "scheduled",
  "limit": 20
})

sprkly_request_post_approval Gravação

Segura um rascunho ou postagem agendada para aprovação do proprietário. Move para pending_approval, onde nunca publica por conta própria, envia um link Aprovar por e-mail ao proprietário e retorna um id de aprovação para consultar com sprkly_get_post_approval_status. Pedir novamente uma postagem que já está aguardando retorna a mesma solicitação. Postagens aprovadas voltam para scheduled (uma postagem atrasada sai em cerca de 2 minutos); postagens rejeitadas viram rascunhos com as anotações do proprietário. Para segurar uma NOVA postagem, passe requires_approval para sprkly_schedule_post. Somente plano Power: outros planos recebem upgrade_required.

Argumento	Tipo	Descrição
post_id obrigatório	string	O id do rascunho ou postagem agendada a segurar para aprovação.
note	string	Nota opcional ao proprietário, mostrada no e-mail de aprovação.

Você diz "Agende a semana, mas me deixe aprovar antes de qualquer coisa sair."

O agente chama

sprkly_request_post_approval({
  "post_id": "post_abc123",
  "note": "Captions drafted from the Tuesday shoot. Check the TikTok hook."
})

sprkly_schedule_post Gravação

Coloca uma postagem na fila para publicação, em UMA chamada. Anexe mídia passando o link do usuário direto para media_urls: a sprkly baixa para o armazenamento por conta própria para as plataformas que precisam disso, então nenhuma ferramenta de upload precisa ser executada antes. Executa as mesmas verificações de cota, conteúdo duplicado e pré-voo de plataforma que o aplicativo sprkly. Instagram e TikTok exigem mídia no momento do envio; YouTube e TikTok exigem um título, e o TikTok também exige platform_meta.tiktok.privacyLevel — basta enviar o nível que o usuário pediu e esta ferramenta nomeia os valores permitidos se não for um deles. Ela lê os bytes reais da mídia e a resposta diz o que realmente será publicado em cada plataforma (um Reel, um carrossel de 3 slides, um conjunto de fotos, um vídeo de feed de Página) além de qualquer coisa que valha a pena repassar: transmita isso ao usuário. Confirme a data, a hora e as contas de destino com o usuário primeiro. Se uma plataforma de destino tiver mais de uma conta conectada e profile_ids não for fornecido, a ferramenta retorna needsAccountChoice com as opções em vez de agendar — coloque essa escolha para o usuário e então chame novamente.

Argumento	Tipo	Descrição
caption	string	Legenda da postagem, máximo 2200 caracteres.
platforms	string[]	Plataformas para publicar. Uma plataforma com exatamente uma conta conectada é segmentada diretamente; uma com várias faz a ferramenta responder needsAccountChoice para o usuário escolher.
profile_ids	string[]	Contas específicas para publicar, de sprkly_list_profiles. Quando fornecido, esta lista É o conjunto de alvos — as plataformas não são expandidas.
all_accounts	boolean	Publicar explicitamente em TODA conta conectada em cada plataforma listada, pulando a pergunta needsAccountChoice. Só passe true quando o usuário disser que quer todas as contas.
requires_approval	boolean	Segura a postagem até o proprietário aprovar. É salva como pending_approval e nunca publica por conta própria; o proprietário recebe um e-mail com um link Aprovar e também pode aprovar ou rejeitar no calendário sprkly. Consulte sprkly_get_post_approval_status para a resposta. Somente plano Power: outros planos recebem upgrade_required.
approval_note	string	Nota opcional ao proprietário, mostrada no e-mail de aprovação. Usada apenas com requires_approval.
scheduled_time	string	Carimbo de data/hora ISO 8601 para publicar. Deve estar no futuro. Se omitido, a postagem sai na próxima execução do publicador, cerca de um minuto a partir de agora — não há escolha inteligente de horário, então passe um horário explícito a menos que o usuário queira publicação imediata. sprkly_get_analytics pode sugerir um.
media_urls	string[]	URLs de imagem ou vídeo publicamente acessíveis para anexar, em ordem de slide. Passe links para QUALQUER plataforma. Instagram e Threads os buscam diretamente; para TikTok, YouTube e Facebook, a sprkly baixa o arquivo para o próprio armazenamento durante o agendamento, então um link também funciona lá e qualquer problema com ele é relatado agora, nesta chamada. Links de compartilhamento do Google Drive e Dropbox são convertidos automaticamente. Apenas JPEG, PNG, WebP, GIF, MP4, MOV e WebM: AVIF e HEIC (o padrão da câmera do iPhone) são recusados com instruções de reexportação, porque a sprkly não pode convertê-los. Cada arquivo deve ser publicamente acessível e ter menos de 50 MB.
media_id	string	Id de um único arquivo de mídia já enviado para a sprkly. Atalho para um media_ids de um item.
media_ids	string[]	Ids de arquivos de mídia já enviados para a sprkly, em ordem de slide. A ordem do array é a ordem publicada. Use estes quando o usuário já tiver mídia na sprkly, ou quando um arquivo for usado em várias postagens; para um link que o usuário acabou de dar, media_urls tem menos etapas. Toda foto em um conjunto deve ter a MESMA proporção ou a chamada é recusada: exporte todas a 1080x1920 (9:16), 1080x1440 (3:4), 1080x1350 (4:5) ou 1080x1080 (1:1). O Instagram aceita no máximo 10 slides; conjuntos de fotos do TikTok aceitam até 35.
title	string	Título da postagem. Obrigatório para YouTube (máximo 100 caracteres) e TikTok (máximo 150 caracteres).
category	string	Categoria de conteúdo opcional, ex. "fitness".
platform_meta	objeto	Opções de publicação específicas da plataforma, organizadas por plataforma.

Você diz "Agende isso para Instagram e TikTok na quinta às 18h."

O agente chama

sprkly_schedule_post({
  "caption": "Behind the scenes of the studio setup",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "scheduled_time": "2026-08-13T18:00:00+08:00",
  "media_id": "media_abc123",
  "title": "Behind the scenes of the studio setup",
  "platform_meta": {
    "tiktok": {
      "privacyLevel": "PUBLIC_TO_EVERYONE"
    }
  }
})

Com duas contas do Instagram conectadas, isso retorna needsAccountChoice e o agente pergunta: "Você tem 2 contas do Instagram, qual?" Então ele chama novamente com profile_ids. Postagens do TikTok precisam de um título e um privacyLevel de sprkly_get_tiktok_posting_options.

Você diz "Sim, a conta do estúdio. O mesmo para o TikTok."

O agente chama

sprkly_schedule_post({
  "caption": "Behind the scenes of the studio setup",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "profile_ids": [
    "prof_ig_studio",
    "prof_tt_studio"
  ],
  "scheduled_time": "2026-08-13T18:00:00+08:00",
  "media_id": "media_abc123",
  "title": "Behind the scenes of the studio setup",
  "platform_meta": {
    "tiktok": {
      "privacyLevel": "PUBLIC_TO_EVERYONE"
    }
  }
})

Você diz "Publique estes cinco cards como um carrossel no Instagram e no TikTok."

O agente chama

sprkly_schedule_post({
  "caption": "Five things nobody tells you about scheduling",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "scheduled_time": "2026-08-14T09:00:00+08:00",
  "media_ids": [
    "media_c1",
    "media_c2",
    "media_c3",
    "media_c4",
    "media_c5"
  ],
  "title": "Five things nobody tells you about scheduling",
  "platform_meta": {
    "tiktok": {
      "privacyLevel": "PUBLIC_TO_EVERYONE"
    }
  }
})

A ordem de media_ids é a ordem dos slides, e os ids vêm de mídia já na sprkly. Se o usuário tivesse colado cinco links, media_urls os aceitaria na mesma ordem e a sprkly puxaria cada um durante o agendamento.

Você diz "Publique isso no TikTok amanhã às 9h, só para mim por enquanto: https://drive.google.com/file/d/1AbCdEf/view?usp=sharing”

O agente chama

sprkly_schedule_post({
  "caption": "Testing the new scheduler",
  "platforms": [
    "tiktok"
  ],
  "scheduled_time": "2026-08-16T09:00:00+08:00",
  "media_urls": [
    "https://drive.google.com/file/d/1AbCdEf/view?usp=sharing"
  ],
  "title": "Testing the new scheduler",
  "platform_meta": {
    "tiktok": {
      "privacyLevel": "SELF_ONLY"
    }
  }
})

Uma chamada. O link de compartilhamento do Drive é convertido para sua forma de download e puxado para o armazenamento da sprkly durante esta chamada, então um link quebrado ou privado é relatado aqui em vez de falhar silenciosamente na hora da publicação. Não chame uma ferramenta de upload primeiro e não consulte o nível de privacidade antes.

sprkly_update_scheduled_post Gravação Idempotente

Altera a legenda, a hora de publicação, as contas de destino ou a mídia anexada em uma postagem que ainda não foi publicada. Postagens com status "scheduled", "pending_approval" ou "draft" podem ser editadas, e o status nunca muda aqui: editar uma postagem que aguarda aprovação não a aprova, e uma postagem rejeitada permanece como rascunho até você solicitar aprovação novamente. Uma postagem aguardando aprovação só pode ter uma conta como destino.

Argumento	Tipo	Descrição
post_id obrigatório	string	O id da postagem agendada.
caption	string	Legenda substituta, máximo 2200 caracteres.
scheduled_time	string	Nova hora de publicação ISO 8601. Deve estar no futuro.
profile_ids	string[]	Contas de destino substitutas. As plataformas são derivadas novamente delas.
media_id	string	Id substituto de arquivo de mídia da sprkly. Atalho para um media_ids de um item.
media_ids	string[]	Mídia substituta, em ordem de slide. Substitui o conjunto inteiro, não anexa — passe todos os slides que você quer que a postagem mantenha.

Você diz "Mude a postagem de sexta para sábado de manhã."

O agente chama

sprkly_update_scheduled_post({
  "post_id": "post_abc123",
  "scheduled_time": "2026-08-15T09:00:00+08:00"
})

sprkly_upload_media Gravação Idempotente

Envia arquivos que o usuário tem na máquina dele (slides, fotos, um vídeo curto) para a sprkly e obtém um media_id para cada um. O MODO LINK é a forma de enviar um arquivo do disco. Envie arquivos, uma entrada por arquivo com seu nome, sha256 e size_bytes. Você recebe um uploadUrl por arquivo. Faça PUT dos bytes nele: curl -sS -X PUT --data-binary @01.jpg "<uploadUrl>". Cada PUT responde com JSON contendo mediaId. Os links duram 15 minutos. Até 50 MB por arquivo e 35 arquivos por chamada. Os bytes nunca passam por você, então um carrossel inteiro custa algumas centenas de tokens. O MODO INLINE é apenas para arquivos minúsculos (alguns KB): data_base64 mais filename, no máximo 25 MB. base64 custa cerca de um token por caractere, então nunca use inline para um slide de verdade. Quando files é enviado, data_base64 e filename são ignorados. Para um link público, use media_urls em sprkly_schedule_post. Os mesmos bytes enviados duas vezes retornam o mesmo media_id.

Argumento	Tipo	Descrição
files	object[]	MODO LINK. Uma entrada por arquivo, na ordem dos slides. Obtenha os valores no Bash: sha256sum 01.jpg (primeiros 64 caracteres) e stat -c %s 01.jpg. De 1 a 35 entradas.
data_base64	string	MODO INLINE, apenas para arquivos minúsculos. O conteúdo do arquivo, codificado em base64. Alfabeto padrão ou URL-safe, com ou sem prefixo data:. Ignorado quando files é enviado.
filename	string	MODO INLINE. O nome do arquivo, por exemplo 01.jpg. Usado na resposta e em mensagens de erro. Os bytes decidem o tipo real. Ignorado quando files é enviado.
content_type	string	MODO INLINE. Dica MIME opcional, como image/jpeg. O sprkly detecta os bytes e isso prevalece.

Você diz "Publique os 5 slides em ./carousel no Instagram amanhã às 9h"

O agente chama

sprkly_upload_media({
  "files": [
    {
      "filename": "01.jpg",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "size_bytes": 183422
    },
    {
      "filename": "02.jpg",
      "sha256": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752",
      "size_bytes": 176050
    }
  ]
})

Uma chamada para todos os slides (dois mostrados). Primeiro, na pasta: for f in *.jpg; do printf '%s %s %s\n' "$f" "$(sha256sum "$f" | cut -c1-64)" "$(stat -c %s "$f")"; done. Depois, faça curl em cada arquivo para seu uploadUrl e colete os mediaIds na ordem dos nomes de arquivo. Então UMA chamada sprkly_schedule_post com media_ids definido para esses ids nessa ordem. Nunca codifique um slide em base64 e não recorra a media_urls para um arquivo em disco: não há link para fornecer.

Você diz "Envie este ícone minúsculo"

O agente chama

sprkly_upload_media({
  "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
  "filename": "dot.png"
})

Modo inline, apenas porque o arquivo tem alguns bytes. Qualquer coisa do tamanho de uma foto real passa por files.

sprkly_validate_post_policy Somente leitura

Verifique uma legenda em relação às regras de publicação de cada plataforma de destino antes de agendar: comprimento da legenda, requisitos de mídia, limites de hashtags, se links são clicáveis, títulos obrigatórios do YouTube e avisos de PII ou conteúdo proibido. Análise pura. Não grava nada.

Argumento	Tipo	Descrição
captionrequired	string	A legenda a ser verificada.
platformsrequired	string[]	Plataformas de destino para verificação.
mediaUrlsCount	integer (0 a -)	Quantas imagens ou vídeos serão anexados. Instagram e TikTok exigem pelo menos um.
hashtags	string[]	Hashtags publicadas junto com a legenda, se ainda não estiverem nela.
title	string	Título da publicação. Obrigatório para YouTube, máximo de 100 caracteres.
platformMeta	object	Opções de publicação específicas da plataforma, organizadas por plataforma.

Você diz "Verifique esta legenda primeiro contra as regras do TikTok."

O agente chama

sprkly_validate_post_policy({
  "caption": "Three edits that doubled watch time. Full breakdown in the comments.",
  "platforms": [
    "tiktok"
  ],
  "mediaUrlsCount": 1
})

Execute isso antes de agendar: ele detecta legenda longa demais, mídia ausente ou título do YouTube ausente enquanto ainda é barato corrigir.

Transporte

HTTP streamable, sem estado. Mensagens JSON-RPC 2.0 são enviadas via POST para um único endpoint e respondidas com application/json. Nenhum id de sessão é emitido, então não há nada para rastrear entre chamadas.

Método	Comportamento
POST	Carrega toda mensagem MCP. Inclua `Accept: application/json, text/event-stream`.
GET	`405`. Este servidor não oferece fluxo SSE iniciado pelo servidor.
DELETE	`405`. Sem estado, então não há sessão para encerrar.

Versões de protocolo

Negociadas em initialize: o servidor ecoa sua revisão quando a suporta; caso contrário, responde com a mais recente. Suportadas: 2025-11-25 2025-06-18 2025-03-26. Envie o valor negociado como MCP-Protocol-Version em solicitações subsequentes. Um valor não suportado é um 400.

Métodos

initialize, ping, tools/list, tools/call, resources/list e prompts/list (ambos vazios). Notificações são confirmadas com 202 e sem corpo.

Autenticação

initialize, ping e tools/list funcionam sem credenciais, para que um cliente possa mostrar o que o sprkly oferece antes de alguém entrar. O primeiro tools/call é desafiado.

O desafio 401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
  error_description="Missing bearer credentials",
  resource_metadata="https://sprkly.app/.well-known/oauth-protected-resource/api/mcp",
  scope="profile mcp:read mcp:write"

Siga resource_metadata para saber qual servidor de autorização usar. Esse documento nomeia esta origem, cujos metadados estão em https://sprkly.app/.well-known/oauth-authorization-server.

OAuth 2.1

Registro Dinâmico de Cliente (RFC 7591) e Documentos de Metadados de ID de Cliente são ambos suportados. PKCE com S256 é obrigatório.
Escopos: profile mcp:read mcp:write. Adicione offline_access para um token de atualização.
mcp:read cobre toda ferramenta somente leitura; mcp:write adiciona rascunho, agendamento e exclusão.

Escopos de chave de API

Uma chave pode conter *, sprkly:* ou qualquer um de post:read, post:write, post:draft, account:read, approval:request. Uma chave com escopo para contas específicas apenas vê e toca essas contas.

Nunca coloque uma chave de API ou token na URL do conector como parâmetro de consulta. URLs são registradas em logs, proxies e histórico do navegador, e a especificação MCP proíbe isso. Use o cabeçalho Authorization ou OAuth.

Obsoleto

Estes ainda funcionam. Nada novo precisa deles.

https://mcp.sprkly.app/mcp. Ele faz proxy para o endpoint acima. Aponte novas integrações para https://sprkly.app/api/mcp em vez disso.
POST /auth e POST /api/auth/mcp-token. A troca de chave de API para JWT. A chave de API agora é aceita diretamente como token bearer, então a troca e seu loop de atualização de 24 horas são desnecessários.

Precisa de ajuda?

O acesso MCP segue a mesma autorização que a API REST. Se um conector não conectar, o sinal mais rápido é se um tools/call não autenticado retorna um 401 com um cabeçalho WWW-Authenticate.