Skip to main content
Match what you see against a heading below; each section gives the cause in one sentence and the fix. When a fix does not hold, write to support@surferseo.com with:
  • The client name and version.
  • The exact error text.
  • For Claude, the ofid_ reference id from the error toast or the page URL.

Adding the server

Cases that appear while the client connects, loads the tool list, or opens the sign-in page.

A connected client shows 405 Method Not Allowed

The client opened a GET or SSE stream after signing in, and the endpoint answers GET with 405 by design (Server details). Check that your client is configured for Streamable HTTP using the setup guide for your client. A plain curl of https://mcp.surferseo.com/mcp returns 401, not 405, and the response points the client at Surfer’s authorization metadata. That is correct: the endpoint requires a signed-in client.

Claude says “Couldn’t reach the MCP server”

Claude connects to Surfer from Anthropic’s infrastructure (How sign-in works), so a proxy or firewall on your machine is not the cause.
  1. Retry.
  2. If it persists, add the server in Claude Code on your own machine.
  3. If Claude Code connects, the failure sits between Anthropic and Surfer. Send support the ofid_ id.

The tool list is empty or short

Most often the client caps the tools it loads, or Surfer is not enabled for the conversation; Limits your client adds gives each client’s cap and setting.
  • Claude web and desktop: check the Tool access mode at + → Connectors → Tool access.
  • Claude Code: a short list at session start is normal; tool definitions load when Claude needs them.
  • ChatGPT web: go to + → Surfer in the composer, or type @Surfer in the message box. If you added Surfer in Developer mode, select the Surfer app for the conversation from + → Developer mode.

The client cannot reach the server on a corporate network

Claude’s remote connectors and ChatGPT web call Surfer from their providers’ infrastructure. Direct MCP connections in Claude Code, Cursor, VS Code, and local ChatGPT desktop or Codex sessions use the host machine’s network. If a local connection is blocked, ask IT to allow mcp.surferseo.com. Browser sign-in also needs access to connect.surferseo.com and app.surferseo.com, whichever client you use. A server that never appears in a managed client may be policy rather than network. Ask the administrator to allow https://mcp.surferseo.com/mcp; What an admin controls lists the clients where a server can be blocked.

The browser sign-in never returns on WSL

Terminal clients listen for the sign-in callback on localhost inside WSL, and the Windows browser does not always reach it. Configure the server in the client’s Windows-side config, or run the setup from PowerShell.
  • Claude Code desktop app: its WSL sessions do not load claude.ai connectors.
  • Codex IDE extension: turn off chatgpt.runCodexInWindowsSubsystemForLinux so Codex runs on the Windows side.
  • No keyring in WSL: if the sign-in fails for that reason, add mcp_oauth_credentials_store = "file" to config.toml.

Signing in

Cases in the sign-in flow, from the browser that does not open to a connection that has expired.

The browser does not open

In Claude Code, print the sign-in URL and open it yourself:
Open the printed URL in a browser on your own machine and authorize. If the browser then fails to load a localhost address, copy that full address from the address bar and paste it into the prompt Claude Code shows. Over SSH, connect with ssh -t so that prompt has a terminal.

”Authorization request expired” or “Something went wrong”

The consent page keeps a sign-in open for a limited time, and a stale link cannot be loaded. Restart the connection from your client. The sign-in page’s “Please try again” messages have the same fix: start again from the client.

”MCP is not available for your organizations”

None of your organizations has MCP on its plan, or you do not belong to an organization yet. The consent page shows the reason under each organization.
  1. Check the account next to Signed in as. If it is the wrong one, select Switch account.
  2. If the page says you don’t belong to any organization yet, ask your company’s Surfer admin to invite you, or write to support@surferseo.com. Otherwise, move to a plan that includes MCP.

Authorize fails with an error

  • “This organization is no longer eligible for MCP”: the organization’s plan changed while the page was open. Start a new connection from your client and choose an eligible organization.
  • Any other error: start a new connection from your client. If the error repeats, write to support@surferseo.com with the message the page shows and steps to reproduce.

It connected as the wrong Surfer account or organization

The sign-in used the account already signed in to your browser. While the consent page is open, select Switch account next to Signed in as and sign in with the other account. For a connection that is already made, and for a different organization, Disconnect or switch accounts has the steps; a connection cannot change organization in place.

The sign-in stops on an error page before Surfer’s login

A client that identifies itself to Surfer by a URL must serve that URL from a host Surfer accepts. The clients with their own setup guides do. If yours stops on an error page before Surfer’s login appears, write to support@surferseo.com with the client’s name and version.

Claude says “Authorization with the MCP server failed”

  1. Retry once.
  2. If it repeats, clear the browser’s cookies or use a different browser.
  3. Remove and re-add the connector.
Include the ofid_ id when you write to support.

invalid or expired access token, or the client asks you to sign in again

The connection expired. A tool call made before you sign in again fails with that error; see How long a connection lasts.
  • Claude web and desktop: Customize → Connectors, then Reconnect.
  • Claude Code: the notice points at /mcp; select the server, then Re-authenticate.
  • Codex: select Authenticate in the server list, or run codex mcp logout surfer then codex mcp login surfer.
  • Cursor: the row reads Needs authentication; select Authenticate (labels as shipped in Cursor 3.18.25).

Calling tools

Look for the error text in the headings below. If a message includes a tool name before the error, use the part after it.

insufficient_scope: "<tool>" requires the "<scope>" scope

Reconnect the server:
  1. Remove the server.
  2. Add it again and sign in.
  3. If it repeats, send the full text to support.

permission_denied

Read the message; each cause has its own fix:
  • MCP is not available on your current plan.: the organization’s plan stopped including MCP after you connected. The connection stays, but requests for organization data fail until the plan includes MCP again (Plans that include MCP).
  • Acting user must be an organization owner or admin with an active subscription: creating and activating a workspace need an owner or admin of an organization with an active subscription (Who can connect). Ask one to do it.
  • No message, or another one: your membership or role no longer allows the action. Check the organization you selected and ask its owner to confirm your access. To change organizations, reconnect.

unauthorized

The connection between Surfer MCP and Surfer failed authentication. Retry later. If it persists, send support the error text and client version.

quota_exceeded

Two causes:
  • The organization has no credits of the kind the tool consumes; Tools that consume credits lists which tools charge.
  • The organization is at its plan’s count of workspaces, templates, or voices; When credits run out has the fix.

rate_limit_exceeded

The organization hit its shared rate limit. The error details say how many seconds to wait; your assistant should wait that long and retry.

gsc_connection_error

The workspace’s Search Console connection needs attention. Read the message:
  • Connect Google Search Console to this workspace in Surfer.: the workspace has no Search Console property connected. Connect one in the Surfer app.
  • Reconnect this workspace's Google Search Console account in Surfer.: Google access for the connected account was revoked, expired, or deleted. Reconnect it in the Surfer app.
  • Check the connected Google account's access to this property and any administrator restrictions.: the Google account behind the connection cannot read this property, or a Google Workspace administrator policy blocks it.

gsc_quota_exceeded

Google’s Search Console quota is used up. Surfer’s own Search Console imports share that quota, so paging through a large property can also delay refreshes in the app. Stop paging and wait. Google suggests 15 minutes for load quota errors; daily limits take longer.

Other Search Console errors

  • gsc_bad_request: Google rejected the query. Check the date range, filters, and grouping. Discover and Google News cannot group or filter by query.
  • gsc_forbidden: Google denied the request. Check the connected account’s access to the property.
  • gsc_request_failed: Google could not complete the request. Retry later.
  • gsc_access_not_configured: write to support@surferseo.com.

conflict

Read the message; each cause has its own fix:
  • Content Editor must be in completed state: the Content Editor has not finished analyzing. Ask your assistant to check the editor until it has, then retry. See Content Editors.
  • An AI article is already being generated for this Content Editor or An AI article has already been generated for this Content Editor: a Content Editor can have only one AI Article, pending or completed. Read the existing article, or create a new Content Editor for another one (AI Articles).
  • Outline is not available yet or Article is not waiting for outline review: the article is not in the outline review step; check its state before reading or submitting the outline.
  • Outline regeneration is already scheduled: wait for the running regeneration to finish, then retry.
  • The page's Content Editor is already open: the recommendation’s editor exists; work in it.
  • A workspace with this name already exists: choose another name.
  • Workspace must be in ready_for_activation state: wait for setup to finish, then activate.
  • A request with this idempotency key is currently being processed: the first call is still running. Wait, then retry with the same key to get its result. For a Content Editor, you can also list Content Editors and find it by keyword.

unprocessable_entity

Surfer could not act on the request in its current state. You can act upon these errors yourself:
  • The page's Content Editor is not ready yet: wait a moment, then retry.
  • Content Editor has no sections to optimize: add headings and content to the editor, then run Auto-Optimize.
  • The AI writing system is overloaded, please retry shortly: wait, then retry.
  • Content Editor language is not supported for AI article generation: create the editor for a location whose language AI Articles support.
  • This idempotency key was already used with a different request: retry with a new key.
This one needs no action:
  • No more competitors available to load: the guidelines already hold every competitor Surfer found.
These failures are on Surfer’s side, not in your request:
  • A message that starts with Could not, such as Could not create Content Editor: Surfer failed to finish the action. Retry once. If it repeats, send the full error text to support.

not_found

Surfer found no such object for this connection. List the objects again and use a current id. Causes:
  • The id is not in the organization this connection uses.
  • The workspace exists but you are not a member of it. Over MCP, a workspace you do not belong to is not listed and cannot be reached; an organization owner or admin can add you (What connecting grants).
  • The workspace exists but is not active; read its state and activate it first (Workspaces, brand, and recommendations).
  • A content template referenced by a Content Editor was deleted.
  • The workspace has no brand. Playground workspaces have none. A new branded workspace has its brand from creation, and its knowledge fills in when setup finishes.
  • The requested outline does not exist.

validation_error

The details list names the field. Common causes:
  • A Surfer template and a custom template chosen together on one Content Editor (Content Editors).
  • A template or voice reference text outside the size limits.

internal_error, empty_response, or malformed_error_response

Surfer failed to process the request, answered with nothing, or answered with an error the server could not read. Retry once. If it repeats, send the full error text to support.

The request exceeded the timeout, or seems stuck

Workspace setup, Content Editor analysis, AI Article writing, and Auto-Optimize run as background jobs. Depending on your client, the call waits for progress or returns while work continues.
  1. Ask your assistant to check the existing workspace, Content Editor, article, or Auto-Optimize job.
  2. If it is still running, wait and check again. If an article is waiting for outline approval, review its outline before continuing.
  3. If your client cuts off a waiting call, increase its timeout using Limits your client adds.
A timeout does not tell you whether the job started. Check its state before retrying an action that creates content or spends credits.

The AI Search score shows error or unavailable

  • unavailable: AI Search scoring does not support the Content Editor’s language. Create the editor for a location in a supported language.
  • error: the calculation failed. Surfer recalculates the score when the content changes. Ask your assistant to save the content again, then read the score. If it stays in error, write to support.
The skills report either status and do not retry it.

Retry a create without making a duplicate

Creating a Content Editor, a content template, or a custom voice accepts a retry key; Ask for retry keys explains how to use it. If you are not sure the first call sent one, have your assistant list what exists, for example the Content Editors for the keyword, before creating it again. Other actions need their own status check. Before retrying article generation or Auto-Optimize, ask your assistant to read the existing job. Credits and limits explains the charging behavior.

The assistant cannot see a tool Surfer shipped recently

Most clients cache the tool list. Refresh it, then start a new conversation. Clients without a refresh control:
  • Cursor IDE: quit Cursor completely and reopen it. Cursor staff say toggling the server in Customize or Developer: Reload Window does not always pick up changes (Cursor forum, 2026-08-05).
  • ChatGPT desktop app and Codex IDE extension: select the server under Settings → MCP servers, Save, then Restart (Restart extension in the IDE).
  • Codex CLI: quit and relaunch codex.