Troubleshooting

Work down the list; each step rules out a layer.

1. Is the server reachable?

curl -s https://mcp.hypervalent.io/health

{"ok":true} means the service is up. Anything else: check status.hypervalent.io.

2. Does the token work?

Send a raw initialize with your token (see Testing with curl). A JSON-RPC result means the token and org id are fine and the problem is in the client. A JSON-RPC error:

data.code	Fix
API_TOKEN_REQUIRED	The header is missing — check quoting in your config
INVALID_API_TOKEN	Revoked, expired, or the org in the URL is not the token's organization
FEATURE_DISABLED	The organization is not on the Team plan

3. Client-specific checks

Claude Desktop

• The server is not listed at all. The config file was not read: it is not at the expected path, is not valid JSON, or Claude Desktop was not fully quit (⌘Q) and relaunched.
• Listed but "failed". Read ~/Library/Logs/Claude/mcp-server-hypervalent.log.
  • spawn npx ENOENT or a similar launch failure → npx is not on Claude Desktop's PATH. Put the absolute path to npx in command.
  • Authentication error / 401 → the token placeholder (atk_xxxxxxxx…) from Studio was pasted as-is. Replace it with the full token.
  • Nothing after "connecting" → a proxy or firewall is blocking mcp.hypervalent.io.
• Worked yesterday, fails today. The token expired or was regenerated. Tokens show their expiry on the API tokens page.

Claude Code

• claude mcp list shows the server as failed → run claude mcp get hypervalent to see the stored URL and header, then re-add with claude mcp remove hypervalent and the snippet.
• Tools are missing from a session started before the server was added → /mcp to reconnect, or start a new session.

Cursor

• Red dot in Settings → MCP → hover it; a 401 is the token, a network error is connectivity.
• Tools not offered to the model although the server is green → too many tools enabled across servers. Disable unused servers.

4. The assistant connects but calls fail

Symptom	Cause
Every tool answers PROJECT_REQUIRED	Organization-wide token; tell the assistant the project or narrow the token
Writes answer TOKEN_SCOPE_READ_ONLY	Read token; create a read + write one
A save answers VERSION_LOCKED	Someone has the document open in the editor
A document the assistant just created is NOT_FOUND on read	It read the published view; drafts need status: "draft"
RATE_LIMITED with a long wait	The daily write cap; see what the assistant is looping on
QUERY_FAILED	An API-side failure; retry, then contact support with the time

The full code list is in Errors & limits.

5. Still stuck

Email support@hypervalent.io with the client, the time of the failing call, the tool name and the error the assistant showed. Never send the token itself — the token's prefix (atk_xxxxxxxx) is enough for us to find it in the logs.