MCP Troubleshooting
Connection failures, missing tools, empty results, rate limits, and quota errors when using the VitalSentinel MCP server, and how to fix them.
The client cannot connect at all
Check the URL. It is https://mcp.vitalsentinel.com/mcp, including the /mcp path. A URL ending at the hostname will not work.
Check that your client supports remote MCP servers over streamable HTTP. Older clients only speak the local stdio transport, and there is no local package to point them at. This server is remote only.
Check your plan. Custom connectors are a paid feature in most AI assistants. If you cannot find where to add one, your plan may not include them.
The browser sign-in never completes
The consent flow opens a VitalSentinel page, asks you to sign in if you are not already, and then shows a screen naming the app, its redirect URI, the permissions requested, and a workspace picker.
If it stops before that:
- You must select at least one workspace. The approve action stays disabled until you do.
- The request handle expires after ten minutes. If you left the tab open, start over from your client.
- An "unverified" warning is normal. Any self-registered client shows it. It means VitalSentinel has not reviewed that app, not that anything is broken. Read the redirect URI shown on the screen and decide whether you recognize it.
A tool I expected is missing
The tool list is built once per connection, from what your credential can actually do. A tool you cannot use is not shown at all.
Work through these in order:
- Is it a write or run tool, on a connection made before 5 August 2026? Browser sign-ins used to be granted read scopes only. Reconnect so you are asked to consent again, or connect with an API key carrying those scopes.
- Does the credential hold the scope? Ask the assistant to check, or call
GET /meon the API and readeffective_scopes. - Is
effective_scopesnarrower thanscopes? Then the workspace role of whoever created the credential is stripping it. A member is read-only across every module except alert rules and notification preferences. See Scopes. - Did you just widen the scopes? You have to reconnect. The tool list was built when the session opened and does not refresh in place. Disconnect and reconnect the server in your client.
"Your workspace role is member; this requires admin"
The scope is granted, but your role forbids the operation. A new credential will not fix this. A workspace owner has to change your role, or an admin has to perform the action.
This is the same rule the dashboard enforces. If you cannot do it in the app, the assistant cannot do it either.
"This connection does not have write:..."
The credential was never granted that scope. On a browser sign-in, reconnect so you are asked to consent again, since connections made before 5 August 2026 were granted read scopes only. On an API key, create a new one carrying the scope under Settings → API access, then reconnect.
The message names the closest scope you do hold, so This connection has read:crux but not write:crux tells you exactly what to add.
A tool returns nothing, or all zeros
Almost always a data problem rather than a permissions problem:
| Symptom | Likely cause |
|---|---|
Indexing counts all zero, gsc_linked is false | No Search Console property is linked to this domain |
| Search Console data missing for the last two days | Google's data lags roughly two days. This is normal, and the tools default their end date accordingly |
| RUM tools empty | The RUM script is not installed, or has not collected data yet. Ask for get_rum_overview and check the event count |
A module block is null in a health or overview result | That module is not configured for the domain, which is not an error. configured_modules in the same result lists what is, and a configured module with nothing to report comes back present but empty rather than null. RUM and analytics never appear in configured_modules, so a null block for either means only that it has no data |
| Analytics empty | The analytics script is not installed on the site |
SSL tool returns not-found, or reports unknown | The certificate chain check has not run for this domain yet. It runs once a day, so a newly added domain answers within a day. If the domain is also monitored for uptime, the tool can answer with an expiry date alone and source set to uptime_checker, leaving issuer, chain validity, and HSTS unknown. Read scan_status, not source, to tell whether the chain scan has run |
Check unavailable_modules in a health or overview result before concluding a module has no data. A module that failed is named there, and the others still answer.
"Showing 50 of 1,240"
That is working as intended. Tool results are capped so they do not flood the context window, and the cut is always announced along with what to do about it.
A trimmed list carries a cursor counting the rows you actually received, not the rows the API sent, so continuing from it does not skip anything. A tool that takes no paging arguments has no cursor to offer, and its notice asks you to narrow the date range or the filters and call again instead. Follow whichever the notice names. A narrower window usually beats paging through everything.
A result too large to trim is refused outright rather than returned in part. The error names the tool, roughly how many tokens it produced, and the 15,000 token per-result cap. Waiting does not help. Call again with a smaller limit, a narrower date range, or a tighter filter.
Rate limit errors
Rate limit reached (heavy-query bucket). Retry after 34 seconds, or narrow the date range so the query costs less.
Analytical reads over a time range sit in a tighter bucket, and only five can run at once per connection. An assistant fanning out across many domains will hit this. The fix is in the message: wait, or ask for a narrower window.
RUM reads sit in a tighter bucket still, rum-read, at 20 requests a minute. It is what you hit first on any RUM tool, so a fan-out across RUM runs out of room sooner than a fan-out across anything else.
See Rate limits.
Credit or quota errors
These are not rate limits, and waiting a few seconds does not help.
| Message names | What it means | What to do |
|---|---|---|
credits | The workspace has spent its API credit allowance for the cycle | Wait for the cycle to reset, or upgrade the plan |
member credits | Your personal cap is spent, but the workspace has balance | Ask the workspace owner to raise or clear your cap |
get_credit_balance always works, even at a zero balance, so the assistant can always tell you which of these applies and when it resets.
If the connection covers several workspaces, ask it to check the workspace that owns the domain you were asking about. Each workspace has its own allowance, so the connection's default workspace can look healthy while the one you were reading from is empty. list_credit_balances answers that in one call, returning a balance per accessible workspace plus a total across all of them, with the caveat that the workspaces do not share a billing cycle.
The assistant quotes a number I do not recognize
Two common causes, both legitimate:
CrUX versus RUM. get_core_web_vitals reads either Google's public field dataset or your own real-user data. They measure different populations and rarely agree exactly. The assistant is instructed to name which one it is quoting; if it did not, ask.
A cached block. Both get_domain_health and get_domain_overview read module caches that can be up to an hour old, and robots.txt up to five minutes. get_domain_health reports its own staleness as cache_age_seconds and accepts live freshness to recompute; get_domain_overview has neither. Ask for get_domain_health with live freshness, or get_uptime_status, which is never cached.
The assistant suggested something odd after reading site data
Content harvested from monitored sites, including page titles, robots.txt bodies, and error messages, is marked as untrusted data and never merged into the server's own prose. Instruction-shaped text is flagged rather than silently removed.
If an assistant appears to be acting on instructions found in your site's content, that is worth reporting. Include the tool it called and the domain. See Security for how the defense works and where its boundaries are.
The connection drops or times out
Sessions are held in memory and are not persisted across restarts. If the server restarts, your client reconnects and re-authenticates transparently.
Access tokens last 60 minutes and refresh automatically. You will be asked to sign in again only if you revoked the connection, or left it unused past the 90-day refresh window.
If your client shows a connection that never becomes ready, remove it and add it again. That is faster than diagnosing a stuck session.
Getting help
For anything else, include:
- The tool name the assistant called
- The exact error message
- Your workspace and domain, if the problem is specific to one
- The request identifier, if the message carries one
Every API response carries an X-Request-Id, and it is what lets support find the exact request. See Getting help.
