The agent says it has no Surnex tools
The server isn’t connected. Check in order:- Restart the client. Most read MCP config only at startup, so an edit made while running hasn’t been picked up.
- Check the URL is exactly
https://api.surnex.io/mcp. - Check the transport is
http— the server doesn’t support stdio. - Validate the JSON. A trailing comma or missing brace makes the client skip the entry silently, with no error shown.
list_organizations.
”This endpoint uses OAuth, not API keys”
You’ve configured an API key. The MCP server doesn’t accept them — it uses OAuth. Remove the credential entirely from your config. There’s nothing to replace it with; the client obtains a token itself:smx_-prefixed key is sent as a bearer token — it’s recognized and refused by name rather than failing as an invalid token.
The consent screen never appears
The client should open a browser on first use. If nothing happens:- Check the client supports OAuth for MCP. Older versions handle only header-authenticated servers and will stall on the 401.
- Restart the client after editing config — most read it only at startup.
- Check the URL is exactly
https://api.surnex.io/mcp.
WWW-Authenticate header on the 401 and fetching the metadata. You can confirm the server’s half is working:
WWW-Authenticate header pointing at the metadata path; the second should return a JSON document naming the authorization server. If both look right, the problem is on the client side.
Access drops about once an hour
The token was issued withoutoffline_access, so there’s no refresh token and the access token expires after an hour.
Reconnect and make sure the consent screen lists “Stay connected without asking you again every hour”. If your client requests scopes explicitly, it needs offline_access.
Token errors
Reconnecting the client resolves nearly all of these.
”You belong to more than one organization, so this call is ambiguous”
Not an error — the server refusing to guess. The message lists your organizations with their ids. Name the one you mean in your prompt:Check rankings for example.com in the Acme organization.Org-scoped tools take an optional
organization argument, by name or id. It’s resolved automatically only when you belong to exactly one. See MCP authentication.
The agent can’t see a project
Two possibilities:- It’s in an organization you’re not a member of. The token acts as you, so it reaches your memberships and nothing else. A project you can’t open in the dashboard isn’t reachable here either.
- You have several organizations and the tool resolved a different one. Name the organization explicitly.
A tool is refused but the data exists
The token carries your role, so the agent can only do what you can. A member’s connection can’t create or delete a project; an admin’s or owner’s can. See Roles and permissions. Tools can also never mint an API key, change billing, or invite and remove people, whatever your role.Tools return empty data
Usually not an error — most Surnex data is collected in the background, so a tool returns what’s stored:- A new project has nothing until its first collection run finishes. A new project’s first rankings arrive within minutes, and each scheduled check’s within about half an hour of it starting; a full audit can take an hour.
- Audits and web vitals don’t run on a schedule.
get_audit_summaryreturns the last crawl, which may be old. Have the agent callstart_site_auditfor fresh data. - Ranking changes need two checks. A project on its first day has no movement to report.
Quota errors
Tools that call external services fail withUSAGE_LIMIT_EXCEEDED when a monthly allowance is exhausted:
- Research, SERP, trends, domain, content and backlink tools — including
refresh_backlinksandget_backlink_gap— draw on research lookups start_site_auditandtrigger_web_vitals_checkdraw on site audit pages — an audit spends the pages it crawls, a vitals check one page- AI search tools draw on AI brand audits, one per run
add_local_location) fails the same way when the organization already holds its plan’s limit. Local keywords don’t use an allowance of their own, but each location takes at most 10.
Check get_usage_summary or the Usage page. Monthly allowances reset on the 1st of the month, UTC.
If every billable tool fails with PLAN_REQUIRED, the organization’s trial or subscription has ended. Reading stored data still works; an admin or owner needs to choose a plan in the dashboard.
The agent did something you didn’t want
Several tools write, anddelete_project is irreversible. If your client supports tool approval, turn it on — it’s the only safeguard, since the API applies no confirmation step of its own.
Deleted project data cannot be recovered. Ranking and backlink history is accumulated daily and there’s no back-fill.
Wrong locale in results
Project tools — adding keywords and prompts, the AI searches, the listing search — use the project’s own market for that service when location and language are left out. Research, trends and domain lookups default to location2840 (United States) and language en.
State the market in your prompt if it isn’t the US.