CLI error: "authentication failed"

The CLI printed this and stopped:

  ✗ authentication failed
    invalid or missing API key
    ◆ check the `--api-key` flag or `MCPPIPE_API_KEY` env var.
    ◆ you can also pin the key in a `mcppipe.toml` file.

The second line is the reason the service sent back, so it varies. The headline does not.

Why the CLI exits instead of retrying

Every other connection failure makes the CLI reconnect with backoff. This one does not, deliberately: an invalid key never becomes valid. Retrying it would turn a typo into an infinite loop of rejected handshakes, and would hide the real problem behind a wall of reconnect logs.

So a tunnel that dies immediately with this message is telling you the key is wrong — not that the network is flaky.

Causes, in the order worth checking

The key is missing or truncated. An mcppipe CLI key always starts with mtk_. If what you are passing does not, you are probably passing something else — a tunnel ID, an OAuth token, or a shell variable that expanded to nothing. Check with echo $MCPPIPE_API_KEY (or echo $env:MCPPIPE_API_KEY in PowerShell) before blaming the service.

The key was rotated. Rotating a key in the dashboard invalidates the old one immediately — there is no grace period and no overlap. If the tunnel was working until someone pressed rotate, that is your answer. Copy the current key from the tunnel’s Settings tab.

The key belongs to a different tunnel. Keys are per tunnel, not per account. A key from tunnel A does not authorise a connection for tunnel B.

The flag is in the wrong position. --api-key is parsed after the subcommand: mcppipe up --api-key mtk_…, not mcppipe --api-key mtk_… up.

Where to put the key

Three places, in precedence order:

--api-key mtk_… on the command line.
MCPPIPE_API_KEY in the environment — the right choice for CI and containers, where a key on the command line ends up in shell history and process listings.
A mcppipe.toml file next to the project.

See the CLI reference for the full flag list.

Not this error?

If the CLI authenticated but then refused the session, you are looking at session_limit instead — that one means the key was accepted.