> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect an assistant with MCP > Set up OAuth access to the SORANK MCP server and use its public tools safely. ## 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 `. 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.