MCP troubleshooting

Find the symptom that matches what you see. The wording your assistant shows can differ from the messages below, because each client displays errors in its own way. For what each tool does, see the Tools reference.

Check what is connected

Start here for most problems.

Look in your assistant's list of connected servers for gurusup-brain. In Claude Code and Codex, run /mcp. In Cursor, open Tools & MCP. In ChatGPT, open Settings, then MCP servers. In Claude, open Settings, then Connectors.
Ask the assistant which tools it has from gurusup-brain. A full connection has 13: init, health, get_profile, start_company_memory_activity, ask_company_memory, search_company_memory, retrieve_company_memory, add_company_knowledge, report_issue, send_feedback, skills_get, skills_publish and request_human_info.
Ask it to run the health tool. It checks whether the Brain API is reachable.

If the server is missing, paste the prompt again or follow the steps for your client in Setup.

Recovery by client

Client	If the server is missing, not connected or asks you to sign in
Claude	Open Settings, then Connectors, and check that GuruSup Brain is listed and turned on for the conversation. If not, add it again. See Claude.
Claude Code	Run `/mcp` and follow the browser steps to sign in. Check the scope: a server added with the default scope is available only in the project you added it in. See Claude Code.
Codex	Run `/mcp`. If it is listed but not signed in, run `codex mcp login gurusup-brain`. See Codex.
Cursor	Look in Tools & MCP and check the toggle is on. Check that `mcp.json` is valid JSON. See Cursor.
ChatGPT	Check that you are in the desktop app, open Settings, then MCP servers, and select Authenticate if it is shown. Restart ChatGPT after changes. See ChatGPT.
VS Code	Follow the steps on the Brain MCP page. Click Start above the server entry in `.vscode/mcp.json` if it does not connect on its own.

Brain says it is still building your memory

You see this message from Brain:

Brain is still building your memory. You can search it once the build finishes.

When your assistant calls init before the memory is built, it is told this instead: "Company Memory is collecting its initial knowledge and is not ready to answer company questions yet." Your assistant may tell you Brain is not ready.

Brain only answers once your organization's memory has been built. Until then, questions, searches and lookups stop with this message. Only an admin can build the memory. Members cannot. An admin confirms it with Continue at the end of the sources step in setup, or with Build my memory on the home page of GuruSup Brain (called Get started until the memory is built, then Overview). The button turns on once a source is connected, a document is ready or something is being prepared. Home then shows "Preparing your documents." until your content is ready, and Brain starts the build by itself. The build runs in the background, and answers may be incomplete until it finishes.

Wait for the build to finish and ask again. If you are an admin and have not started it, that is the next step. See the Quickstart and How Brain works.

Your client first tries to connect, is told it is not signed in (an HTTP 401), and opens a sign-in page in your browser. After you sign in, it connects on its own. The sign-in page may open in a browser window or tab. If nothing opens, use your client's sign-in step from the table above.

If sign-in seems to work but every tool then fails with an error about your sign-in or account details, contact support. This comes from how your account reaches Brain, and you cannot change it from your assistant.

The assistant works with the wrong organization or account

Sign-in ties a connection to one person in one organization, and you choose the organization when you sign in. If you belong to several, the connection uses the one you chose. To check, ask the assistant to call get_profile. It returns your email and an opaque profile ID. To switch, connect again and choose the other organization at sign-in. In Claude Code you can run claude mcp remove gurusup-brain first. In Claude, remove the connector under Connectors. In Cursor, delete the entry from mcp.json or turn it off. Then add it again with the steps for your client.

ChatGPT uses get_profile to label connected accounts. See ChatGPT.

Connected, but the assistant does not use Brain

Connecting the server gives the assistant the tools. It does not tell it when to use them. That comes from an instruction saved in the assistant's long-term instructions:

For anything about this company, use the GuruSup Brain tools before answering. Call init first, then ask_company_memory. Answer only from what those tools return, and if they find nothing, say so instead of guessing.

The Copy prompt on the Brain MCP page asks the assistant to save this for you. If you connected by hand, or the assistant did not save it, add it yourself. The instruction is per client and, in most clients, per project:

Client	Where it lives
Claude	Project instructions. It applies only inside that project.
Claude Code	`CLAUDE.md` in the project
Codex	`AGENTS.md` in the project
Cursor	`.cursor/rules/gurusup-brain.mdc`, with `alwaysApply: true`
ChatGPT	Personalization, then Custom instructions

In the meantime, you can tell the assistant to check GuruSup Brain and ask again. See Ask questions.

Brain finds nothing

When Brain has nothing that supports an answer, the assistant is told to say it found nothing instead of guessing. Not seeing a fact in the excerpts does not prove Brain does not have it, so try these before giving up:

Use the names people actually use for the customer, project or product.
Make the question narrower, or wider if it was very specific.
Ask an admin to check that the source holding the answer is connected and has finished learning. Brain can only answer from what it has read.

Brain also leaves out anything you are not allowed to see, so a fact that exists may not come back for you. If some parts of a question are answered and others are not, the assistant is told to say which is which. See What an agent can see.

Slow answers

A slow answer can take minutes. Brain waits for its own backend a long time before it gives up, so a tool that looks stuck is often still working. Wait, and if the answer never comes, ask again with a narrower question. If it keeps failing, ask the assistant to run health and contact support if that fails too.

Contacting a person also runs in the background and can take several minutes.

A question fails with a retry message

You see:

Knowledge access changed while processing this request. Please retry.

What you are allowed to see changed while Brain was working on your question. Ask again.

A lookup fails with an id limit message

You see:

Provide at most 3 unique document or chunk ids.

The assistant asked retrieve_company_memory for more pages than one call allows. Ask it to fetch fewer at a time. The limit is 3 unique ids, counting document ids and passage ids together. It is 20 only when the assistant asks for diagnostics.

The server answers 405 when opened in a browser

If you open the Brain MCP address in a browser, or a tool checks it with a GET request, it can answer "405 Method Not Allowed". That is normal. Brain's MCP address takes requests sent with POST, so a plain GET is refused. It does not mean the server is down. Use health or your client's server list to check the connection.

Saving knowledge or a skill fails

These checks run before anything is sent. They apply to both tools unless noted.

You see	What to do
`title is required` (knowledge)	Give the note a title.
`content is required`	Add the text to save.
`content exceeds the 200000 character limit`	Shorten the text or split it into several notes. The limit is 200,000 characters for both a note and a skill.
`name is required` (skill)	Give the skill a name.
`slug is required` (skill)	Give the skill an identifier.
`unsupported content_type; expected one of: text/markdown, text/plain`	Save the note as plain text or Markdown.
"Brain couldn't save this knowledge right now. This is on our side. Try again in a few minutes, and contact support if it keeps failing."	Try again later.
"Unknown agent skill categories: ..." (skill)	Use categories that exist in your organization.
"Cannot publish a skill for knowledge categories you cannot access." (skill)	Publish only for categories you can access.

A note you save can take a few minutes to show up in answers. If your organization's usage has run out, new content waits for the next period. If ingestion is paused, a saved note does not become available while the pause lasts. In both cases the assistant may still tell you "Listo.", which means Brain accepted the note. Asking is not metered, so questions keep working. An admin can check usage under Usage. See Plan and usage.

A skill you publish arrives as pending and cannot be used until an admin approves it. See Skills.

Loading a skill fails

If Brain cannot find the skill, it returns Agent skill '<identifier>' was not found. The skill may not exist, may still be pending, or may be archived. Only active skills you are allowed to use are listed. Ask your assistant to run init again to get the current list, or ask an admin to check the Skills page.

Contacting a person fails

These messages come from request_human_info, the tool that asks a colleague for missing information.

You see	What it means and what to do
"No contact matches that name. Check the name or pick them from the list."	The name you gave is not a configured contact. Only contacts an admin has set up can be asked. See Contacts.
"More than one contact matches that name. Use their full name or pick them from the list."	Give the full name.
"You don't have a contact method yet, so Brain can't contact you. Add one to your profile first."	You asked to be contacted yourself, but your profile has no contact method. Add one, then ask again.
"Company Memory activity not found."	The assistant passed an activity that Brain does not know. Ask the question again from the start.
"We couldn't send this question. This is on our side. Try again in a few minutes, and contact support if it keeps failing."	The request did not go out. Try again later.
"This isn't available right now. This is on our side. Contact support and we'll sort it out."	This cannot be fixed from your side. Contact support.

If no contact is set up at all, the assistant is told to say that no team contact is available. It should not suggest a person. An admin can add contacts under Contacts.

The self-contact rule works like this. When you ask to be contacted yourself, Brain checks that you are the configured contact. If the preview picks someone else, the assistant does not send the request to them. It tells you that you are not available as a configured contact. To fix that, ask an admin to set up your contact, or add your own contact method under your account. See Contacts.

Report a problem through your assistant

If Brain fails in a way you can point to, ask your assistant to report it. It uses report_issue to record what it saw, what it expected and which tool was involved. You can also ask it to send feedback about something Brain lacked. Reports go to the GuruSup team and do not show in the app. They do not fix a wrong company fact: for that, tell your admin, or see Resolve conflicts. See the Tools reference.

Still stuck

Ask your assistant to run the health tool. If it fails, or the problem is one of the "on our side" messages above, contact support.

Was this page helpful?