# MCP reference

Endpoint: `https://api.plsk.org/mcp`. Transport: Streamable HTTP. Protected resource metadata: `https://api.plsk.org/.well-known/oauth-protected-resource/mcp`.

## Authentication

OAuth 2.0 authorization code flow with PKCE and dynamic client registration. The authorization server is `https://my.plsk.org` (metadata at `/.well-known/oauth-authorization-server`). The access token (`plso_…`) is sent as `Authorization: Bearer <token>`. A connection is valid for at most 30 days and can be revoked in the cabinet.

A connection has one of two scopes, chosen at consent:

| Scope | Permits |
|---|---|
| `read` | Listing and reading. `site_api` with `GET` and `HEAD`. |
| `manage` | Everything in `read`, and creating, changing and deleting. |

## Account tools

| Tool | Parameters | Scope | Description |
|---|---|---|---|
| `list_subscriptions` | none | read | Lists the subscriptions of the account. |
| `get_subscription` | `id` | read | Returns one subscription. |
| `create_subscription` | `name` (1 to 40 characters), `idempotency_key` (1 to 64 characters from `A-Z a-z 0-9 _ -`) | manage | Creates a subscription. A repeated `idempotency_key` returns the existing subscription. |
| `delete_subscription` | `id` | manage | Deletes a ready subscription or removes a failed one. |
| `retry_subscription` | `id` | manage | Retries a failed subscription. |
| `list_subscription_keys` | `id` | read | Lists the keys of a subscription without secrets. |
| `create_subscription_key` | `id`, `lifetime` (`1d`, `7d`, `subscription`) | manage | Issues the subscription key. The secret is returned once. |
| `revoke_subscription_key` | `id`, `key_id` | manage | Revokes a key. |
| `submit_feedback` | `kind` (`bug`, `feedback`), `title` (5 to 120 characters), `message` (20 to 8000 characters), `include_recent_calls` (boolean, optional) | read | Submits a report. With `include_recent_calls`, the tool name, Plesk method name, status and duration of the account's calls of the past hour are appended; arguments and results are never attached. |

## Plesk tools

| Tool | Parameters | Scope | Description |
|---|---|---|---|
| `site_api` | `subscription_id`, `method`, `path`, `query` (object of strings, optional), `body` (JSON, optional) | read for `GET` and `HEAD`, manage otherwise | One request to the Plesk REST API of the subscription. `path` is relative to `/api/plesk/v2`. A path beginning with `/modules/<extension>/` addresses an extension API, for example `/modules/wp-toolkit/v1/installations`. |
| `plesk_api_reference` | `text` (optional), `limit` (1 to 500, optional) | read | Lists operations of the core Plesk REST API (method, path, summary). Requires no subscription. Extension APIs are not listed. |

The result of `site_api` is `{"status": <number>, "content_type": "<type>", "body": <value>}`. `body` is parsed JSON, text, or `{"encoding": "base64", "data": "<base64>"}` for binary content. It is truncated at 256 KiB, indicated by `"truncated": true`. Statuses 4xx and 5xx from Plesk are returned as results.

## Plesk MCP tools

The following tools pass requests to the MCP server of the WebPros Dashboard. Each subscription has its own token there, limited to one server and one Plesk customer; the requests run as that customer. All tools take `subscription_id`. The rate limit is 120 requests per minute per subscription.

| Tool | Parameters | Scope | Description |
|---|---|---|---|
| `si_plesk_api_method_list` | `subscription_id`, `filter` | read | Searches Plesk API methods by words in the name, summary or path. At most 50 methods are returned. |
| `si_plesk_api_method_usage` | `subscription_id`, `methodName`, `includeOutputSchema` (optional) | read | Returns the arguments of a method and the tool that executes it. |
| `si_plesk_api_method_execute_read` | `subscription_id`, `methodName`, `arguments` (object, optional) | read | Executes a method that only reads. |
| `si_plesk_api_method_execute_write` | `subscription_id`, `methodName`, `arguments` (object, optional) | manage | Executes a method that changes data. |
| `si_plesk_api_method_upload` | `subscription_id`, `methodName`, `arguments` (object, optional) | manage | For methods that take a file. Returns an upload URL and the request that sends the file. |

Method names correspond to Plesk REST operations (`get_domains`, `post_databases`). The methods of WP Toolkit have no prefix (`createinstallation`, `getinstallations`) and are found with the filter `wordpress`. Methods that create or delete Plesk API keys or panel sessions (`post_auth_keys`, `delete_auth_keys_by_key`, `post_server_session`) are neither listed nor executed.

## Errors

A failed call returns a tool error whose text is `{"error": {"code": "<code>", "message": "<text>"}}`.

| Code | Condition |
|---|---|
| `invalid_input` | A parameter is missing or malformed. |
| `insufficient_scope` | The connection has the scope `read` and the call requires `manage`. |
| `not_found` | The subscription does not exist in the account. |
| `not_available` | The subscription is not ready, has expired, or its Plesk access is not available yet. |
| `not_ready`, `not_failed` | The state of the subscription does not permit the operation. |
| `quota_exceeded` | The account has 5 active subscriptions. |
| `idempotency_key_spent` | The key belongs to a subscription that was deleted; a new key is required. |
| `key_exists` | The subscription already has an active key. |
| `disclosure_required` | The research disclosure has not been acknowledged in the cabinet. |
| `bad_path`, `blocked_path` | The `site_api` path is malformed or not offered. |
| `blocked_method` | The method creates credentials or sessions. |
| `rate_limited` | The rate limit is exceeded. |
| `upstream_error` | Plesk or the WebPros Dashboard did not answer or refused the request. |
| `spec_unavailable` | The Plesk specification could not be obtained. |
| `internal_error` | Internal error. |

Interpretation of Plesk refusals: [Troubleshooting](/troubleshooting).