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 you typed (for Gemini, also the client secret). Copy the passphrase 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 tool is refused: missing or stale rule receipt

Every tool that can act needs the current rule receipt that aki__akidevrule_context returns. The refusal code says which case it is: RULE_RECEIPT_MISSING (none sent), INVALID (not sha256: plus 64 hex characters), UNKNOWN (not issued since this server started), STALE (a rule file changed since) or UNCHECKED (the rules could not be read).

1. 1The refusal carries its own fix: call aki__akidevrule_context (without knownReceipt if the rules are no longer in your context), then call this tool again with receipt=<the sha256:… it returns>. Ask the AI to do exactly that.
2. 2After restarting akimcp or editing a rule file, older receipts turn UNKNOWN or STALE: fetch a fresh one.
3. 3A tool that acts on a project with a CLAUDE.md, AGENTS.md or GEMINI.md may first return that project’s rules and a new receipt instead of running. That is not an error: call it again with the new receipt.
4. 4If the tool has no receipt argument at all, the chat holds an old schema: reconnect akimcp or start a new chat.

A call fails with -32602 (invalid arguments)

A chat keeps the tool schema it loaded. After an update it can send an argument the new schema no longer takes, and the protocol answers -32602. The error now says which case it is.

1. 1If it reads <tool> takes no <argument>; its arguments are …, the argument name is not one this version takes: use a name from the list it prints.
2. 2If it ends with tool schema is stale; reconnect AkiMCP or start a new chat, every argument is valid for the running server but not for the schema your chat cached. Reconnect akimcp in the client, or start a new chat, then retry.
3. 3Updating from 2.2 to 3.0.x: reconnect akimcp in every client once, because tool definitions changed in 3.0.0 and Claude asks “Always allow” again for the tools that changed. Updating 3.0.0 to 3.0.1 only needs a restart: the tool definitions are the same.

chrome_launch fails with no_profile

Browser profiles live in ~/.aki/cdp/profiles/<browser>-<profile>/ and only the optional AIObox app creates them. chrome_launch opens or attaches to one and never creates or copies it. The error reads Profile "chrome-profile-14" not found in … AkiMCP opens existing shared profiles and does not create them. (no_profile; next: …).

1. 1Use an id the error lists after open one of, or pass the folder name such as Profile 14. chrome_profiles lists the shared ids too.
2. 2No shared profile yet? Attach instead: find the port of a Chrome running with a remote-debugging port using aki__port_status, run aki__devtools_targets on it, match the tab by title or url, then pass that port and targetId explicitly.
3. 3The old ~/.aki/mcpsv/chrome-clones folder is no longer read and can be deleted, and the refresh argument is gone.

A browser call ends with “code timeout” after 50 seconds

A client gives up on a tool call after about a minute and then shows nothing, so every CDP call (devtools_eval, devtools_screenshot, devtools_targets, tab requests, postman_eval) ends within 50 seconds, finding the target and connecting included. A frozen or hidden tab, a script that never returns, or an endpoint that does not answer reaches that bound.

1. 1the page did not answer within 50s (the tab is frozen, or the script is still running): the script may have run. Check with a short read-only expression before running it again. Still no answer means the tab is frozen, so reload or close it yourself.
2. 2the page gave no screenshot within 50s (the tab is frozen or hidden): try once more. Still none means the tab is frozen or hidden: show or reload it.
3. 3the CDP endpoint host:port did not answer within 50s: check the app is running with aki__port_status, then try once more. Since 3.0.1 this message also covers a call that timed out while still listing tabs or connecting: nothing ran, so there is no need to check for side effects. 3.0.0 could say “the script may have run” in that case.

A background task or Postman will not start

aki__task_start and the Launch Postman button in the panel fail with the system error code of the failed start, and the server keeps running. Before 3.0.1 a task that failed to start ended the whole server, and a failed Postman launch ended the Postman helper, so update if you see that.

1. 1Failed to spawn background task process: ENOENT: the working folder or the program does not exist. Check the cwd you passed and that the program is installed and on the server’s PATH.
2. 2Failed to spawn background task process: EACCES: the program exists but is not executable. Fix its permissions or point to the right binary.
3. 3Failed to launch Postman: ENOENT or EACCES: install Postman, or fix the permissions of its binary, then press Launch Postman again.
4. 4A command refused before any start was tried is a different case: see “A command is refused” on this page.

A tool is missing, or a call says the tool is disabled

Tools of an app that is not installed are not served, and optional providers can be switched off. agy and Kiro CLI start off, because each hands a whole task to another paid agent. Rule context, files, search and shell are always on.

1. 1Open panel section 8 (Tool providers). A provider whose app is missing shows why: agy is not on PATH, kiro-cli is not on PATH, Postman app not found, no Chromium browser installed (Chrome, Brave, Edge), or no ~/.aki/aiobox/ folder for the optional AIObox tools.
2. 2Install the app, then press Detect again. No restart is needed.
3. 3For agy and Kiro CLI, also switch the provider on in the same section.
4. 4A switch applies on the server at once, but a client sees it only on its next tool list: start a new chat or reconnect the connector. Until then a call to a hidden tool fails with an error that says the tool is disabled.

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.