# 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. |

## Errors

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

## Next step

[BladeCP Agent Skills](/skills.md): the plugin that registers this server and teaches your agent the BladeCP flows.