BladeCP MCP: Troubleshooting

Symptoms of BladeCP MCP in your client and the API errors its tools return, with what to check and what to do.

Symptoms

Symptom	What to check
Only `list_doc_pages`, `get_doc_page` and `search_docs` show up	No key reached the server. Check that `BLADECP_API_KEY` is set in the environment where the agent starts and start a new session. In Codex and Cursor, check the configuration entry of the client. An empty variable or a placeholder that was not expanded counts as no key.
The client asks to sign in with OAuth	The server does not use OAuth. Configure the key as a header instead.
Account tools answer `401`	The key expired or was revoked. Create a new one in the Hub and update the variable.
No `bladecp` server at all	The plugin or the configuration entry is missing, or the client does not support remote Streamable HTTP servers.
Documentation tools appear twice	Two `bladecp` servers are registered (plugin and manual entry). Disable one.

API errors come back as tool errors, with the original status and body of the BladeCP API. The agent can read them and explain what happened:

Error	Meaning
`401`	The key is invalid or revoked. With the code `api_key_expired`, it reached its expiration date. Create a new key and update the variable.
`403` `insufficient_scope`	The key lacks the scope the tool needs. `get_account` lists the scopes of the key.
`403` `KEY_BOUND_TO_MIGRATION` or `404`	The key is tied to one migration, or the item belongs to another account.
`429` `rate_limited`	Too many requests in the current minute. Wait and ask again.
No answer	A timeout or network error. Every call only reads, so it is safe to try again.

BladeCP Agent Skills: the plugin that registers this server and teaches your agent the BladeCP flows.