Saltar para o conteúdo principal

Ligar um assistente

A SORANK já aloja o servidor MCP remoto em https://app.sorank.com/mcp. Não precisa de criar um endpoint MCP nem de executar um servidor local.
  1. Num assistente compatível com MCP remoto por Streamable HTTP e OAuth authorization code com PKCE S256, abra as definições MCP ou de conectores.
  2. Adicione um servidor remoto com o URL https://app.sorank.com/mcp. Escolha OAuth ou autenticação automática. O site, /api/public/v1 e localhost não são o endereço MCP.
  3. Clique em Ligar ou Autorizar. O cliente descobre a configuração OAuth, regista-se se necessário e abre o início de sessão da SORANK. Confirme os scopes e sites pedidos antes de aprovar.
  4. Volte ao assistente, atualize as ferramentas e chame list_profiles. Só aparecem os sites autorizados. Depois use get_capabilities e, com quotas:read, get_quotas.
Se o cliente exigir JSON, introduza este endereço no campo URL remoto e escolha OAuth. Os nomes dos campos dependem do cliente; este servidor alojado não exige um comando local npx.

Ler o ecrã de consentimento

O ecrã de consentimento indica que aplicação pede o acesso e para onde é enviada a autorização.
  • Verificado: a autorização segue para o endereço oficial de um assistente conhecido, como o Claude ou o ChatGPT. A SORANK mostra então o nome desse assistente.
  • Neste computador: a aplicação é executada no seu próprio computador, como um assistente de ambiente de trabalho ou uma ferramenta de desenvolvimento. Permita o acesso apenas se tiver iniciado a ligação.
  • Não verificado: qualquer outro endereço. O nome da aplicação é escolhido por quem a registou: verifique o endereço antes de permitir o acesso.
Selecionar tudo marca com um clique todos os sites, ou todas as permissões de um grupo. As permissões de leitura vêm pré-selecionadas; as alterações e ações são sempre uma escolha sua.

Alternativa com chave pessoal

Se o cliente aceitar um cabeçalho Authorization personalizado para MCP remoto, crie uma chave em https://app.sorank.com/settings/api com os sites e scopes necessários. Configure Authorization: Bearer <chave-completa> no armazenamento seguro do cliente, nunca no prompt. A chave completa só aparece uma vez. OAuth é preferível para clientes interativos.

Configurar OAuth

Os metadados do recurso MCP estão em https://app.sorank.com/.well-known/oauth-protected-resource/mcp e os do servidor de autorização em https://app.sorank.com/.well-known/oauth-authorization-server. Os clientes compatíveis descobrem-nos automaticamente. Quem desenvolve clientes usa os endpoints OAuth anunciados, PKCE S256 e o recurso exato https://app.sorank.com/mcp.

Verificar a elegibilidade

Pode ligar um assistente depois de concluir o onboarding na Sorank e se pelo menos um site tiver uma subscrição válida. Caso contrário, o ecrã de consentimento explica o que falta, tem uma ligação para o onboarding ou para Definições → Faturação, e Permitir acesso fica indisponível. Conclua esse passo e volte a iniciar a ligação a partir do assistente. Só é possível selecionar sites elegíveis, e list_profiles devolve apenas sites elegíveis. Se um site perder a subscrição mais tarde, as suas ferramentas devolvem subscription_required, mesmo numa sessão já aberta.

Escolher ferramentas e permissões

Peça ao cliente para listar as ferramentas depois de ligar. O servidor só anuncia as ferramentas permitidas pela sua autorização e volta a verificá-la em cada chamada. Uma ferramenta oculta não pode ser chamada diretamente.
  • Sites e quotas: list_profiles, get_capabilities, get_quotas.
  • Ver produtos: list_products.
  • Ver análises: get_gsc_performance, list_gsc_queries, list_gsc_pages, get_gsc_countries_devices, get_ai_traffic_timeline, list_ai_traffic_pages.
  • Ver visibilidade de IA: get_geo_stats, get_geo_mentions_evolution, get_geo_citations_timeline, list_geo_citing_sources, get_geo_cited_competitors.
  • Ver configurações: get_settings. Editar configurações: update_site_settings, replace_business_brief, replace_competitors, update_article_settings, update_visual_settings, connect_youtube_channel, set_youtube_channel_enabled, disconnect_youtube_channel.
  • Pesquisar e gerar palavras-chave: research_keywords, get_keyword_metrics, generate_keywords. Acompanhe uma pesquisa completa de palavras-chave com get_keyword_run.
  • Ver melhorias: get_audit, list_audit_pages, estimate_audit_fixes, list_audit_fixes. Executar auditorias e corrigir artigos: start_audit, recheck_audit_page, fix_audit_page, apply_audit_fix, restore_audit_fix, fix_audit_bulk.
  • Atualizar produtos: refresh_product_catalog. Ver artigos: get_article_index_status.
  • Ver visibilidade de IA: list_geo_prompts. Editar prompts de visibilidade de IA: create_geo_prompts, update_geo_prompt, delete_geo_prompts.
  • Ver backlinks: get_backlinks, list_backlink_quests. Gerenciar backlinks e missões: update_backlink_settings, claim_backlink_quest.
  • Ver faturas: list_invoices.
  • Conteúdo: create_calendar, generate_articles, publish_article, get_operation e as outras ferramentas de artigos e calendário.

Seguir um fluxo seguro

Comece com list_profiles, get_capabilities e get_quotas. Crie um calendário ou gere artigos após confirmar a quota. Cada alteração exige um UUID idempotency_key nos parâmetros. Guarde o ID da operação e consulte get_operation até terminar. Um comando aceite pode falhar depois; verifique resultado ou erro. Leia o artigo antes de o editar ou publicar.

Efeitos e revogação

Criar um calendário pode agendar gerações e publicações posteriores. generate_articles usa a quota de artigos da conta; o seu recibo fica succeeded assim que o lote é aceite, e acompanha cada artigo aceite com get_article. publish_article pode enviar conteúdo para um CMS, conforme as suas capacidades e o destino escolhido. As ferramentas de definições alteram as mesmas definições que a aplicação e devolvem uma lista effects com os processos iniciados em segundo plano, como uma regeneração das perguntas GEO ou uma sincronização do YouTube. O URL do site não pode ser alterado. O mesmo plano, permissões e quota aplicam-se na aplicação e em REST. Revogar a ligação ou perder o acesso ao site bloqueia as chamadas e leituras de operações seguintes. Num site Framer, get_publication também devolve site_deploy. O Framer só mostra uma alteração depois de uma publicação do site, que o Sorank inicia cerca de um minuto após cada alteração: pending significa que public_url ainda não mostra a última alteração, e live que ela já está online. Enquanto o estado for pending, last_error_code indica o erro da última implementação falhada, por exemplo cms_token_expired quando a chave API do Framer tem de ser substituída. Quando uma publicação falha, get_publication devolve status failed com last_error.code publication_failed. Quando o Sorank registou a causa, last_error.reason indica-a, por exemplo site_unreachable: o Sorank não conseguiu ligar-se ao site, por isso verifique se está online e se o alojamento ou a firewall não bloqueiam o Sorank. Podem ser adicionadas novas causas: trate uma causa desconhecida como uma falha genérica. Numa loja PrestaShop ligada com uma chave de Webservice, sem o módulo Sorank, update_published_article não consegue alterar o endereço de uma página publicada. Se alterou o slug do artigo, a operação termina em failed com publication_change_failed. Reponha o slug publicado ou instale o módulo Sorank na loja.

Gastar créditos de IA e corrigir artigos

A pesquisa de palavras-chave, as pesquisas completas de palavras-chave e as correções de artigos usam os créditos de IA do site, ao mesmo preço que na aplicação. get_quotas devolve o saldo e o preço atual de cada ação. Chame estimate_audit_fixes antes de corrigir uma página ou o site inteiro: devolve o custo e não debita nada. Se o saldo não chegar, a ferramenta devolve insufficient_credits com details.required e details.balance. Uma pesquisa de palavras-chave que falhe é reembolsada. fix_audit_page prepara as correções escolhidas, ou uma reescrita completa. apply_audit_fix escreve depois uma correção no artigo do seu CMS, e restore_audit_fix repõe a versão anterior; ambas requerem também Publicar artigos. fix_audit_bulk corrige o site inteiro e aplica cada correção por si; requer também Gerar artigos e Publicar artigos. start_audit usa a quota de auditorias do site, e só é executada uma auditoria de cada vez.

Tratar erros das ferramentas

Uma chamada falhada devolve um erro de ferramenta com os mesmos code, message, request_id, retryable e details que a API REST, por exemplo onboarding_required, subscription_required, missing_scope, not_found, gsc_not_connected ou business_brief_revision_conflict. Repita apenas quando retryable for true.

Verificar compatibilidade

Esta V1 suporta o transporte Streamable HTTP e o fluxo OAuth testados, com registo dinâmico limitado. Não suporta clientes que exigem apenas metadados CIMD. Confirme as capacidades do cliente antes de o ligar. O texto dos artigos devolvidos é conteúdo do utilizador, não uma instrução fiável.

Se a ligação falhar

  • Abrir /mcp no navegador não testa MCP. Introduza o URL num cliente MCP e escolha Streamable HTTP.
  • Se o início de sessão não abrir, confirme OAuth discovery, authorization code com PKCE S256 e registo dinâmico. Uma chave pessoal funciona se o cliente aceitar um cabeçalho Authorization.
  • Se faltarem sites ou ferramentas, reveja os sites e scopes aprovados. list_profiles precisa de profiles:read; get_quotas precisa de quotas:read.
  • Se uma ligação deixar de funcionar, verifique a revogação e o acesso aos sites em Definições → Acesso à API e volte a ligá-la.
  • Se o ecrã de consentimento não permitir autorizar, conclua o onboarding ou atualize a subscrição conforme indicado e volte a ligar a partir do assistente.