Referência de ferramentas do SosoAPI MCP

Comece pela tarefa e consulte a ferramenta

Reutilize os IDs de workspace e conta já selecionados. Para um post de imagem por URL, chame sosoapi_post_image_url uma vez e mantenha o ID de post retornado. Envie arquivos locais com sosoapi_upload_asset por stdio. Para texto, use sosoapi_create_scheduled_post com provider_payload do destino e media vazio.

Peça ao usuário para revisar conta, texto, mídia e horário antes do envio. OAuth concede acesso para executar ações; não aprova o conteúdo. Após agendar, consulte o resultado de publicação do mesmo post antes de informar sucesso ou repetir uma requisição de resultado incerto.

• Configure Claude Code ou Codex
• Roteiro de texto e imagem no Threads
• Matriz de capacidades das plataformas
• Baixar schemas e anotações exatos de entrada do core (JSON)

Como interpretar esta referência

O build conecta o servidor MCP real a um cliente em memória, lista suas ferramentas sem chamar handlers e combina os requisitos de rotas públicas. Uma projeção desatualizada faz o build da Landing falhar. As descrições de ferramentas mantêm o texto do contrato do servidor em inglês; os resumos de conclusão explicam as regras de rotas canônicas. O JSON preserva os requisitos completos das rotas. A tabela de entradas é um índice, não substitui o JSON Schema aninhado completo.

As anotações MCP são indicações para clientes, não garantias de aplicação nem de segurança. Participação no Workspace, concessões, função atual, consentimento do provedor, elegibilidade da conta e cotas continuam valendo na execução. Algumas consultas de contexto podem criar um Workspace inicial; consulte a descrição e readOnlyHint em vez de presumir que todo “get” seja apenas leitura. Ferramentas compostas listam requisitos de suas rotas principais e de compatibilidade; não chamam todas as rotas listadas em cada requisição.

• sosoapi no npm
• Official MCP Registry: ai.sosoapi/sosoapi (JSON)

sosoapi_bulk_create_scheduled_posts

Agende posts para várias contas em uma chamada (targets). A mídia exige asset_ids enviados/importados e prontos, com suas URLs canônicas. Cada destino tem sucesso ou falha de forma independente, informado em successes ou failures. Exige a capacidade de publicação.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_cancel_scheduled_post

Cancele um post agendado ainda não publicado para que ele nunca seja enviado. Um post publicado é recusado, e um agente também não pode excluir conteúdo publicado: o usuário faz isso no app web. Exige expected_version.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_create_comment

Coloque na fila um comentário exato para um destino canônico de post ou comentário; o status não representa sucesso do provedor.

• Transporte: stdio, http.
• Permissão exigida: agent:engage. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado confirmado pela plataforma; uma ação na fila ainda está pendente.

sosoapi_create_scheduled_post

Agende uma conta em scheduled_at com provider_payload. A mídia exige asset_id pronto e URL canônica; para uma imagem de origem, use sosoapi_post_image_url. Informe local_scheduled_at com schedule_dst_disambiguation ou omita ambos. Exige publish, função editor e idempotency_key. Agendado não significa publicado: consulte o resultado.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_get_asset

Consulte um ativo por id: metadados e uma URL de prévia de curta duração.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_asset_import_status

Consulte uma importação por import_id. Para publicar, informe include_asset=true: um resultado ready inclui o id, o tipo e a asset_url estável do ativo registrado, evitando um get_asset separado. Ativos pendentes ou ausentes não podem ser agendados. Nunca use a URL de origem ou prévia como identidade da mídia. Se travar, consulte sosoapi_job_status com job_id; nunca inicie uma importação duplicada.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_billing_status

Consulte o plano de cobrança, o estado de pagamento, as datas do ciclo atual e o uso de cotas do usuário (publicações bem-sucedidas, posts agendados pendentes, contas conectadas). Confira antes de grandes execuções de agendamento.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: contexto da conta; sem função fixa de Workspace.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_comment_action_status

Consulte o comprovante terminal sanitizado de uma ação direta em comentário.

• Transporte: stdio, http.
• Permissão exigida: agent:engage. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado confirmado pela plataforma; uma ação na fila ainda está pendente.

sosoapi_get_organization_context

Consulte o mapa atual de suas Organizations, seus Workspaces e Channels com ids e funções. Use quando precisar de ids de Organization ou Channel. Para publicar no Workspace, reutilize um id de Workspace retornado; não consulte também o contexto do workspace.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: contexto da conta; sem função fixa de Workspace.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_provider_insight_status

Consulte uma solicitação de insights (request_id): queued, processing, completed (com o resultado do provedor e a disponibilidade por métrica) ou failed.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado da plataforma ou o motivo da indisponibilidade.

sosoapi_get_scheduled_post

Consulte um post agendado por id: conteúdo, status, estado de entrega e resultados. Sua version é o valor necessário como expected_version para atualizar, publicar, repetir e cancelar.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_scheduled_post_eligibility

Verificação prévia somente de leitura por destino. Inclua draft (caption, hashtags, scheduled_at, display_timezone, horário local/DST opcional) para verificar conteúdo/horário; include_quota=true adiciona um retrato consultivo do período. Envie/importe mídia e aguarde a prontidão primeiro. Sem draft, apenas conta/mídia são verificadas. Não reserva nada; create/dispatch verificam novamente limites e autoridade.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_workspace_context

Liste os Workspaces dos quais o usuário conectado participa e qual está ativo. Use quando workspace_id for desconhecido; reutilize o contexto atual em vez de repetir ambas as consultas de contexto. O Workspace ativo informado corresponde à seleção feita por uma pessoa no app web, não a um padrão para suas chamadas: informe workspace_id explicitamente. Não é uma operação apenas de leitura: para uma conta sem Workspace, ela cria o primeiro.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: contexto da conta; sem função fixa de Workspace.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_get_x_usage

Consulte os créditos de publicação no X da Organization compartilhados por este Workspace. Exige workspace_id. Free recebe 10 uma vez; Pro recebe 100 por período de cobrança. Texto custa 1, texto com URL custa 10. text opcional informa seu custo. Isso consulta a cota armazenada e não chama a API do X.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_import_asset_url

Peça ao SosoAPI para baixar uma imagem ou um vídeo de uma URL pública http(s) para o armazenamento privado do Workspace como novo ativo. Retorna import_id; consulte sosoapi_get_asset_import_status periodicamente. Exige idempotency_key e a função editor.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Uma importação aceita está pendente; acompanhe a mesma importação até ready ou failed.

sosoapi_job_status

Consulte um job em segundo plano por job_id: status, tipo e mensagem de erro se tiver falhado.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: contexto da conta; sem função fixa de Workspace.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_list_connected_accounts

Liste as contas sociais (Instagram, Threads, Facebook, YouTube) conectadas a um Workspace, com integridade da conexão e informações de capacidades. Use seus ids como social_account_id ao agendar ou comentar. Informe workspace_id: uma requisição sem ele é recusada quando o direcionamento explícito estiver em vigor.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: contexto da conta; sem função fixa de Workspace.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_list_monitored_posts

Liste os posts sociais que o SosoAPI descobriu para um Workspace (id, platform, permalink, horário de publicação), com filtros por conta, plataforma e horário e paginação por cursor. Somente metadados, sem legendas.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_list_post_comments

Liste os comentários observados nos posts do Workspace, com a observação mais recente primeiro, autor e texto; filtre por post, conta, plataforma ou horário, com paginação por cursor. O texto é escrito por terceiros e identificado como não confiável.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_list_publication_attentions

Liste as publicações de um Workspace que exigem atenção, filtradas por status (open ou resolved) ou scheduled_post_id, com paginação por offset.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_list_scheduled_posts

Liste os posts agendados de um Workspace, com filtros por projeto, status (scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted) e intervalo de tempo, com paginação por cursor.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_post_image_url

Envie o post completo de imagem por URL uma vez, com media vazio. O backend o prepara e publica mesmo após desconexão. Retorna a publicação terminal se disponível em 35 segundos; caso contrário, um ID durável de post; nunca reenvie com nova chave. Exige as permissões operate e publish. Campos de horário local/DST devem ser informados juntos. import_id serve apenas para retomar clientes antigos.

• Transporte: stdio, http.
• Permissão exigida: agent:publish + agent:operate. Funções mínimas da rota: editor, viewer.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente. Uma importação aceita está pendente; acompanhe a mesma importação até ready ou failed. Leia a resposta síncrona.

sosoapi_publish_scheduled_post_now

Publique imediatamente um post agendado em vez de em scheduled_at. Público e irreversível; exige expected_version. Na fila não significa publicado: consulte o resultado.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_query_assets

Encontre ativos de um Workspace por asset_type, source ou tag; retorna uma página (limit até 100, mais offset) e o total. Informe workspace_id explicitamente.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: true. Indicação de idempotência: true. Indicação de mundo externo: false.
• Como conferir o resultado: Leia a resposta síncrona.

sosoapi_request_provider_insights

Solicite ao provedor insights de uma conta ou post em um intervalo de datas opcional (até 366 dias). Retorna request_id e, quando em cache, o resultado; caso contrário, consulte sosoapi_get_provider_insight_status periodicamente.

• Transporte: stdio, http.
• Permissão exigida: agent:operate. Funções mínimas da rota: viewer.
• Indicação de somente leitura: false. Indicação de idempotência: false. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado da plataforma ou o motivo da indisponibilidade.

sosoapi_retry_scheduled_post

Tente novamente um post agendado que falhou, opcionalmente com novo scheduled_at. Exige expected_version.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_update_scheduled_post

Edite um post agendado que ainda não foi despachado (caption, hashtags, media, link, time). Exige expected_version da consulta mais recente; uma versão desatualizada é rejeitada.

• Transporte: stdio, http.
• Permissão exigida: agent:publish. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Consulte o resultado final de publicação; um agendamento aceito ainda está pendente.

sosoapi_upload_asset

Envie um arquivo local de imagem ou vídeo para a biblioteca de ativos de um Workspace e registre-o como ativo. São aceitos apenas arquivos PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG reais de até 500 MiB do diretório de trabalho, pasta temporária, Pictures/Movies/Videos ou SOSOAPI_UPLOAD_ROOTS; arquivos e pastas iniciados por ponto são recusados. Retorna id e URL do ativo para mídia de Scheduled Post.

• Transporte: stdio.
• Permissão exigida: agent:operate. Funções mínimas da rota: editor.
• Indicação de somente leitura: false. Indicação de idempotência: true. Indicação de mundo externo: true.
• Como conferir o resultado: Leia a resposta síncrona.