Skip to content

Troubleshooting

Apoorv Raj Saxena edited this page Jan 6, 2026 · 1 revision

Troubleshooting

No messages appear in the UI

  1. Confirm your server is wrapped:
    • config uses command: "mcp-reticle" and args: ["run", ...]
  2. Confirm the UI is running:
    mcp-reticle ui
  3. Check terminal output for errors (server crash, missing binary, permission issues).
  4. Validate interception with log-only mode:
    mcp-reticle run --log -- <server command...>
  5. If using proxy mode, confirm upstream + listen settings:
    mcp-reticle proxy --help

Proxy won’t start

  • Port already in use: choose a different --listen port
  • Upstream unreachable: verify the upstream is running and URL is correct
  • Permissions: ensure the process can bind to the chosen port and read/write needed files

Server crashes / stderr output

  • Reticle captures stderr; inspect it in the UI.
  • Run the server directly (without Reticle) to compare behavior.
  • Ensure the same env vars and working directory as the client normally provides.

High token usage / context bloat

  • Use token profiling to identify heavy methods/tools.
  • Reduce tool schemas or response sizes where possible.
  • Split toolsets across servers so you can isolate heavy ones.

Reporting issues

Include:

  • OS + architecture
  • MCP client (Claude Desktop / Cursor / Cline / other)
  • Transport (stdio / http+sse / streamable http / websocket)
  • Server command (redact secrets)
  • Minimal reproduction steps
  • An export file (see Exports)

Clone this wiki locally