Troubleshoot Biohub MCP connections and tool errors

Most connection problems are caused by the URL, the transport, or sign-in. Check these first:

Setting	Value
Server URL	`https://biohub.ai/mcp`, with no trailing slash
Transport	Streamable HTTP, sometimes labeled HTTP
Authentication	Sign-in in your browser with a free Biohub account

Common problems

The browser shows 405 Method Not Allowed

That’s expected. MCP clients send POST requests to the server, and a browser sends a GET, which the server rejects with 405. Add the URL to an MCP client instead, as the Quickstart shows.

The client was added with the wrong transport

Biohub MCP uses Streamable HTTP. A client set up with the older SSE transport opens the connection with a GET request, gets 405, and fails to connect. It can even finish sign-in in the browser and then fail to reconnect with 405. Remove the entry and add it again with HTTP. In Claude Code:

claude mcp remove biohub
claude mcp add --transport http biohub https://biohub.ai/mcp

If you first added it with --scope user or another scope, pass the same scope again. Then enter /mcp, select biohub, and sign in again. In other clients, select Streamable HTTP or HTTP as the server type.

No tools show up

Confirm the URL is exactly https://biohub.ai/mcp.
Make sure you finished signing in. Tools appear only after sign-in; see Sign-in problems if your client still asks you to sign in.
Make sure the server is turned on for your chat. In Claude, click +, select Connectors, and turn on Biohub. In ChatGPT, select Developer mode from the + menu and select Biohub.
Refresh the client’s server list, or restart the client.
Ask your assistant to list the Biohub tools. You should see the tools listed in the Overview.

To check that the server itself is up, send it a request without signing in:

curl -si https://biohub.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | grep -i '^www-authenticate'

The server answers with HTTP 401 and prints a line like this one:

www-authenticate: Bearer scope="email openid", resource_metadata="https://biohub.ai/.well-known/oauth-protected-resource/mcp"

That line tells your client where to find the sign-in page. It means the server is working and waiting for you to sign in.

The tool names have a prefix

Many clients add the server name to each tool, for example mcp__biohub__esm_atlas_search_uniprot. The tools are the same.

The assistant ignores a Skill

Name the Skill in your request, such as “Using the Biohub MCP waveorder-tutorial Skill, …”.
If it still answers on its own, ask it to read the Skill’s SKILL.md URI, such as skill://waveorder-tutorial/SKILL.md, and follow it.
If your client can’t read MCP resources, ask it to call read_resource with the same URI, or list_resources to see every Skill file; see MCP resource reference.
If list_resources and read_resource are missing, refresh the client’s tool list or reconnect.

The assistant can’t run a Skill’s commands

The WaveOrder Skills run the wo command, uv, and napari on your computer, so they need a client that can run commands on a computer with a display. See Start a Skill.

ChatGPT doesn’t show Developer mode

Developer mode is available on the web for Plus, Pro, Business, Enterprise, and Education accounts. On a workspace plan, ask an admin to allow developer mode.

A call is slow or times out

Calls that compute on an ESM Atlas miss take longer, and a complex from ui_show_structure always runs a fold, which has 95 seconds to finish. Folds within the call and ESMC scans can also take tens of seconds. A fold that becomes a run returns at once; ask your assistant to check the run later with biohub_get_inference_run. A structure view with a PNG preview (include_png set to true) takes several seconds longer than one without. Each call has a 120-second deadline, after which the tool returns indeterminate. Some clients stop waiting sooner and report their own timeout. Don’t retry an indeterminate call automatically, because the work may already have started. Wait a while, then ask once more.

Why some calls take longer

How long a call takes depends on whether the tool can return a stored result or has to compute a new one. The ESM Atlas looks up the exact sequence you send. When it has no stored result, some tools compute one for your request:

esm_atlas_get_protein_details computes SAE features for sequences up to 2,048 residues.
esm_atlas_search_similar_protein_clusters computes the query’s features and can predict structures for up to six hits that don’t have one yet.
ui_show_structure predicts a protein’s structure for sequences up to 700 residues.

The folding and ESMC tools always start new work on the Biohub Platform and bill your account. Maximum-accuracy folds and folds over 768 tokens become runs that finish later, as Folding tools explains. Atlas tools and biohub_get_inference_run are marked read-only because they create nothing that you need to manage. ui_show_structure, the folding tools, and the ESMC tools are marked compute and non-idempotent, so your client can ask you to approve each call, even a free single-protein view. These annotations describe what a tool can do, not the input of one call. Calling a tool again can compute, and bill, again. Every call has a 120-second deadline. If it passes, or if the outcome of a compute step is unknown, the tool returns indeterminate. The work may have started, so don’t retry automatically: wait a while before asking again. A fold or ESMC call that started may also have been billed.

The structure appears only as an image or text

Your client doesn’t support MCP Apps, so it can’t show the interactive viewer. It shows the text result, so ask your assistant for a PNG preview if you want a picture. See What your client shows.

The download buttons are disabled

Downloads from the viewer need a client that supports file downloads. You can still explore the structure in the viewer.

The server returns 413 Request Entity Too Large

The request body was over 64 KiB, and it was rejected before it reached a tool. The response is an HTML page, not a JSON-RPC error. Send a smaller request.

A browser-based client gets 403 Forbidden Origin

The server rejects requests sent from web pages on other sites. Connect from a desktop app, a CLI, or your own server-side code instead of from browser JavaScript. Biohub MCP asks you to sign in with a free Biohub account, and any verified email address can sign in. Many fixes below remove the server from your client and add it again, as Remove the server and add it again shows for each client. Some clients hide the server’s message, so match what your client shows to the closest row.

What you see	What it means and what to do
Claude Code shows “needs authentication” for `biohub`	Claude Code shows every `401` and `403` this way. Enter `/mcp`, select `biohub`, and sign in again. If it comes back, run `claude mcp remove biohub`, add the server again, and sign in.
Claude Code shows “failed” for `biohub`	Claude Code couldn’t reach or talk to the server. Check the exact URL and the `http` transport, update Claude Code to 2.1.81 or later, and try again after a minute.
HTTP `401` with `invalid_token`	Your sign-in expired, was made for another server, or was damaged. Sign in again from your client. If the client keeps failing, remove the server and add it again.
HTTP `403` with `Biohub MCP could not tell which app this connection belongs to. Remove the Biohub MCP server from your app and add it again.`	Your sign-in doesn’t say which app it was made for, or it names two different apps. Remove the server and add it again.
HTTP `403` with `This app identifies itself with a client ID Biohub MCP does not accept. Connect with a supported app, such as Claude Code or Codex.`	Your app identified itself with an app address Biohub MCP doesn’t accept. Remove the server and add it again, or connect with a different app.
HTTP `403` with `Your account needs a verified primary email address in a domain Biohub MCP permits.`	Your Biohub account’s main email address isn’t verified, or its domain is blocked. Verify the email address on your Biohub account, or sign out of the sign-in page and sign in with another account.
HTTP `403` with `insufficient_scope`	The client didn’t ask to read your email address when you signed in. Remove the server and add it again, then sign in and allow access to your email address.
HTTP `503` with `Sign-in could not be checked right now. Try again shortly.`	Biohub MCP couldn’t check your account with the sign-in service. Wait the number of seconds in the `Retry-After` header, then try again. Don’t remove the server.

Remove the server and add it again

Removing the server from your client clears its saved sign-in and app identity, which fixes the sign-in errors that link here. For example, if you added Biohub MCP before it required sign-in, your client may say it needs authentication, or show this message:

Biohub MCP could not tell which app this connection belongs to. Remove the Biohub MCP server from your app and add it again.

To start over, remove the server from your client, add it again with the Quickstart steps, and sign in.

Client	Remove the server
Claude Code	Run `claude mcp remove biohub`. If you added it with `--scope user` or another scope, pass the same scope again when you add it back.
Codex, the ChatGPT desktop app, or the Codex IDE extension	Run `codex mcp logout biohub`, then `codex mcp remove biohub`. If you added it in the ChatGPT desktop app and don’t have the Codex CLI, remove `biohub` under Settings, then MCP servers.
Claude.ai or Claude Desktop	Remove the Biohub connector under Customize, then Connectors. A connector can’t change how it signs in after it’s added, so removing it is the only fix. For an organization connector, an Owner removes it under Organization settings, then Connectors.
ChatGPT	Delete the Biohub app you created in developer mode.
Cursor	Remove the `biohub` entry in Cursor Settings, then MCP, or from your `mcp.json`.
VS Code	Remove the `biohub` entry from your `mcp.json` or your user configuration. If Biohub still appears in the Accounts menu, sign out of it there.

Sign out of Biohub in the client, or clear its saved Biohub sign-in, then connect and sign in again in the browser. If the client asks again right after you sign in, remove the server and add it again. Never add a token or a key to the server URL or the client configuration to get around it. Codex signs in with a client metadata document from version 0.148.0, through its own sign-in page on your computer. Otherwise it falls back to dynamic registration, which Biohub MCP also accepts.

Run codex --version and update Codex if it’s older than 0.148.0.
If ~/.codex/config.toml sets mcp_oauth_callback_url, remove that line.
Run codex mcp logout biohub and codex mcp remove biohub, then add the server again as the Quickstart shows.

Codex 0.163.0 fails the last step of codex mcp login --no-browser with invalid_target. Run codex mcp login biohub without --no-browser, and complete the sign-in in the browser it opens.

Codex reports the resource parameter more than once

codex mcp login biohub can fail with a message that ends with The request includes the parameter 'resource' more than once. This happens when the server was added with the --oauth-resource flag. Remove the entry and add it again without the flag:

codex mcp logout biohub
codex mcp remove biohub
codex mcp add biohub --url https://biohub.ai/mcp

The client is reusing an app identity the sign-in service no longer knows, such as a dynamic registration that was deleted. Remove the saved Biohub connection and add it again, as Remove the server and add it again shows. This can happen when you don’t have a Biohub account yet. Create a free account, then connect again. If it keeps happening, the sign-in page’s bot check may be blocked in your browser or network:

Use a current browser with JavaScript turned on.
Try a private window, which rules out saved data and most extensions.
If you’re allowed to, turn off extensions that block scripts or ads, or try without a VPN or proxy.
Make sure your network doesn’t block challenges.cloudflare.com.

If you contact us, include the time it happened, your browser and its version, and any error code the page shows, but never a token or a password.

Error codes

A failed tool call returns a JSON object with a stable code and a readable message. Some codes add fields, such as retry_after_seconds or actual_length and max_length.

Code	Meaning	What to do
`invalid_input`	An input breaks a type, format, or limit. `Tool arguments do not match the supported schema` means an argument is missing, misnamed, the wrong type, or outside its allowed range, such as `top_k` above 12 or `topk` instead of `top_k`. For a complex, the message can give the Biohub Platform’s reason, such as an unknown CCD code. For `esmc_score_mutations`, a wrong `expected_wild_type` usually means the numbering is off.	Fix the input. `esm_atlas_lookup_accession` doesn’t take UniProt accessions, so use `esm_atlas_search_uniprot` for those.
`not_found`	The accession, cluster, feature, resource URI, or fold run doesn’t exist, or the run belongs to another account.	Check the identifier. `esm_atlas_get_cluster_info` only works on cluster representatives, such as hits from similarity search. For a resource, copy the exact URI from `list_resources`.
`restricted`	ESM Atlas guardrails blocked the request, or the Biohub Platform refused a complex, fold, or ESMC request for your account.	Stop, and don’t try to work around it. For a Biohub Platform refusal, check that your account can use the model.
`rate_limited`	The ESM Atlas asked callers to slow down, or your account reached a Biohub Platform limit or ran out of credits.	Wait at least `retry_after_seconds` and make fewer parallel calls. For the ESM Atlas, it is at most 3,600 seconds; a Biohub Platform daily limit can take up to a day to reset. Also check your account’s credits.
`dependency_unavailable`	The ESM Atlas, the Biohub Platform, or an external database is unavailable or sent an unusable response, or a structure is over the viewing limits.	Try again later. If the structure is over the limits, it can’t be viewed here.
`indeterminate`	The deadline passed, or the outcome of a compute step is unknown. A complex fold, fold, or ESMC call may also have been billed.	Don’t retry automatically. If the error has a `run_id`, check that run first. Otherwise wait, then ask once more.
`sequence_too_long_to_fold`	The ESM Atlas has no stored structure, and the sequence is over 700 residues. For a complex in the viewer, it is over 768 tokens, and for the folding tools, over 4,096 tokens.	Don’t trim the sequence to fit, since that would be a different protein. Get scores for a complex of up to 4,096 tokens with the folding tools.
`expired`	A fold run is more than 31 days old, and Biohub has deleted its result.	Fold again if you still need it.
`sequence_too_long_for_features`	The ESM Atlas doesn’t have the sequence, and it’s over 2,048 residues.	Don’t trim the sequence to fit.
`resource_too_large`	The complete result is over 6 MiB, a folded complex is over 20,000 atoms, or a `list_resources` or `read_resource` result is over 128 KiB.	Ask for fewer results, such as a smaller `top_k` or `size`. For a complex, fold fewer or smaller molecules. For a resource, read it through your client’s own MCP resource support.
`internal_error`	An unexpected server failure. Some arrive as a generic error message without a code.	Try once more later.

Limits

Limit	Value
Sequence length for most tools	1 to 4,000 residues
Sequence length for similarity search	1 to 2,048 residues
SAE features computed on a miss	Up to 2,048 residues
Structure prediction on a miss	Up to 700 residues
Similarity search `top_k`	1 to 12, default 10
Structures predicted by one similarity search	Up to 6
UniProt search `size`	1 to 6, default 6
UniProt query length	500 characters
Accession length	128 characters
Viewer PDB size	2 MiB
Viewer atom count	20,000
Highlighted residues	32
Complex size	Up to 768 tokens, in up to 36 chains
Complex fold time	95 seconds
Folding tools	Up to 16 molecules and 4,096 tokens; 768 tokens within the call
Maximum-accuracy runs	10 a day per account, by default
Fold run retention	31 days
ESMC protein length	1 to 2,046 residues
ESMC substitutions per call	64, at up to 8 positions
ESMC positions per scan	400, and at most 200,000 divided by the length
Request body	64 KiB
Complete result	6 MiB
`list_resources` or `read_resource` result	128 KiB
Tool deadline	120 seconds

Similarity search can return fewer than top_k hits, because the ESM Atlas leaves out matches with a similarity score below 0.5 and withholds hits that its guardrails restrict.

Still stuck?

Tell us what happened through the feedback form, including your client, the tool name, and the error code.

Biohub MCP

Tools

Skills

Security and support