Troubleshooting
The handful of things that trip people up on the way in, and the quickest fix for each.
The connector will not connect
Added, but stuck on “Needs authentication”
claude mcp addregisters PAPI and stops there. The server sits at “Needs authentication” until you finish the handshake. Run /mcp, choose papi, pick Authenticate, and sign in in the browser tab that opens.
Nothing connects, no matter what
Open getpapi.ai/settings, find your project, and click Reset connection for a fresh snippet. Your cycles, tasks, and history stay exactly where they are. Replace the papi entry in your .mcp.json with the new snippet and restart your MCP client.
A token-based tool will not connect (Zed, z.ai)
A few tools do not support OAuth. Open getpapi.ai/settings, copy the token snippet from the Advanced panel, and paste it in place of the URL-only config. That is the one case where a connection token is needed.
Two PAPIs installed, or a stale entry
If you added PAPI more than once — say the remote connector and a local/NPX server — your tool ends up with two papientries and connects to the wrong one, or an old entry lingers after you thought you removed it. PAPI cannot clear these for you: they live in your tool’s own config, not in the database. Here is the clean way out.
1. See everything that is registered
Any row named papi is a PAPI registration. If you see more than one, that is the duplicate to clear.
2. Remove the stale or duplicate entry
Run it once per duplicate. Keep one connection only — the supported path is the remote connector at https://mcp.getpapi.ai/mcp. Removing a connector never touches your project: cycles, tasks, and history stay in the database.
3. If an entry survives removal, clear it by hand
A stray registration lives in a config file. For Claude Code that is ~/.claude.json; other tools keep their own MCP config. Open it, delete the leftover papi block, save, and restart your tool. Then confirm with claude mcp list that only the one you want remains.
4. Re-add cleanly
Open getpapi.ai/settings, copy the current connect snippet, add it once, then run /mcp → choose papi → Authenticate. One entry, one sign-in.
PAPI says there is no project
Your connector authenticated, but it is not pointed at a project yet. Two ways to fix it:
Run setup once from the repo you want PAPI to track. It creates the project and binds this connection to it. If you already set one up, confirm you are signed in with the account that owns it, and that you opened your tool in the right project folder. PAPI binds to the folder the connector was added from.
Sign-in and sessions
I signed in but the dashboard is empty
The dashboard at getpapi.ai shows the projects owned by the account you signed in with. An empty dashboard usually means you are signed in with a different account than the one your connector uses. Sign out, sign back in with the matching account, and your cycles appear.
Still stuck?
Drop into the community and we will help you get connected. Bring the exact command you ran and what your tool showed, and someone will point you at the fix.