Troubleshoot Biohub MCP connections and tool errors

Most connection problems come down to the URL or the transport. Check these first:

Setting	Value
Server URL	`https://biohub.ai/mcp`, with no trailing slash
Transport	Streamable HTTP, sometimes labeled HTTP
Authentication	None

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 described in Connect your client.

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. 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. In other clients, choose Streamable HTTP or HTTP as the server type.

No tools show up

Confirm the URL is exactly https://biohub.ai/mcp.
Make sure the server is turned on for your chat. In Claude, click +, choose Connectors, and turn on Biohub. In ChatGPT, choose 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 seven tools listed in the Quickstart.

To check the server itself, list its tools from a terminal with the curl command in Other MCP clients.

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.

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. Biohub MCP has no sign-in. Choose no authentication, such as No Authentication in ChatGPT, and leave any key or token fields empty. In Codex, the auth column of codex mcp list reads Unsupported, which is expected.

A call is slow or times out

Calls that compute on an ESM Atlas miss take longer, and a structure view took 15 to 25 seconds in our tests. 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. Security and privacy explains which tools compute.

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, and the PNG preview if it displays images. 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.

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`.	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, or feature doesn’t exist.	Check the identifier. `esm_atlas_get_cluster_info` only works on cluster representatives, such as hits from similarity search.
`restricted`	ESM Atlas guardrails blocked the request.	Stop, and don’t try to work around it.
`rate_limited`	The ESM Atlas asked callers to slow down.	Wait at least `retry_after_seconds`, which is at most 3,600, and make fewer parallel calls.
`dependency_unavailable`	The ESM Atlas 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.	Don’t retry automatically. Wait, then ask once more.
`sequence_too_long_to_fold`	The ESM Atlas has no stored structure, and the sequence is over 700 residues.	Don’t trim the sequence to fit, since that would be a different protein.
`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.	Ask for fewer results, such as a smaller `top_k` or `size`.
`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
Request body	64 KiB
Complete result	6 MiB
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.

Still stuck?

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

​Common problems

​The browser shows 405 Method Not Allowed

​The client was added with the wrong transport

​No tools show up

​The tool names have a prefix

​ChatGPT doesn’t show Developer mode

​The client asks you to sign in

​A call is slow or times out

​The structure appears only as an image or text

​The download buttons are disabled

​The server returns 413 Request Entity Too Large

​A browser-based client gets 403 Forbidden Origin

​Error codes

​Limits

​Still stuck?