# BladeCP MCP: Tools

Every tool of BladeCP MCP with its parameters, the modes with and without an API key, what the results contain and the annotations clients read.

Every tool is read-only. These tables are generated from the server itself, so they always match the version in this guide.

## With and without a key

| Tools | Availability |
| --- | --- |
| `list_doc_pages`, `get_doc_page`, `search_docs` | Always, even without a key |
| `get_account`, `list_servers`, `get_server`, `get_server_usage`, `list_server_domains`, `list_migrations`, `get_migration`, `list_migration_destinations` | With a key |


Without a key, the server works in documentation-only mode. An empty header, or a placeholder the client did not expand, counts as no key. With a key, the account tools return what the key can see: see [Keys and permissions](/mcp/keys.md).

## All tools

| Tool | What it does | Parameters | Available |
| --- | --- | --- | --- |
| `list_doc_pages` | Lists every page of the BladeCP Developers documentation (llms.txt) with its title, Markdown URL and summary. Use it to find the page to read with get_doc_page. | `locale` (string, optional): Documentation language: en (default), pt-BR or es. | Always |
| `get_doc_page` | Returns one BladeCP Developers page as Markdown: API keys, the Customer API reference, the CLI, the MCP server, agent skills and the migrators. Read the relevant page before calling an API tool or writing an integration. | `path` (string, required): Page path as listed by list_doc_pages or search_docs, for example getting-started/api-keys, /cli.md, pt-BR/mcp or the full https://developers.bladecp.com/... URL. Use / for the overview page. | Always |
| `search_docs` | Searches the BladeCP Developers documentation and returns the most relevant excerpts, each with its URL and the path to read the full page with get_doc_page. | `query` (string, required): Search terms, for example "create an API key".<br>`locale` (string, optional): Documentation language: en (default), pt-BR or es. | Always |
| `get_account` | Returns the BladeCP account behind the configured API key (GET /api/v1/customer/me): customer UUID and email, the key UUID, its scopes and its rate limit. Use it to check which scopes the key has before calling other tools. | none | With a key |
| `list_servers` | Lists the servers (provisions) the API key can access (GET /api/v1/customer/provisions) as compact rows: uuid, status, primary domain, product, plan, location and domains. Paginated: page starts at 1, limit up to 100 (default 25), and meta.hasMore tells whether another page exists. Needs the provisions:read scope. | `domain` (string, optional): Only the server whose primary domain is exactly this host.<br>`status` (string, optional): Only servers in this status, for example active.<br>`page` (integer, optional): Page number, starting at 1. Default: 1.<br>`limit` (integer, optional): Servers per page, 1 to 100. Default: 25. | With a key |
| `get_server` | Returns one server (GET /api/v1/customer/provisions/{uuid}) with its status, plan resources, location, components with their status and version, and domain bindings. Configuration values and credentials are never included. Needs the provisions:read scope. | `uuid` (string, required): Server (provision) UUID, as returned by list_servers. | With a key |
| `get_server_usage` | Returns the latest resource usage snapshot of a server next to its plan limits (GET /api/v1/customer/provisions/{uuid}/usage): disk, bandwidth, email and FTP accounts, databases and domains, with percentages and a health status. Pass to for an earlier snapshot. Needs the provisions:read scope. | `uuid` (string, required): Server (provision) UUID, as returned by list_servers.<br>`from` (string, optional): Lower bound of the snapshot search, ISO 8601 UTC (ending in Z) or unix seconds.<br>`to` (string, optional): Returns the most recent snapshot at or before this instant, ISO 8601 UTC (ending in Z) or unix seconds. Default: now. | With a key |
| `list_server_domains` | Lists the domains of a server (GET /api/v1/customer/provisions/{uuid}/domains): the primary domain, additional domains and the preview host. Needs the provisions:read scope. | `uuid` (string, required): Server (provision) UUID, as returned by list_servers. | With a key |
| `list_migrations` | Lists the site migrations of the API key owner, newest first (GET /api/v1/customer/me/migrations), as compact rows: uuid, phase, primary domain, backup status, target server and staging URL. A key bound to one migration only sees that migration. cutover_pending and cutover_stalled mean the migration is complete; pointing the domain is optional. Needs the migrations:read scope. | none | With a key |
| `get_migration` | Returns one migration (GET /api/v1/customer/me/migrations/{uuid}): phase, domains, component progress, staging URL, timing and whether a retry is allowed. The discovery report of the backup is omitted unless include_discovery is true. The migration is complete once the preview is approved: cutover_pending and cutover_stalled are complete, pointing the domain is optional and cutoverTarget is the A record address. Needs the migrations:read scope. | `uuid` (string, required): Migration UUID, as returned by list_migrations.<br>`include_discovery` (boolean, optional): When true, keeps the full discovery report of the backup (it can be large). Default: false. | With a key |
| `list_migration_destinations` | Lists the plans and locations the API key owner can migrate a site to (GET /api/v1/customer/me/migration-destinations), with monthly prices in currency units. These are the same choices the Hub offers. Needs the migrations:read scope. | `currency` (string, optional): Only plans with a monthly price in this ISO 4217 currency, for example USD or BRL. | With a key |


## Results

- Results are compact. Server details never include configuration values or credentials.
- `list_servers` is paginated: `page` starts at 1 and `limit` goes up to 100, 25 by default. `meta.hasMore` tells whether there is another page.
- `get_migration` leaves out the discovery report of the backup unless you pass `include_discovery: true`, because it can be large.
- `get_doc_page` takes a slug such as `cli` or `pt-BR/mcp`, a `.md` path or a full address of this site, and `/` for the overview.

## Annotations

Each tool declares the standard MCP annotations. Clients can show them, or use them to decide when to ask you before a call. They are hints; the guarantee is that the server only sends read requests to the BladeCP API.

| Annotation | Value | Meaning |
| --- | --- | --- |
| `readOnlyHint` | `true` (every tool) | Only reads: the tool changes nothing in your account. |
| `destructiveHint` | `false` (every tool) | Never deletes or overwrites anything. |
| `idempotentHint` | `true` (every tool) | Calling it again with the same input has no further effect, so a retry is safe. |
| `openWorldHint` | `true` (every tool) | Reaches a service outside the agent: the BladeCP API or this documentation. |


## Next step

[Keys and permissions](/mcp/keys.md): the scopes the account tools need.