TROUBLESHOOTING

Everything here has happened; nothing is invented to pad the list out. The common thread is worth saying up front: almost none of these produce an error message. A wrong key name, a chat in the wrong mode, a missing standing instruction, all of them look identical from the chat window, and they all look like “this product does not work”. If you hit something not listed, tell us and it gets added.

Start here: read the board, not the chat window

Driving five clients through this setup by hand, three of them misdescribed their own state. One said it was not connected while it was connected. One blamed the IDE for blocking tool calls that nothing had blocked. One reported writing to the board when it had not.

An agent describing its own configuration is guessing from the same documentation you have. Open app.astryke.com and look at the Agents page: it lists what actually reached the server, by client name, with the time each was last heard from. Trust that over any account of itself an agent gives you.

The server never appears in my editor’s MCP list

Nine times out of ten this is a key name, and no client warns you about it. VS Code wants servers where everyone else wants mcpServers. Devin Desktop wants serverUrl where everyone else wants url, and ignores url in complete silence. Copying a working block from one editor into another is the usual way in.

Every config format, side by side.

My agent invented a config file that nothing reads

Specifically ~/.copilot/mcp_servers.json, which does not exist and is read by nothing. Agents asked to “set up this MCP server” produce it confidently and then report success. If a file by that name turned up on your machine, delete it and use the command palette route on the VS Code page instead.

My agent is trying to sign in at the server address

https://app.astryke.com/mcp is an API endpoint, not a sign-in page. Opening it in a browser is not part of setup. If your agent is asking you to authorize something by hand, the config step did not take: register the server properly and let the client run the OAuth flow itself.

It connected, but the agent never uses it

The most common outcome of a successful setup, and the one that reads as “this does nothing”. MCP is pull-only. Connecting gives your agent the ability to read your board and no reason to, so it carries on asking what you were working on while a perfectly good board sits there.

Put a standing instruction in the file your client reads at the start of a session. The text and the file path for each client are on that client’s setup page, linked in the sidebar.

A tool name got mangled and now nothing works

Windows only, and vicious because it is invisible. If your agent wrote the standing instruction through PowerShell, a backtick before a letter is an escape character. A quoted get_brief can arrive on disk as get_brie. The instruction reads fine to a human, the tool call fails forever, and nothing reports an error. Open the file and check the spelling by eye.

VS Code says it is not connected, but it is

Two causes, neither reports an error. Copilot only offers MCP tools in Agent mode, so in Ask or Edit they are silently absent and Copilot will tell you plainly it has no Astryke connection. And a chat opened before the server connected keeps the tool list it started with for its whole life. Switch to Agent mode and start a new chat.

Cursor CLI: authenticated, but the tools will not run

Cursor’s CLI keeps a per-directory approval list separate from the browser sign-in, and calls both of them approval. After signing in, run this in the folder you are working in:

agent mcp enable astryke-hub
agent mcp list-tools astryke-hub

The approval does not follow you to another folder. Print mode (-p) also refuses tool calls, and we have not found a flag that changes it.

Authentication keeps re-opening the browser

The connection is scoped per machine. Set up with a project-level scope instead of a user-level one, every new directory looks like a new client. For Claude Code, use --scope user:

claude mcp add --transport http --scope user astryke-hub https://app.astryke.com/mcp

The board is empty after connecting

Usually correct rather than broken. A new workspace has no projects because nothing has told it about any, and Astryke deliberately does not invent a placeholder one. Tell your agent what you are working on, or ask it to read the projects already on your machine and offer to fill them in. There is a sample board linked from your empty board if you want to see the filled-in version first.

The agent connected but nothing gets written back

Check whether your trial has ended. When it does the board goes read-only: reads keep working, writes stop. From the agent’s side that is indistinguishable from a broken connection. The billing page in the app says which state you are in.

The other possibility is a read-only connection. Reconnect granting hub.write if your agent reports that it cannot record progress.

A project is on my board twice

Fixed on 4 August 2026. Until then, an agent that got the name slightly wrong, My Project against My-Project, started a second project rather than matching the first. Names are now matched with punctuation, spacing and case ignored, and the agent is told the real name so it stops missing.

Any duplicates created before that date are still there. Rename or archive the spare from the project page; nothing merges them for you.

My next step disappeared

Also fixed on 4 August 2026, and worth explaining because it looked like data loss and was. An agent sending an empty next step used to overwrite the one already on the board. A blank field now means “nothing to add” rather than “delete it”. There is no undo for anything lost before that date.

It works in one editor and not another

Claude Code, Codex and VS Code with Copilot are tested end to end, which here means one person drove the whole loop by hand and watched a write land on a real board. Cursor and Devin Desktop connect and list every tool, but no write-back has been confirmed on either. A failure on those two is genuinely more likely to be us than you. Report it and it gets looked at.

Still stuck? Contact — include which editor, the config you used, what you expected, and any error copied exactly. Never send passwords or tokens.