Troubleshooting

This page is organised by what you are seeing, not by which feature is involved. Find the symptom and work down its checks in order. Most reports come down to four things: the provider never sent anything, signature validation rejected what it sent, the local listener is not running, or the editor never read its MCP configuration.

Nothing is arriving at my capture URL

The dashboard shows no captures, and you are sure you sent something. Check these in order, because each one rules out the next:

The reason this ordering matters is that a missing capture and a rejected capture look different in the dashboard but identical from the provider’s side, and only the provider’s log tells you whether anything left at all.

I am getting a 401 and I did not expect one

A 401 means signature validation ran and the signature did not verify. That is the feature working; the question is why it disagreed with your provider.

• The secret does not match. Copy it again from the provider. A trailing space or newline from a copy and paste is the most common cause and the hardest to see.
• The secret was rotated. Providers rotate on schedule and on request, and some allow two live secrets during a rollover. Update the secret here to whichever one is signing now.
• The wrong scheme is selected. A provider signing with one scheme cannot be verified with another. Check the scheme on the endpoint against what the provider documents it sends. The four schemes are on the signature validation page.
• The provider sends more than one signature header. Some send both a current and a legacy header during a migration. Verify against the one the provider currently documents.

If all four check out and the 401 continues, open the rejected capture. It keeps the headers and body that arrived, so you can read the signature headers the provider actually sent instead of guessing. That turns a guess into an observation.

The capture is here, but replay never reaches my app

The capture exists and looks right, and your server sees nothing.

• Check the listener is running. flurryport listen has to be running for a replay to reach localhost. If the terminal running it is closed, replays have nowhere to go: they sit pending for one minute and are then dead-lettered.
• Check the target URL and port. The target is the full URL on your machine, path included. A target pointing at / when your handler is at /webhooks/stripe delivers to your app and gets a 404 from your own router, which reads as "nothing arrived" from the outside.
• Read the replay result rather than the app. The execution records what your server answered. A 404, a 500 and a connection refused are three different problems, and the record tells you which one you have.
• Auto-forward is not the same as replay. If you expected every new capture to arrive on its own, check that auto-forward is switched on for that target. Targets created from the CLI start with it off. See auto-forward and targets.

Replay arrives, but my signature check fails locally

This one confuses people because the capture is fine and the delivery is fine. The signature is computed over the raw request body, so anything that re-serialises the body between arrival and your verification breaks the check.

• Verify against the raw bytes, before any JSON parsing and re-encoding.
• Some frameworks parse the body by default and hand you an object. Ask for the raw body explicitly on the route that verifies.
• Header names are case insensitive in HTTP, and some libraries are not. Look them up case insensitively.

If you apply a transformation, the payload your target receives is deliberately not the payload the provider signed, so a signature check against a transformed body will always fail. Verify before transforming, or do not verify on that target.

The MCP server does not appear in my editor

• Restart the editor. Most clients read MCP configuration only at startup, so an edit made while the editor is open does nothing until it is restarted.
• Check the file and the key. VS Code uses .vscode/mcp.json with a top-level servers key and needs "type": "stdio". Claude Desktop, Cursor and Windsurf use the same mcpServers block at three different paths. The full matrix is on the CLI and MCP server setup page.
• Check that npx runs. Run npx -y flurryport mcp in a terminal. If it fails there, it will fail in the editor, and the error is easier to read in the terminal.
• Check your Node version. The CLI is built and tested on Node 22. node --version tells you what npx will use.
• ChatGPT will not work on this path regardless of configuration. A local stdio server cannot be connected there.

A tool answers account_required

Twenty tools work before a session is claimed and forty need an account. This is by design rather than a fault: the anonymous path exists so you can try the thing without signing up, and it does not include operations that write to a project we would have to keep. The tool list itself never changes; the same tools start succeeding once you claim.

To claim, ask your agent for the claim link (it is the register page with your session token attached), open it, and sign up or sign in. Your captures move into a new project, re-encrypted, and the server flips to authenticated on its next poll with nothing to paste. If you already have an account, run flurryport login --use and restart the MCP server, because token scope is read at startup.

My captures disappeared

Retention is per plan, and captures age out on a rolling window; see plans and limits for the window on yours. Anonymous sessions are shorter: 90 minutes after the last use, and 24 hours at most. If you need a capture kept, claim the session and add it to a collection, which exempts it from retention.

A room says seat_required

This one belongs to rooms rather than to capture and replay, and it means no seat has been redeemed in the session making the call.

• If your agent holds a standing credential for the room, it re-attaches rather than redeeming anything.
• Otherwise the room’s host mints a fresh pairing code and the agent redeems it. Pairing codes are single use and expire, so a code that has already been redeemed will not work twice.

Still stuck

Open an issue on GitHub with the endpoint, the time of the delivery and what the provider’s own log says. Those three things resolve most reports in one round trip, and the third is the one people leave out.