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 [email protected] 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: choose Developer mode from the plus menu in the composer and select the Surfer app for the conversation.

​
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; the consent page shows the reason under each one, as What you approve describes. Credits and limits says which plans include it. Two other messages on the page:
  • A message that you do not belong to any organization yet: write to support.
  • “This organization is no longer eligible for MCP” when Authorize fails: the plan changed while the page was open.

​
It connected as the wrong Surfer account or organization

The sign-in used the account already signed in to your browser, and a connection cannot change organization. Disconnect or switch accounts has the steps for both.

​
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.
  • Cursor: the row reads Needs authentication; select Authenticate (labels as shipped in Cursor 3.18.25).
  • Codex: select Authenticate in the server list, or run codex mcp logout surfer then codex mcp login surfer.

​
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

Signing in grants every scope (What connecting grants), so this should not occur.
  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 (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.

​
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: read the existing article instead of generating again (AI Articles and Auto-Optimize).
  • 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.
  • An outline regeneration is already running: wait for it 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 for it.

​
unprocessable_entity

Surfer could not act on the request in its current state. Two messages are worth a retry; the rest are final.
  • The page's Content Editor is not ready yet: wait a moment, then retry (Workspaces, brand, and recommendations).
  • The AI writing system is overloaded, please retry shortly: wait, then retry.
  • Content Editor has no sections to optimize: add headings and content to the editor first.
  • Content Editor language is not supported for AI article generation: create the editor in a supported language.
  • No more competitors available to load: the guidelines already hold every competitor found; nothing to retry.
  • This idempotency key was already used with a different request: pick a new key.

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

​
”Brand names that contain commas are not supported.”

The AI Tracker comparison cannot accept a competitor name containing a comma. Omit the competitor list to use the project’s top three competitors by mention count, or use names without commas.

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

​
Retry a create without making a duplicate

Content Editor, content template, and custom voice creation accept an idempotency key: a unique label your assistant supplies for one intended create.
  • On a retry of the same create, reuse the key and the same inputs. Surfer returns the original result.
  • For a different create, use a new key.
  • If the first request is still processing, wait before retrying it.
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.