Concepts and referenceMCP troubleshooting

MCP troubleshooting

Fix the common problems with an assistant connected to Gurusup, from sign-in and the wrong organization to empty answers and tool errors.

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 and the assistant may reword them. For what each tool does, see the Tools reference.

Check what is connected

Start here for most problems.

  1. 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, check that Gurusup is added and that it asked you to sign in. In Claude, open Settings, then Connectors.
  2. Ask the assistant which tools it has from gurusup-brain. The plain address lists 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.
  3. Ask it to run the health tool. It checks whether Gurusup's backend is reachable.

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

Recovery by client

ClientIf the server is missing, not connected or asks you to sign in
ClaudeOpen Settings, then Connectors, and check that the Gurusup connector is listed and turned on for the conversation. If not, add it again. See Claude.
Claude CodeRun /mcp and follow the browser steps to sign in. If it is missing, run the plugin install command again and restart. If you added only the server, check the scope: the default scope is available only in the project you added it in. See Claude Code.
CodexRun /mcp and sign in. If it is missing, run the plugin install command again and restart. See Codex.
CursorLook in Tools & MCP and check the toggle is on. Check that mcp.json is valid JSON. See Cursor.
ChatGPTOpen the plugin link from Gurusup MCP again, add Gurusup if it is missing, and sign in to Gurusup with your work email. See ChatGPT.
VS CodeFollow the steps in the Connect VS Code dialog on Gurusup MCP. Click Start above the server entry in .vscode/mcp.json if it does not connect on its own.

How errors look in your assistant

When a tool fails, the assistant gets an error that starts with "Error executing tool" followed by the tool's name. What comes next tells you where it failed.

  • A plain sentence, such as "Provide at most 3 unique document or chunk ids." The call was refused, usually before it reached Gurusup's backend. The sections below list these sentences and what to do. One comes from the backend: You do not have access to any sources.
  • An HTTP status, such as 403 Forbidden or 503 Service Unavailable, with the address of Gurusup's backend. The backend refused or failed the call. Its own explanation does not reach the assistant, so use the status and the tool name in the table below.
ToolStatusWhat it meansWhat to do
ask_company_memory, search_company_memory, retrieve_company_memory503The memory has not finished building, is being rebuilt, or search is down on Gurusup's sideAsk the assistant to run init. If it says the memory is not ready, wait for the build. Otherwise try again in a few minutes, and contact support if it keeps failing.
retrieve_company_memory403What you are allowed to see changed while Gurusup was answeringAsk again
retrieve_company_memory400The call had no page or passage idAsk again from the question, so the assistant fetches ids first
add_company_knowledge403Adding new content is paused for your organizationAsk an admin, or contact support
add_company_knowledge503Gurusup could not save the note on its sideTry again in a few minutes, and contact support if it keeps failing
add_company_knowledge422A field is over its limit, for example a title longer than 240 charactersCheck the limits in the Tools reference
skills_publishA plain sentence starting "Gurusup rejected these skill categories"A category does not exist, or you cannot access it. The sentence names the refused categoriesUse one of the categories the message lists, and put topic words in tags. If it lists none, ask an admin to grant you a category. See Tools reference.
skills_publishA plain sentence such as "Gurusup could not accept the skill name. Provide a name of 1 to 240 characters."One field was refused, over its limit or in the wrong shape. The sentence names itFix that field and publish again. Your local copy is untouched.
skills_publishA sentence starting "SKILL.md line", with a column and a field, for example "SKILL.md line 3, column 45, field description: the value contains ': ' and isn't quoted. Wrap the value in double quotes."The SKILL.md header could not be read. The sentence names where and how to fix itFix the header and publish again. Your local copy is untouched.
skills_publish"Only this skill's creator or an organization administrator can edit it or publish a new version. To publish your own version, use a different skill name."The skill already exists and you are neither its creator nor an adminPublish under a different skill name, or ask the creator or an admin
skills_publish"This skill is 22.0 MiB and the limit is 20 MiB. Remove or compress large files (the biggest: assets/a.png (3.0 MiB)). Keep your local work. Request a skill upload link, then upload the skill folder as a ZIP (20 MiB package limit). Use the same slug to update an existing skill."A skill can be up to 20 MiB in total. The sentence names the biggest filesRemove or compress large files, then upload the skill as a ZIP.
skills_publish"'[path]' could not be read as base64. Keep your local work. Request a skill upload link, then upload the skill folder as a ZIP (20 MiB package limit). Use the same slug to update an existing skill."A file was not valid base64. Inline base64 is for small text files, not for binaries or packages over 1 MiBUpload the skill as a ZIP.
skills_get404The skill does not exist, is archived, or is still pending and you did not write itAsk the assistant to run init again for the current list
request_human_info404No configured contact matches the person named, or the activity is unknownSee Contacting a person fails
request_human_info409More than one contact matches the nameGive the person's full name
request_human_info400You asked to be contacted yourself and your profile has no contact methodAdd a contact method to your profile, then ask again
request_human_info503The request could not be sent on Gurusup's sideTry again in a few minutes, and contact support if it keeps failing
Any tool401 or 403 with no other cause aboveYour sign-in or your membership in the organization is not valid any moreSign in again from your client. If it keeps failing, contact support.

Gurusup says it is still building your memory

When your assistant calls init before the memory is ready, it gets a short setup contract with your setup progress instead of the usual rules, so it can help you finish setup from the chat. Your assistant may tell you Gurusup is not ready. Questions, searches and lookups fail with 503 until the build has finished.

Gurusup only answers once your organization's memory has been built. Only an admin can build the memory, in the app or through an assistant (memory.start). Members cannot. An admin confirms it with Continue at the end of the sources step in setup. After setup, Gurusup starts the build by itself once a document is ready. Home (called Get started until the memory is built, then Overview) shows "Getting your documents ready." until your content is ready. The build runs in the background, and answers may be incomplete until it finishes. The setup contract comes back while Gurusup rebuilds or recovers the memory too.

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 Gurusup works.

Sign-in fails or keeps asking you to sign in

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 "MCP request has no authenticated end-user identity." or a message about missing claims in the access token, contact support. This comes from how your account reaches Gurusup, 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, if you added only the server, 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 Gurusup

Connecting the server gives the assistant the tools. It does not tell it when to use them. That comes from a short instruction saved in the assistant, per client and, in most clients, per project. The prompt on the docs home page saves it for you. If you connected another way, or the assistant did not save it, add it yourself: Save the instruction has the text and where it lives in each client.

In the meantime, tell the assistant to check Gurusup and ask again. See Ask questions.

Gurusup finds nothing

When Gurusup 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 Gurusup 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. Gurusup can only answer from what it has read.
  • Ask your assistant to search with different terms, or to ask a colleague who would know. See Ask a colleague.

When no page answers, Gurusup tells the assistant either "Nothing in company memory answered this question for you." or "The matches found did not answer your question." The second means it found matches you may read, but none answered the question.

Gurusup also leaves out anything you are not allowed to see, so a fact that exists may not come back for you. That includes a source an admin restricted to other people, even if you are an admin. 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. Gurusup waits up to 10 minutes for its own backend 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

If retrieve_company_memory fails with 403, what you are allowed to see changed while Gurusup was working on your question. Ask again.

When ask_company_memory or search_company_memory fails because your access changed, the assistant is told "Knowledge access changed while processing this request. Please retry." Ask again.

You do not have access to any sources

You see:

You don't have access to any sources in this organization. Ask an organization admin to give you access.

ask_company_memory or search_company_memory found that the organization has sources but you can read none of them: you have no category granted and no restricted source lists you. An organization with no sources, or whose sources were all revoked, does not give this error: there is nothing to deny, so the search comes back empty and the assistant says it found nothing. Ask an organization admin to grant you the categories you need under Team, or to add you to the source's list. See Members and roles and Restrict a source.

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.

A question is too long

You see:

The subject and question together exceed 4,000 characters. Shorten them and try again.

Ask a shorter question, or split it into several.

The server answers 405 when opened in a browser

If you open the Gurusup MCP address in a browser, or a tool checks it with a GET request, it can answer "405 Method Not Allowed". That is normal. Gurusup'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 reaches Gurusup's backend, so their text reaches the assistant. They apply to both tools unless noted.

You seeWhat to do
title is required (knowledge)Give the note a title.
content is requiredAdd the text to save.
content exceeds the 200000 character limitShorten 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.

For failures with an HTTP status, such as paused content or an unknown category, see the table in How errors look in your assistant.

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, and the assistant still tells you "Listo.", which means Gurusup 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. Until an admin approves it, only you can use it, in your personal agents and in the agents you own when you chat with them or run a routine now. The whole organization can use it once approved. The receipt says so: a member reads "Ask an admin in your organization to approve it.", and an admin reads that they can approve it now, so their assistant can do it right away. See Skills.

Loading a skill fails

If skills_get fails with 404, the skill does not exist, is archived, or is still pending and someone else wrote it. 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

request_human_info asks a colleague for missing information. Its failures reach the assistant as an HTTP status:

StatusWhat it means and what to do
404The person you named is not a configured contact, or the assistant passed an activity Gurusup does not know. Only contacts an admin has set up can be asked. Check the name, or ask the question again from the start. See Contacts.
409More than one contact matches that name. Give the full name.
400You asked to be contacted yourself, but your profile has no contact method. Add one, then ask again.
503The request did not go out, or this is not available right now. It is on Gurusup's side. Try again later, and contact support if it keeps failing.

A request can also go out and then not reach the person. These are not HTTP errors: the assistant reads them from the request's delivery explanation and relays them.

What the assistant saysWhat it means and what to do
"[Name] is already on a call with us, so we'll call once it ends, around [date and time] UTC."The request is scheduled, not stuck. Gurusup calls at that time. Nothing to do.
"It's outside [name]'s contact hours, so we'll call at [date and time] UTC."The person is outside their contact hours. Gurusup calls when they start. Nothing to do.
"We space out contact with [name], so we'll call around [date and time] UTC."Gurusup limits how often it contacts one person. It calls at that time. Nothing to do.
"We couldn't call [name] because their phone number needs a country code. Ask an organization admin to add it in Contacts, then ask again."The number was saved without a country code, so Gurusup did not call and no other allowed method was left. An admin edits the number in Contacts, then you ask again.

If no contact is set up at all, the preview returns no contact and 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, Gurusup 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.

An operation fails or is not available

These apply to the tools that run operations in Gurusup: learn and one tool for each operation, such as sources_connect. They come only with the catalog address, https://mcp.brain.gurusup.com/mcp?profile=catalog, not with the plain one. The messages and what they mean are in When an operation fails.

SymptomWhat to do
The assistant says an operation is unavailable, or its tool is not in the tool listYou connected with the plain address, which lists only the 13 original tools: connect with the catalog address instead. Or the operation is not allowed for your role. Some are for admins only. Ask an admin to run it or to change your role. See What each role can do.
"This action isn't available in your Gurusup connection. Continue with the available tools."The address your assistant connected with does not offer that tool. The plain address has only the 13 original tools, so learn and the operation tools are missing. Change the server URL to the catalog address, https://mcp.brain.gurusup.com/mcp?profile=catalog, and reconnect so the assistant reads the current tool list.
"Choose one MCP profile from brain, catalog and compact."The server URL has an empty, unknown or repeated profile. Use the plain address or ?profile=catalog, once.
"Gurusup couldn't confirm your account because of a problem on our side. Your account settings are unchanged and we've been alerted. You don't need to reconnect: once it's fixed, your tools work again here." (the message ends by pointing to Gurusup support)The service that checks who you are failed. It is on Gurusup's side, not your sign-in. Do not disconnect or reconnect. Try again later, and contact support if it keeps happening.
The assistant asks for your key or token in the chatDo not paste it. Credentials go on Gurusup's own page: the assistant should give you a link. Ask it for the link.
A source connected from the chat has no older contentA source learns from the moment it is connected. Ask the assistant to estimate and import history, which uses your usage. See Connect a source from the chat.
The change went through but the assistant says it could not read the detailsAsk it to check the change with a read operation. Do not run the change again.

Report a problem through your assistant

If Gurusup 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 Gurusup lacked. Reports go to the Gurusup team and do not show in the app. Gurusup confirms a report only when it gets a receipt for it. If it cannot, the assistant is told not to say the report was saved and not to send it again, so you may see nothing about it. 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 Gurusup's side" cases above, contact support.