MCP troubleshooting
Use this page when a client cannot connect, tools are missing, or a tool call fails.
Connection Fails
Section titled “Connection Fails”Check:
- The endpoint is correct.
- The client supports remote MCP or uses a compatible proxy.
- The token or OAuth authorization is still active.
- The Authorization header is exactly
Bearer <token>when using bearer tokens.
Hosted endpoint:
https://mcp.sleepwalker.ai/mcpTools Are Missing
Section titled “Tools Are Missing”Available tools depend on scopes.
| Symptom | Likely cause |
|---|---|
| Only read tools appear. | The connection has read-only scopes. |
| Action tools are missing. | The token or OAuth connection does not include action scopes. |
| Run status tools appear but create tools do not. | The connection can read runs but cannot create billable work. |
Open the Sleepwalker app and review the token or connection in MCP.
Authentication Errors
Section titled “Authentication Errors”| Error | Meaning |
|---|---|
| Missing Authorization header | Bearer-token clients must send Authorization: Bearer sw_mcp_live_.... |
| Invalid token | The token is wrong, expired, or revoked. |
| Missing scope | The token is valid but cannot call that tool. |
If a token was exposed, revoke it and create a new one.
Insufficient Credits
Section titled “Insufficient Credits”Billable tools can fail when the account does not have enough credits.
Top up from Add Credits in the Sleepwalker app, then retry.
For large AI Visibility runs, Sleepwalker may queue only the funded probes and mark the rest as skipped.
Long Or Truncated Responses
Section titled “Long Or Truncated Responses”Use chunking instead of requesting everything at once.
| Data | Tool |
|---|---|
| Long page content | serialize_sleepwalker_page_content with offset. |
| Long AI Visibility response | get_sleepwalker_prompt_response with offset. |
| Large run result | Status tools first, include full results only when needed. |
Client-Specific Notes
Section titled “Client-Specific Notes”Some desktop clients require a local proxy for hosted MCP servers.
When using a proxy:
- keep tokens in environment variables
- avoid query-string tokens
- restart the client after editing its MCP config
- confirm the client is using the updated config file
Safe First Test
Section titled “Safe First Test”Ask the client:
Use Sleepwalker to list my tests.If this works, the connection and read scope are valid.
Then test one bounded action, such as page serialization, before running larger jobs.