> For the complete documentation index, see [llms.txt](https://docs.scribeware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scribeware.com/into-the-weeds/ai-assistant-mcp/troubleshooting-the-ai-assistant.md). # Troubleshooting the AI Assistant The AI can't see ScribeWare, the tools vanished mid-conversation, or it's editing the wrong report — what each one usually means. ## My AI Doesn't See ScribeWare at All Work through these in order — it's nearly always one of the first three. 1. **Is ScribeWare running and logged in?** The connection lives inside the desktop app. Closed app, no tools. Logged out, no tools. 2. **Is the switch on?** **Settings → AI**, and check the chip says **Running on port ...**. If it says **Stopped — log in to start**, that's your answer. 3. **Did you restart your AI tool?** Claude Desktop in particular only reads its config file at startup, and needs a full quit — not just closing the window. 4. **Is the config in the right file?** Easy to paste into the wrong one. The panel in **Settings → AI** names the exact path for your operating system above each snippet. 5. **Is the JSON valid?** If you merged the snippet into a file that already had other MCP servers in it, a missing comma or brace will stop the whole file loading. Paste the file into your AI and ask it to check. ## The Port Number Doesn't Match ScribeWare normally listens on **8765**. If another program on your machine already has that port, ScribeWare takes the next free one instead — 8766, 8767 and so on. Tools configured with an `http://127.0.0.1:8765/mcp` URL (Claude Code, Gemini CLI, most others) have that number baked into their config, so they'll be pointing at nothing. Copy the snippet from **Settings → AI** again — it always shows the port actually in use — and paste it over the old one. Claude Desktop doesn't have this problem; its bridge script finds the right port on its own. ## It Says It's Not Logged In The AI is talking to ScribeWare fine, but ScribeWare has nobody signed in. Log in to the desktop app and try again — you don't need to restart your AI tool. ## The Tools Worked, Then Stopped Usually a stale connection: this happens if ScribeWare restarted, or you switched company or user account, part-way through a conversation. Go to **Settings → AI** and click **Reset session**. Then ask your AI to try again — most tools reconnect on their own without a restart. If yours doesn't, restart it. ## It's Editing the Wrong Report or Chapter The AI works on whatever you've got open in ScribeWare. If it's editing the wrong thing, the app is almost certainly showing something different from what you're picturing. Open the report and chapter you actually mean, then ask again. To be sure, you can just ask: *"which report and chapter can you see right now?"* ## It Asks Me for a Report ID It shouldn't — IDs are filled in automatically. When this happens it's usually the AI being over-cautious rather than anything being broken. Tell it plainly: > Don't ask me for IDs. Use the report I have open. If it happens constantly, add that line to your **Standing Instructions** in **Settings → AI**. ## It Made a Mess Open the **Changes** bar from the right-hand toolbar and hit **Revert All**. Everything the AI touched goes back, item by item. If the changes were made with **auto-approve** ticked on that report, there's nothing to revert to — that's the trade-off described in [Reviewing AI Changes](/into-the-weeds/ai-assistant-mcp/reviewing-ai-changes.md). Untick it if you'd rather have the undo. ## It Keeps Making the Same Mistake Correcting it in chat only lasts as long as the conversation. To make it stick, put the rule in **Extended Guidance** under **Settings → AI**, or tell the AI to save it there: > Add that to the company guidance so you remember it next time. See [Teaching It Your Style](/into-the-weeds/ai-assistant-mcp/teaching-it-your-style.md). ## Something's Genuinely Broken When a tool gives a wrong result or a confusing error, say so in the chat — *"that edited the wrong section"*. The AI files a report back to us, and those reports are read: they're the main way this integration gets fixed. For anything that stops you working, contact ScribeWare support as normal. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.scribeware.com/into-the-weeds/ai-assistant-mcp/troubleshooting-the-ai-assistant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.