Troubleshooting Aki MCP Server

Claude cannot connect while Funnel says “on”

The serve-config can save locally but fail to sync to Tailscale, so a real client is blocked at TLS while your own machine sees everything as fine.

1. 1Do not test with a bare curl https://your-host from the machine running the server: it takes the internal mesh shortcut.
2. 2Test the real public path with dig @8.8.8.8 your-host A +short then curl --resolve your-host:443:<IP> https://your-host/.well-known/oauth-authorization-server.
3. 3If it times out despite “on”, re-run tailscale funnel --bg 9999 to force a config re-push.

“Wrong token” or panel 403 on a second launch

A second launch used to race the running instance for the same ports. The server now reuses the running panel when the version matches, or stops the older one first.

• Make sure you are on a current version. If a stale panel tab is open, reload it from the freshly launched instance.

Port already in use (EADDRINUSE)

• The gatekeeper uses a fixed port 9999; a genuine conflict now names the likely cause. Free the port or stop the other process.
• The panel falls back to the next free port automatically if something else holds 9998.

A client gets 429 after wrong credentials

5 rejected credentials in 60 seconds block a caller for 15 minutes. A valid Bearer token is never blocked, so a working connection is not affected.

1. 1Wait 15 minutes, or open panel section 7 and press Release next to the blocked caller.
2. 2Check the passphrase or client secret you typed. Copy them from the panel (click the eye button to reveal).
3. 3If you keep hitting the limit legitimately, raise the numbers in section 7 (Connection limits).

A command is refused

• The message says why and names the allowed subcommands. Add the command in panel section 6 (Shell allowlist) if you trust it.
• Git write forms (branch -D, tag -d, remote set-url, --output=) are refused on purpose. Run them yourself, or allow bare git knowing it then allows everything.

A secret may have leaked

Open the control panel and roll the secret that was exposed.

• Passphrase: Roll passphrase, then Roll & sign out all clients.
• Access token: Roll & sign out all clients, then reconnect each AI with the passphrase.
• Local snippets (Cursor, Claude Code, Codex, Postman) need the new token pasted again after any token roll.

Gemini connects but does not use the tools

• This is a known limitation: the OAuth handshake succeeds but tool discovery is unreliable. Use Claude, Grok, or ChatGPT for real work today.