tokconnectStart with the failure stage. A client can fail before it reaches TokConnect, TokConnect can reject a bearer key, a connected client can hide the server's tools, and a successful tool call can return no records. Changing the keyword cannot repair an absent header.
Check the fixed connection values
TokConnect uses one hosted MCP endpoint and one authentication scheme:
URL: https://mcp.tokconnect.com/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer YOUR_TOKCONNECT_KEYGet the key from TokConnect. A client that labels the server httpUrl, url, or a Streamable HTTP transport uses a client-specific configuration shape. Do not point it at a guessed REST path such as /api/search. TokConnect does not publish per-tool REST endpoints.
Use a stage-by-stage check
- Configuration: confirm the exact client file, valid JSON, YAML, or TOML, and the endpoint above.
- Client discovery: use that client's MCP status command or tools panel. A server missing here has not reached TokConnect.
- Authentication: inspect a 401, unauthorized response, or unavailable token in the process that launched the client.
- Tool visibility: check enablement, allowlists, and client approval before changing the request.
- Research response: evaluate fields, cursors, and service errors only after a tool actually ran.
Work in that order and change one value per retry. A request that returns an MCP error reached farther than an entry that never appears in a tools panel. Recording the stage prevents a copied configuration fix from hiding the original symptom.
Read auth errors as auth errors
A 401 or an unauthorized response means TokConnect did not accept the Authorization header. Check the exact header name, the space after Bearer, and the token source. A shell export only reaches a CLI process you launch from that shell; a desktop client or background gateway can run with a different environment.
| Client | Status check | Credential location to inspect |
|---|---|---|
| Claude Code | /mcp or claude mcp list | Configured header or the shell variable used in a shared .mcp.json. |
| Codex | /mcp or codex mcp list | The variable named by bearer_token_env_var. |
| Gemini CLI | /mcp or gemini mcp list | The stored HTTP header in settings.json. |
| OpenClaw | openclaw mcp status --verbose, then probe | The gateway or runtime environment used in mcp.servers. |
Use the right client diagnostic
| Client | First diagnostic | Client-specific recovery |
|---|---|---|
| Claude Code | claude mcp list, then /mcp | Check the selected scope and start a new session after a configuration edit. |
| Claude Desktop bridge | Desktop tool list and the bridge's own diagnostic output | Check the local npx path and bridge header before treating it as a Connector issue. |
| Codex | codex mcp list, then /mcp | Verify the single TOML table and that the client process can read the named environment variable. |
| Hermes | /reload-mcp and the available prefixed tools | Reload after YAML changes; inspect tools.include and tools.exclude. |
| Cursor | Chat tools list | Restart after JSON edits and enable the server and the individual tool needed for the prompt. |
| Gemini CLI | gemini mcp list, then /mcp | Confirm the entry uses httpUrl for Streamable HTTP and approve the bounded tool request. |
| OpenClaw | openclaw mcp status --verbose, then openclaw mcp probe tokconnect | Fix the outbound mcp.servers entry; openclaw mcp serve is a different, inbound role. |
Confirm tool discovery
A connected server should expose a research tool list. Depending on the client, look for names such as keyword_research, search_topics, search_videos, video_comments, search_users, and search_hashtags. Hermes adds an mcp_tokconnect_ runtime prefix. OpenClaw's probe opens a live MCP connection and lists capabilities, which makes it more useful than a saved-definition check.
Check server-level tool filters before you change a URL. A client can connect and still exclude a tool. Hosted TokConnect does not enable save_topic; a missing save action in a hosted connection is expected.
Tool names can differ at the client surface. Hermes presents a name such as mcp_tokconnect_search_users, while the server-native name is search_users. OpenClaw filters are applied while a runtime consumes its saved registry. Cursor can require an individual tool to be enabled in the chat. In each case, capture the actual tool list before claiming the hosted server lacks a capability.
Treat empty results as research output
A successful search can return no useful matches. Use a narrower test before you conclude the client is broken:
Use keyword_research for “walking pad” with language “en” and expand 3 related topics. Return matchCount, the first three topic names and query IDs, and the errors array. Do not add a time unit to searchVolume.
The saved TokConnect research record for this input returned 20 topic matches on September 18, 2026. That example gives you a controlled comparison. A different date, key, language, or upstream response can produce a different result.
For an empty response, try the same phrase without a language filter, then a shorter seed phrase. For a video search, keep the searchId from the first page if you request an offset page. A missing pagination value can cause a search request to fail or return an unexpected page.
Pagination fields are request-family specific. Topic search returned hasMore: true and nextOffset: 3 for the tested walking-pad query. Hashtag and user search returned nextCursor: 3. Video search returned a searchId and nextOffset: 1. Keep the keyword and filters unchanged while following the associated continuation value. Start a new search when the query changes.
Observed empty-200 suppression
The editorial MCP call search_sounds("walking pad", count=3) returned the service message: “video search was suppressed by the service (an empty 200 is its block signal).” It did not return a 401 or an absent-tool error. Retry after the service clears, then record the result separately from an authentication diagnosis. The protocol fixture records the input and error.
Compare against a small known response
When a client can call tools, begin with a low-volume request that has a plain result shape. In the configured editorial MCP environment, search_suggestions for “walking pad” with count 3 returned three strings: “walking pad,” “walking pad treadmill,” and “walking pad exercise at home.” list_languages returned status 0 and language keys including en. Those observations are protocol evidence captured on September 18, 2026, not client-specific test results.
Use the value of this check correctly. Three suggestions prove neither topical demand nor future results. A language list proves only that the server could answer that request. Once either call succeeds, move to a distinct workflow such as keyword research or hashtag research instead of making discovery calls the final deliverable.
Collect details for support
Record the client name, its MCP status, endpoint hostname, tool name, sanitized error text, and request shape. Remove the bearer key and any user data before you share logs. Include whether the tool was absent, rejected before execution, or returned an empty result. Those facts let support identify the connection stage without asking you to repeat unrelated steps.
Include the client version when known, the configuration scope or file path, whether the process was restarted after the edit, and a time window. Do not include an authorization header, a full configuration file containing one, browser cookies, or any profile data that is not needed to reproduce the request. A useful report can state: server appears in /mcp, search_sounds was invoked, and the sanitized service message was returned.
Use the client-specific guides for Claude Code, Codex, OpenClaw, or Gemini CLI when the configuration itself needs correction.