SEO MCP Troubleshooting

Most SEO MCP problems fall into one of five categories: client support, authorization, project access, crawl state, or invalid query inputs. Start with the smallest read-only verification.

Connection checklist

1. Confirm the server URL is exactly https://mcp.screpy.com.
2. Confirm the client supports remote MCP servers and OAuth.
3. Remove any extra /mcp or /v1 path.
4. Reconnect and complete the browser authorization flow.
5. Test with: “List the SEO projects I can access.”

Common problems

The client cannot add the server

The client may support only local command-based servers or may require remote MCP to be enabled. Check the current client documentation for remote URL and OAuth support.

Authorization succeeds but tools fail

The token may be expired, revoked, missing the mcp:use scope, or tied to a no-longer-valid account session. Disconnect, revoke the old authorization if available, and reconnect.

No projects are returned

Confirm that the same Screpy member account has access to a project. Shared-project access may have changed. Do not guess a project UID as a workaround.

Crawl tools return no usable dataset

Call list_crawls and inspect status. Page, link, and image analysis normally requires a completed crawl. Do not automatically start a new crawl without user approval.

A filter is rejected

Check:

• The field is allowlisted for that record type.
• The operator matches the field type.
• Numeric values are numeric.
• contains is used only with string fields.
• The request has no more than 20 filter objects.
• Cursor values come from the immediately relevant response.

Results are incomplete

The tool may be paginated. Inspect next_cursor and continue only as far as the task requires. State any sampling limit in the final answer.

Rate limit response

Wait for the duration indicated by Retry-After. Reduce repeated calls, reuse prior results, and narrow filters. Do not loop aggressively.

Diagnostic prompt

Diagnose the SEO MCP connection without changing account state.
First call list_projects. If it fails, report the tool error category and stop.
If it succeeds, call list_crawls for the selected project and explain
whether a completed dataset is available.
Do not invent identifiers or retry repeatedly.

When to reconnect

Reconnect after a revoked grant, changed account identity, client credential reset, or persistent authorization failure. A filter validation error or incomplete crawl does not normally require reconnecting.