Skip to content
Valency Valency Valency Documentation

Troubleshooting

Before reporting an issue, run through the quick checks and common fixes below.

Quick checks

Section titled “Quick checks”
  1. Server status: Check labs.valency.io/health. If it's down, the server is the problem.
  2. Account: Verify you've signed up at app.valency.io.
  3. Connector URL: Confirm the server URL is https://labs.valency.io/mcp/.

Common issues

Section titled “Common issues”

"Couldn't reach the MCP server" in Claude

Section titled “"Couldn't reach the MCP server" in Claude”

Usually the MCP server URL is wrong. Confirm the connector points at https://labs.valency.io/mcp/ — see the Claude setup guide for the full walkthrough. If the URL is correct but Valency used to work and just stopped, see Did Valency stop working recently? below.

Did Valency stop working recently?

Section titled “Did Valency stop working recently?”

If Valency used to work and recently started failing, your connector was set up before a sign-in change and needs to be removed and re-added. This affects Claude, ChatGPT, Codex, and Gemini alike.

Fix: See Reconnecting to Valency for the two-minute, per-platform steps.

Sign-in fails with "redirect_uri is not registered"

Section titled “Sign-in fails with "redirect_uri is not registered"”

Affects Claude Code and Codex CLI. To receive the sign-in redirect, both start a small web server on your own machine and ask Valency to redirect back to it. Unless you pin the port, they pick a different random one on every attempt, and Valency only accepts redirects to a fixed list of local ports — so sign-in is rejected before the login page ever loads.

Fix: pin the port.

The port can only be set when the server is added, so remove and re-add:

claude mcp remove valency-mcp
claude mcp add --transport http --scope user --callback-port 33418 \
  valency-mcp https://labs.valency.io/mcp/

Added it under a different name? Run claude mcp list first and remove whichever name is actually there.

Then start claude, run /mcp, and select the Valency server. Because the failed attempt never issued any credentials, the menu offers Authenticate — there's nothing cached to clear first.

If the port you pinned turns out to be in use, see The callback port is already in use below. If you pinned the port and sign-in still fails with the same error, let us know and include the full message.

The callback port is already in use

Section titled “The callback port is already in use”

Affects Claude Code and Codex CLI. Something else on your machine is holding the port you pinned. Neither client falls back to another port — each reports the problem and stops, so sign-in never reaches Valency.

Quit whatever is holding the port and try again, or switch to one of the other ports Valency accepts: 33419, 33420 or 3118.

OAuth callback port 33418 is already in use — another process may be holding it.

The message also includes a command for finding the process that's holding the port, so you can quit it and retry.

To use a different port instead, remove and re-add the server:

claude mcp remove valency-mcp
claude mcp add --transport http --scope user --callback-port 33419 \
  valency-mcp https://labs.valency.io/mcp/

Added it under a different name? Run claude mcp list first and remove whichever name is actually there. Then start claude, run /mcp, and authenticate.

If those are taken too, tell us and we'll add a port that's free on your machine.

Sign-in doesn't work

Section titled “Sign-in doesn't work”

No tools appear

Section titled “No tools appear”
  • Refresh the page or restart the app
  • Check that the MCP server URL is correct: https://labs.valency.io/mcp/

No results returned

Section titled “No results returned”

Nothing works at all

Section titled “Nothing works at all”

Start with the server health check at labs.valency.io/health. If that's down, the server is the problem — report it immediately.

Still stuck?

Section titled “Still stuck?”

See Reporting Issues for how to get help.

Terms of Service