Skip to main content

​
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.

​
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.
  • 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.

​
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.