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. The consent screen names the application asking for access and shows where the authorization is sent.
  • Verified: the authorization goes to the official address of a known assistant, such as Claude or ChatGPT. SORANK then shows that assistant’s name.
  • On this computer: the application runs on your own computer, such as a desktop assistant or a coding tool. Allow access only if you started the connection yourself.
  • Unverified: any other address. The application’s name is chosen by whoever registered it, so check the address before you allow access.
Select all ticks every website, or every permission of a group, in one click. Read permissions are preselected; changes and actions are always your choice.

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.
  • Research and generate keywords: research_keywords, get_keyword_metrics, generate_keywords. Follow a full keyword search with get_keyword_run.
  • View improvements: get_audit, list_audit_pages, estimate_audit_fixes, list_audit_fixes. Run audits and fix articles: start_audit, recheck_audit_page, fix_audit_page, apply_audit_fix, restore_audit_fix, fix_audit_bulk.
  • Refresh products: refresh_product_catalog. View articles: get_article_index_status.
  • View AI visibility: list_geo_prompts. Edit AI visibility prompts: create_geo_prompts, update_geo_prompt, delete_geo_prompts.
  • View backlinks: get_backlinks, list_backlink_quests. Manage backlinks and quests: update_backlink_settings, claim_backlink_quest.
  • View invoices: list_invoices.
  • 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. On a Framer site, get_publication also returns site_deploy. Framer shows a change only after a site publish, which Sorank runs about a minute after each change: pending means public_url does not show the last change yet, and live means it does. While the state is pending, last_error_code names the error of the last failed deploy, for example cms_token_expired when the Framer API key must be replaced. When a publication fails, get_publication returns status failed with last_error.code publication_failed. When Sorank recorded the cause, last_error.reason names it, for example site_unreachable: Sorank could not connect to the site, so check that it is online and that its host or firewall does not block Sorank. New reasons may be added: handle an unknown one as a generic failure. On a PrestaShop shop connected with a Webservice key, without the Sorank module, update_published_article cannot change the address of a published page. If you changed the article’s slug, the operation ends failed with publication_change_failed. Restore the published slug, or install the Sorank module on the shop.

Spend AI credits and fix articles

Keyword research, full keyword searches and article fixes use the website’s AI credits, at the same price as in the app. get_quotas returns the balance and the current price of each action. Call estimate_audit_fixes before fixing a page or the whole site: it returns the cost and debits nothing. When the balance is too low, the tool returns insufficient_credits with details.required and details.balance. A keyword research that fails is refunded. fix_audit_page prepares the fixes you choose, or a full rewrite. apply_audit_fix then writes a fix to the article on your CMS, and restore_audit_fix puts the previous version back; both also need Publish articles. fix_audit_bulk fixes the whole site and applies each fix itself; it also needs Generate articles and Publish articles. start_audit uses the website’s audit quota, and only one audit runs at a time.

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.