MCP MCP server
Troubleshooting
The usual reasons the MCP server won't start, can't sign in, or is missing a tool, and how to fix each one.
For developers and power users
Find your symptom in the table below.
| Symptom | What to do |
|---|---|
Not signed in, or the server exits at start | Set BOTCIRCUITS_ACCESS_KEY. |
BOTCIRCUITS_ACCESS_KEY was refused | The key is wrong, revoked or expired. Create a new one in Settings › Access keys and restart the assistant. |
This access key doesn't give access to this resource (403) | The key's access doesn't cover that area. Edit the key, or make one with more access. |
| Account tools fail (such as changing your profile or password) | Keys can't change sign-in details by design. Do it in the web app. |
Can't reach http://… | Check Space is running, and that BOTCIRCUITS_API_URL is right. |
outside the workspace | BOTCIRCUITS_WORKSPACE is set, and the file isn't inside it. Move the file, or change the setting. |
| A tool seems to be missing | The server's tool list may be older than Space. Ask the maintainers to refresh it. Or it's one of the actions that are not tools on purpose. |
| The tools don't appear at all | Use the full path to the command in the config, restart the assistant, and check its MCP log. |
| A request times out | Raise BOTCIRCUITS_TIMEOUT. For chat, raise BOTCIRCUITS_CHAT_TIMEOUT. The copilot keeps working on the server even if your assistant stopped waiting. |
| A long result is cut off | Raise BOTCIRCUITS_MAX_OUTPUT_CHARS, or ask for a narrower result. |
Testing the command by hand
Run botcircuits-space-mcp in a terminal. It should just sit waiting for input. That's correct. The assistant talks to it through that same channel. Press Ctrl+C to stop it.
Checking your key
Ask your assistant: “Who am I signed in as in the Copilot?” A good answer proves the key, the address and the connection all work.
Still stuck?
- Check Settings › Access keys to confirm the key is active, and look at its last used time and address.
- Ask an administrator to check the access log for your key's activity. See Logs and audit.
- Re-read Set it up, step by step.