Troubleshooting

When a call fails, your agent sees a short message that starts with ScholarMuse and an error code, for example ScholarMuse insufficient_credits: …. The sections below explain each code. A call that ends in an error is never charged.

The sign-in window does not open

• Start the sign-in yourself. Many agents only open the browser when you ask: in Claude Code type /mcp, select scholarmuse and choose Authenticate; in Codex run codex mcp login scholarmuse; in Gemini CLI run /mcp auth scholarmuse. Connecting your agent lists the step for every agent.
• Look for a link. Some agents print the sign-in link instead of opening it. Copy it into your browser.
• Restart the agent after adding the server, then try again.
• Use the bridge. Some apps can add an MCP server but cannot run the browser sign-in at all. Add ScholarMuse to those through mcp-remote, as shown in Apps that cannot open the sign-in.

ScholarMuse never needs an API key, token or password pasted into your agent. If an agent asks for one during setup, do not give it.

The tools do not show up

Every connected agent can use every ScholarMuse tool, in every discipline. There is nothing to switch on. If your agent does not see them:

1. Check that the server is connected. Most agents show this in their MCP settings or after /mcp. If it shows as needing sign-in, sign in again.
2. Restart the agent, or start a new chat. Many agents load the tool list only when they start.
3. Check the app's own switches. Some apps add a server switched off, or need it selected per chat: in Cherry Studio, enable the server and pick it in the chat's MCP selector; in ChatGPT, type @ and select ScholarMuse.
4. Check the model. The model you chat with must support tool calling.
5. Ask: "List the ScholarMuse capabilities." If that works, the connection is fine and the agent may just need a clearer request.

insufficient_credits

Over REST: HTTP 402. The call needs more credits than you have left, so it was not run. The message says how many the call needs.

Add credits on the Credits page in your account settings, or choose a plan on the pricing page. Free accounts also receive 30 credits each month. See Credits.

paid_plan_required

Over REST: HTTP 402. Figures need a paid plan or a credit pack. The free credits a new account gets cover data tools only, because each figure costs real money to generate.

Buying any plan or credit pack unlocks figures. It can take up to a minute after payment before the change is picked up. See Scientific figures.

rate_limited

Over REST: HTTP 429, with a Retry-After header. Your account sent more calls than its plan allows. Wait a moment and try again.

A credit pack without a plan gets the Starter limits. When your agent sends more calls at once than your plan runs, the extra ones wait their turn; if one waits too long, it returns rate_limited. Over REST, each API key can also send at most 60 requests a minute.

If you hit the limit often, ask your agent to make fewer, larger calls (for example one search with a higher limit instead of many small ones), or move to a larger plan.

upstream_error

Over REST: HTTP 502. The tool could not finish, usually because none of its sources answered, or a source returned something unusable. The message gives the reason.

Try again a little later. If some sources answered and others did not, you get a partial result instead of an error; see Partial results.

invalid_input and unknown_tool

These mean the agent sent a request ScholarMuse could not understand: a missing or wrong argument, or a tool name that does not exist. The message names the problem, and agents usually correct it and try again by themselves. If an agent keeps using an old tool name, restart it so it reloads the tool list.

Disconnect and reconnect an agent

To remove an agent's access, open Connected agents and click Disconnect. It stops working within a minute and has to ask for your approval again.

To reconnect, or to fix a connection that seems stuck:

1. Disconnect it on Connected agents.
2. In your agent, start the sign-in again (for example /mcp → Authenticate in Claude Code, or codex mcp login scholarmuse). If that does not prompt you, remove the ScholarMuse server from the agent and add it again.
3. Sign in at scholarmuse.ai and click Allow.

Still stuck?

Write to davie@daviechen.com with the name of your agent, what you asked, and the error message. The Activity page shows every call with its status, which helps us find it.