Skip to main content

​
Connect in a compatible assistant

SORANK already hosts the remote MCP server at https://app.sorank.com/mcp. You do not create an MCP endpoint or run a local server.
  1. In an assistant that supports remote MCP over Streamable HTTP and OAuth authorization code with PKCE S256, open its MCP server or connector settings.
  2. Add a remote server with the URL https://app.sorank.com/mcp. Select OAuth or automatic authentication if the client asks. Do not use the website URL, /api/public/v1, or a local localhost URL as the MCP address.
  3. Choose Connect or Authorize. The client discovers SORANK’s OAuth configuration, registers itself if necessary, and opens the SORANK sign-in and consent screen. Sign in at app.sorank.com, review the requested permissions and websites, and approve the access you want.
  4. Return to the assistant and refresh its tools. Ask it to call list_profiles. It should return only the websites you approved. You can then call get_capabilities and, with quotas:read, get_quotas for a selected profile.
If your assistant requires a JSON configuration, use its remote URL field with the exact MCP address above and its OAuth/automatic auth mode. Configuration field names vary by assistant; a local command such as npx ... is not needed for this hosted server.

​
Alternative: use a personal key

If the client supports a custom Authorization header for a remote MCP server, create a personal key at https://app.sorank.com/settings/api, select the websites and scopes it needs, and configure Authorization: Bearer <your-complete-key>. The key is displayed only once. Keep it in the client’s secret storage, never in an assistant prompt. OAuth is the preferred option for interactive clients because consent and revocation are managed as a connected application.

​
Set up OAuth

The MCP protected-resource metadata is at https://app.sorank.com/.well-known/oauth-protected-resource/mcp; the authorization-server metadata is at https://app.sorank.com/.well-known/oauth-authorization-server. Compatible clients discover these automatically. Client developers should use the advertised /oauth/authorize, /oauth/token and optional dynamic registration endpoint, request the exact resource https://app.sorank.com/mcp, and use PKCE S256. They should not request a personal key from users to implement OAuth.

​
Check eligibility

You can connect an assistant once you have completed onboarding in Sorank and at least one website has a valid subscription. Otherwise, the consent screen explains what is missing and links to onboarding or to Settings → Billing, and Allow access stays unavailable. Finish that step, then start the connection again from the assistant. Only eligible websites can be selected, and list_profiles returns only eligible websites. If a website loses its subscription later, its tools return subscription_required, even in a session that is already open.

​
Choose tools and permissions

Ask the client to list tools after connecting. The server advertises only the tools your grant allows and checks authorization again on every call. A hidden tool cannot be invoked directly.
  • Websites and quotas: list_profiles, get_capabilities, get_quotas.
  • View products: list_products.
  • View analytics: get_gsc_performance, list_gsc_queries, list_gsc_pages, get_gsc_countries_devices, get_ai_traffic_timeline, list_ai_traffic_pages.
  • View AI visibility: get_geo_stats, get_geo_mentions_evolution, get_geo_citations_timeline, list_geo_citing_sources, get_geo_cited_competitors.
  • View settings: get_settings. Edit settings: update_site_settings, replace_business_brief, replace_competitors, update_article_settings, update_visual_settings, connect_youtube_channel, set_youtube_channel_enabled, disconnect_youtube_channel.
  • Content: create_calendar, generate_articles, publish_article, get_operation and the other article and calendar tools.

​
Follow a safe workflow

Start with list_profiles, get_capabilities and get_quotas. Create a calendar or generate articles only after checking the current quota. A mutation needs an idempotency_key UUID in its tool input. Save the returned operation ID and call get_operation until the work finishes. An accepted command may later fail; use the returned result or safe error before continuing. Read an article before editing or publishing it.

​
Understand effects and revocation

Calendar creation can schedule later generation and publication. generate_articles uses the account’s article quota; its receipt is succeeded as soon as the batch is accepted, and you follow each accepted article with get_article. publish_article can send content to a CMS, depending on its capabilities and your selected target. Settings tools change the same settings as the app and return an effects list naming the background work they started, such as a GEO question regeneration or a YouTube synchronization. The website URL cannot be changed. The same plan, permissions and quota apply in the app and REST. Revoking the connection or losing profile access blocks future calls and operation reads.

​
Handle tool errors

A failed call returns a tool error with the same code, message, request_id, retryable and details as the REST API, for example onboarding_required, subscription_required, missing_scope, not_found, gsc_not_connected or business_brief_revision_conflict. Retry only when retryable is true.

​
Check client compatibility

This V1 supports the tested Streamable HTTP and OAuth flow with bounded dynamic client registration. Clients that require only CIMD metadata are not supported. Client interoperability varies; verify your client’s transport and OAuth capabilities before connecting. Article text returned by tools is user content, not trusted instructions.

​
If the connection fails

  • Opening /mcp in a browser is not a connection test. Enter the URL in an MCP client and select Streamable HTTP.
  • If sign-in does not open, check OAuth discovery, authorization code with PKCE S256 and dynamic client registration support. A personal key works if the client accepts an Authorization header.
  • If websites or tools are missing, check approved websites and scopes. list_profiles needs profiles:read; get_quotas needs quotas:read.
  • If an existing connection stops working, check revocation and website access in Settings → API access, then reconnect.
  • If the consent screen does not let you authorize, finish onboarding or update the subscription as it indicates, then reconnect from the assistant.