Skip to main content

Troubleshooting

Use this guide when a Vocci-connected AI app cannot connect, sign in, or return expected results.

Unable To Connect To MCP Server​

Symptoms​

  • The app says the MCP server cannot be reached.
  • The connection step fails before sign-in opens.
  • The app rejects the server URL.

Possible Causes​

  • The server URL is missing /mcp.
  • The app does not support remote MCP connections.
  • The app cannot open a browser sign-in flow.

Resolution​

Use the exact server URL:

https://mcp.vocci.ai/mcp

Confirm the app supports remote MCP and browser sign-in, then retry the setup guide for your app.

Sign-In Or Authorization Fails​

Symptoms​

  • The browser sign-in flow does not complete.
  • The app shows a 401 or 403 error.
  • The app was connected before, but requests now fail.

Possible Causes​

  • The Vocci authorization step was not completed.
  • The app did not return from the browser sign-in flow.
  • Your authorization expired or access was revoked.
  • The signed-in account does not have access to Vocci integrations.

Resolution​

Reconnect Vocci from the app, complete OAuth in the browser, and confirm you are using the expected Vocci account. Do not paste browser session values, OAuth codes, or authorization headers into app configuration.

Error Says resource Appears More Than Once​

The confirmed duplicate-resource cause is specific to Codex: an older Codex server entry can retain an explicit oauth_resource override and send it in addition to the resource discovered from Vocci.

Codex

For a full Codex reset, clear the saved credential before deleting the server entry, then add the entry without --oauth-resource:

codex mcp logout vocci
codex mcp remove vocci
codex mcp add vocci --url https://mcp.vocci.ai/mcp

If logout reports no saved credential, continue with remove. If mcp add opens OAuth, complete that flow and do not run mcp login again. If it returns without opening OAuth, run codex mcp login vocci --scopes "profile,offline_access,email".

Claude app (hosted connector)

Do not assume a Claude authorization failure has the Codex oauth_resource cause. For hosted Claude, disconnect and reconnect your personal Vocci grant. On Team or Enterprise, an ordinary user should not delete a shared connector. A workspace owner should delete and recreate one only after confirming that the shared connector definition itself is wrong for multiple users.

Claude Code (local entry)

Run /mcp, select Vocci, choose Clear authentication, then authenticate again. Only remove and re-add the local entry when its definition is stale. Preserve its exact configuration scope when re-adding it: omit --scope or use --scope local for a private current-project entry, use --scope project only for an entry shared through .mcp.json, or use --scope user for a user-wide entry.

If a fresh personal authorization still fails, report the app name, version, and approximate time without including credentials or the full authorization URL.

Vocci Appears Connected But Tools Are Missing​

Symptoms​

  • Vocci appears in the app, but no tools are available.
  • The app says tool scanning failed.
  • Searches fail because the app cannot find a Vocci tool.

Possible Causes​

  • The app did not refresh tools after authorization.
  • Tool scanning was skipped or failed.
  • The connection uses the wrong endpoint.

Resolution​

Refresh or restart the app, rescan tools if the app offers that action, and confirm the configured URL ends with /mcp. If tools still do not appear, disconnect Vocci and run the setup flow again.

Search Results Are Empty​

Symptoms​

  • A search succeeds but returns no useful results.
  • Results look unrelated to the question.
  • Expected content is missing.

Possible Causes​

  • The query is too broad or too vague.
  • The signed-in account does not have relevant data.
  • Source or date filters exclude expected matches.
  • The requested item no longer exists or is not supported through MCP.

Resolution​

Try a request that does not depend on a specific topic:

List my recent Vocci sessions and summarize them

If the app supports filters, remove filters first, then add one filter at a time. For Base-only searches, use note and file sources; for recording-only searches, use session, summary, and transcript sources.

A Result Does Not Open​

Symptoms​

  • Search returns a result, but opening it fails.
  • The app shows source details without content.
  • The app says content was omitted.

Possible Causes​

  • The authorized account no longer has access to the item.
  • The item is unsupported, unavailable, or too large to return through MCP.
  • The app is trying to open an old result ID from a previous search.

Resolution​

Run the search again and open one current result. If content is still omitted, use the returned title, snippet, source type, and source ID as the available context.

Rate Limits Or Timeouts​

Symptoms​

  • The app receives 429.
  • Requests repeatedly time out.
  • Broad searches take too long.

Possible Causes​

  • Too many requests were sent in a short period.
  • The query is broad enough to require more retrieval work.
  • The app is retrying automatically.

Resolution​

Wait before retrying, ask a narrower question, start with fast search when possible, and avoid repeated broad searches. If the app supports context packs, use one compact pack instead of opening many individual results.

Reporting An App Issue​

When reporting a setup issue, include the app name, app version, Vocci URL host, approximate time, status code if shown, and a short description of the error. Do not include sign-in codes, raw user content, or full redirect URLs with query strings.

Last updated on