mcplexer

Troubleshooting

Common issues and how to resolve them.

"No matching route"

The routing engine couldn't find a rule matching the tool call in the resolved workspace.

Check the workspace CWD. MCPlexer resolves the workspace by matching the client's working directory against workspace root_path values. If the wrong workspace is selected, the expected routes won't be available.

terminal
mcplexer status # Verify which workspaces exist and their root paths

Check route priority. Routes are evaluated in priority order (highest first). A deny rule with higher priority may be blocking your tool call before a lower-priority allow rule is reached.

Use dry-run. Simulate the exact tool call to see the routing decision:

terminal
mcplexer dry-run <workspace-id> github__list_repos # Or via the API: curl -X POST http://localhost:8080/api/v1/dry-run \ -H "Content-Type: application/json" \ -d '{"workspace_id": "...", "tool_name": "github__list_repos"}'

The dry-run output shows which rules were evaluated and why each did or didn't match.

Check the workspace default policy. If no route matches and the workspace has default_policy: "deny", the call is blocked. Set it to "allow" for development or add an explicit allow rule.

"Connection refused"

The client can't connect to the MCPlexer daemon or HTTP server.

Check if the daemon is running:

terminal
mcplexer daemon status

If stopped, start it:

terminal
mcplexer daemon start

Check the socket path. The daemon communicates over a Unix socket at /tmp/mcplexer.sock. Verify it exists and has the correct permissions:

terminal
ls -la /tmp/mcplexer.sock

If the socket file is stale (left over from a crashed process), remove it and restart:

terminal
rm /tmp/mcplexer.sock mcplexer daemon start

Check the port. If using HTTP mode, verify the port isn't already in use:

terminal
lsof -i :8080

"OAuth token expired"

OAuth tokens have a limited lifetime. When a token expires, tool calls using that auth scope will fail.

Check token status:

terminal
curl http://localhost:8080/api/v1/auth-scopes/<id>/oauth/status

Automatic refresh. MCPlexer automatically refreshes tokens using the refresh token if one was provided during authorization. If refresh fails, you need to re-authorize manually.

Re-authorize:

terminal
# Via the web UI: navigate to Credentials > your auth scope > Re-authorize # Via the API: curl http://localhost:8080/api/v1/auth-scopes/<id>/oauth/authorize

This opens the OAuth flow again. Once complete, the new token is stored and tool calls resume.

Token monitoring

The Dashboard shows OAuth token status for each auth scope. Expired tokens are highlighted so you can spot them quickly.

"Tool not found"

The requested tool doesn't exist in MCPlexer's tool registry.

Check the namespace prefix. All tools are namespaced as {namespace}__{toolname}. Make sure the client is using the full namespaced name:

terminal
# Correct: github__list_repos # Wrong: list_repos

Run tool discovery. If the downstream server was recently added or updated, its tools may not be registered yet:

terminal
curl -X POST http://localhost:8080/api/v1/downstreams/<id>/discover

Check if the server is disabled. Disabled downstream servers don't expose their tools. Verify the server is enabled in the web UI under Config > Downstream Servers or via the API.

Check the downstream server is reachable. If the downstream process crashes during discovery, no tools are registered. Check logs for startup errors.

Debug Logging

Enable verbose logging to see the full request lifecycle — workspace resolution, route matching, auth injection, and downstream dispatch.

terminal
MCPLEXER_LOG_LEVEL=debug mcplexer serve --mode=http

For the daemon:

terminal
mcplexer daemon stop MCPLEXER_LOG_LEVEL=debug mcplexer daemon start mcplexer daemon logs -f

Debug output includes:

  • Workspace resolution details (CWD matching, selected workspace)
  • Route evaluation steps (which rules matched/skipped and why)
  • Auth scope injection (which env vars were set)
  • Downstream process lifecycle (start, stop, crash, restart)
  • Cache hit/miss decisions

Common CLI Issues

Config file not found. MCPlexer looks for ~/.mcplexer/mcplexer.yaml by default. Override with MCPLEXER_CONFIG:

terminal
MCPLEXER_CONFIG=/path/to/config.yaml mcplexer serve

Database locked. Only one MCPlexer process can write to the SQLite database at a time. If you see "database is locked" errors, check for other running instances:

terminal
mcplexer daemon status ps aux | grep mcplexer

Permission denied. Ensure the MCPlexer binary has execute permissions and the ~/.mcplexer/ directory is writable by the current user.

Deployment