# Model Context Protocol (MCP)

The Sitequest MCP endpoint lets AI assistants like GitHub Copilot, Claude, or other MCP-compatible clients interact with your infrastructure directly.

## Overview

MCP (Model Context Protocol) is an open standard that allows AI applications to securely connect to external tools and data sources. Sitequest implements a **stateless Streamable HTTP** MCP server.

- **Endpoint:** `POST https://site.quest/mcp`
- **Protocol version:** `2025-03-26`
- **Transport:** Streamable HTTP (stateless, JSON responses)
- **Authentication:** Same API keys as the REST API

## Available Tools

### VPS tools

| Tool | Required scope | Description |
|------|---------------------|-------------|
| `vps_get_pricing` | — | VPS component prices and configuration totals |
| `vps_list` | `vps:read` | List all VPS with status, specs and usage metrics |
| `vps_get` | `vps:read` | Detailed VPS info including live config and status |
| `vps_get_monitoring` | `vps:read` | CPU, memory and ping history plus downtime statistics |
| `vps_get_traffic` | `vps:read` | Current bandwidth usage and daily traffic log |
| `vps_list_files` | `vps:files` | List directory contents via SFTP |
| `vps_read_file` | `vps:files` | Read file content via SFTP |
| `vps_power` | `vps:manage` | Start, stop or restart a VPS (stop and restart require confirmation) |
| `vps_mount_iso` | `vps:manage` | Mount or unmount an ISO image |
| `vps_set_label` | `vps:manage` | Update a VPS display name |
| `vps_list_backups` | `vps:manage` | List all backups of a VPS |
| `vps_create_backup` | `vps:manage` | Create a new backup (requires confirmation) |
| `vps_restore_backup` | `vps:manage` | Restore a VPS from a backup (destructive, requires confirmation) |
| `vps_delete_backup` | `vps:manage` | Delete a backup (destructive, requires confirmation) |
| `vps_get_firewall` | `vps:manage` | Get firewall status and rules |
| `vps_manage_firewall` | `vps:manage` | Add or remove rules, enable or disable the firewall |
| `vps_mkdir` | `vps:manage` | Create a directory |
| `vps_delete_path` | `vps:manage` | Delete a file or directory (requires confirmation) |
| `vps_get_ssh_security` | `vps:manage` | Get SSH security settings |
| `vps_set_password_auth` | `vps:manage` | Toggle SSH password authentication |
| `vps_set_sha1_hmac` | `vps:manage` | Toggle legacy hmac-sha1 algorithms |
| `vps_set_ssh_banner` | `vps:manage` | Show or hide the pre-auth SSH banner |
| `vps_set_post_quantum_kex` | `vps:manage` | Toggle post-quantum key exchange |
| `vps_set_legacy_ciphers` | `vps:manage` | Toggle legacy ciphers |
| `vps_update_openssh` | `vps:manage` | Update OpenSSH to the latest version |
| `vps_rescue_password_auth` | `vps:manage` | Restore password login through the hypervisor when SSH is unreachable |
| `vps_list_ssh_keys` | `vps:manage` | List all SSH keys on a VPS |
| `vps_delete_ssh_key` | `vps:manage` | Remove an SSH key from a VPS (requires confirmation) |
| `vps_reset_password` | `vps:exec` | Generate a new root password (destructive, requires confirmation) |
| `vps_write_file` | `vps:exec` | Write file content via SFTP (max 32 MB) |
| `vps_rename` | `vps:exec` | Rename or move a file or directory |
| `vps_chmod` | `vps:exec` | Change permissions |
| `vps_generate_ssh_key` | `vps:exec` | Generate an SSH key pair, optionally store it for the web terminal |
| `vps_upload_ssh_key` | `vps:exec` | Upload a public SSH key, optionally store it for the web terminal |
| `vps_exec` | `vps:exec` | Run a one-shot SSH command as `root` |
| `vps_upgrade` | `vps:scale` | Upgrade VPS resources (CPU, RAM, storage etc., requires confirmation) |
| `vps_cancel` | `vps:cancel` | Cancel a VPS subscription at period end (requires confirmation) |
| `vps_uncancel` | `vps:cancel` | Reactivate a cancelled VPS subscription |
| `vps_create` | `vps:provision` | Create a new VPS (creates an order and charges the mandate, requires confirmation) |
| `vps_reinstall_os` | `vps:provision` | Reinstall the operating system (destructive, requires confirmation) |

### Domain tools

| Tool | Required scope | Description |
|------|---------------------|-------------|
| `get_domain_pricing` | — | List available TLDs and their prices |
| `check_domain` | — | Check a domain's availability, premium status and price |
| `list_domains` | `domains:read` | List all domains with registration status and DNS record count |
| `get_domain` | `domains:read` | Detailed domain info including DNS records and registrar data |
| `list_dns_records` | `domains:read` | List DNS records of a domain |
| `add_dns_record` | `domains:manage` | Create a DNS record |
| `edit_dns_record` | `domains:manage` | Update an existing DNS record |
| `delete_dns_record` | `domains:manage` | Remove a DNS record (requires confirmation) |
| `set_nameservers` | `domains:manage` | Update domain nameservers |
| `set_transfer_lock` | `domains:manage` | Enable or disable the transfer lock |
| `set_whois_privacy` | `domains:manage` | Enable or disable WHOIS privacy |
| `set_dnssec` | `domains:manage` | Enable or disable DNSSEC |
| `get_authcode` | `domains:manage` | Get the domain auth code (transfer key), domain owner only |
| `cancel_domain` | `domains:cancel` | Cancel a domain at period end (destructive, requires confirmation) |
| `uncancel_domain` | `domains:cancel` | Reactivate a cancelled domain |
| `register_domain` | `domains:provision` | Register a new domain (creates an order and charges the mandate, requires confirmation) |
| `transfer_domain` | `domains:provision` | Transfer a domain to Sitequest (creates an order and charges the mandate, requires confirmation) |

### Order tools

| Tool | Required scope | Description |
|------|---------------------|-------------|
| `get_order_status` | `vps:scale`, `webspace:scale` or `domains:provision` | Get order status by ID or token |
| `list_orders` | `vps:scale`, `webspace:scale` or `domains:provision` | List the orders this key may read, newest first |

### Webspace tools

Shared web hosting with isolated PHP/MariaDB sites. SFTP and exec tools operate as the unprivileged site Linux user, jailed to the site's home directory.

| Tool | Required scope | Description |
|------|---------------------|-------------|
| `webspace_list` | `webspace:read` | List all webspaces with status, plan, CMS and quota usage |
| `webspace_get` | `webspace:read` | Get a webspace including linked domains and disk usage |
| `webspace_get_ssh_info` | `webspace:read` | SSH connection details (host, port, username, host key fingerprint) |
| `webspace_list_files` | `webspace:files` | List directory contents via jailed SFTP |
| `webspace_read_file` | `webspace:files` | Read a file via jailed SFTP |
| `webspace_set_label` | `webspace:manage` | Update the display name |
| `webspace_set_php` | `webspace:manage` | Change the PHP version (8.2 – 8.5, requires confirmation) |
| `webspace_install_cms` | `webspace:manage` | Install or reinstall WordPress, Joomla, TYPO3 or Static (wipes the docroot, requires confirmation) |
| `webspace_link_domain` | `webspace:manage` | Link a user-owned domain and issue a Let's Encrypt certificate |
| `webspace_unlink_domain` | `webspace:manage` | Unlink a linked domain (requires confirmation) |
| `webspace_reset_db_password` | `webspace:manage` | Reset the MariaDB password (returns the new password once, requires confirmation) |
| `webspace_mkdir` | `webspace:manage` | Create a directory inside the jail |
| `webspace_delete_path` | `webspace:manage` | Delete a file or directory (requires confirmation) |
| `webspace_list_ssh_keys` | `webspace:manage` | List authorized SSH keys |
| `webspace_delete_ssh_key` | `webspace:manage` | Remove an authorized SSH key by fingerprint (requires confirmation) |
| `webspace_write_file` | `webspace:exec` | Write a file via jailed SFTP (max 32 MB) |
| `webspace_rename` | `webspace:exec` | Rename or move inside the jail |
| `webspace_chmod` | `webspace:exec` | Change permissions of a file or directory |
| `webspace_add_ssh_key` | `webspace:exec` | Upload an authorized SSH public key |
| `webspace_exec` | `webspace:exec` | Run a one-shot SSH command in the jailed shell |
| `webspace_upgrade` | `webspace:scale` | Increase disk space and/or databases for a fee, no downgrades (requires confirmation) |
| `webspace_cancel` | `webspace:cancel` | Cancel a webspace subscription at period end (destructive, requires confirmation) |
| `webspace_uncancel` | `webspace:cancel` | Reactivate a cancelled webspace subscription |
| `webspace_create` | `webspace:provision` | Provision a paid webspace (creates an order and charges the mandate) |
| `webspace_claim_free` | `webspace:provision` | Claim the one-off free-tier webspace for the account |
| `webspace_delete` | `webspace:provision` | Permanently delete a free webspace (destructive, requires confirmation). Paid webspaces end through `webspace_cancel` |

> Pricing for webspaces is not yet exposed via MCP. Use the REST endpoint `GET /api/v1/webspaces/pricing` until a `get_webspace_pricing` tool is added.

## Setup for VS Code / GitHub Copilot

Create a `.vscode/mcp.json` file in your workspace:

```json
{
  "servers": {
    "sitequest": {
      "type": "http",
      "url": "https://site.quest/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with an API key that has the scopes you need (e.g. `vps:read`, `domains:read`).

After saving the file, VS Code will detect the MCP server automatically. You can then ask Copilot questions like:

- "List my VPS instances"
- "What domains do I have?"
- "Show me the details for server X"

## Setup for JetBrains

In your JetBrains IDE, open **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**, click **Add** and paste this configuration:

```json
{
  "mcpServers": {
    "sitequest": {
      "url": "https://site.quest/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Setup for Claude Code

Add the server from your terminal with one command:

```bash
claude mcp add --transport http sitequest https://site.quest/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

With `--scope project` the configuration goes into your project's `.mcp.json` and applies to everyone working in the repository. In that case, keep the key in an environment variable instead of the file. In a Claude Code session, `/mcp` shows whether the server is connected.

## Setup for Cursor

Create a `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects):

```json
{
  "mcpServers": {
    "sitequest": {
      "url": "https://site.quest/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Under **Settings → MCP** you then see the server and its tools.

## Setup for Other MCP Clients

Any MCP client that supports the **Streamable HTTP** transport can connect. Configure:

- **URL:** `https://site.quest/mcp`
- **Method:** `POST` only (GET returns 405)
- **Headers:**
  - `Authorization: Bearer YOUR_API_KEY`
  - `Content-Type: application/json`
  - `Accept: application/json, text/event-stream`

### Manual JSON-RPC Example

**Initialize:**

```bash
curl -X POST https://site.quest/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0" }
    }
  }'
```

**List available tools:**

```bash
curl -X POST https://site.quest/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
```

**Call a tool:**

```bash
curl -X POST https://site.quest/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "vps_list",
      "arguments": {}
    }
  }'
```

## Security and limits

A connected AI assistant acts with the rights of its key. Files, logs and command output can contain instructions the assistant mistakes for yours.

- **Running code is a separate scope.** Commands, file writes and new SSH keys are only available with `vps:exec` or `webspace:exec`.
- **For diagnostics, `files` is enough.** An assistant can read logs and configuration but change nothing. It still sees any secrets in those files.
- **Restrict the key.** Give it only the scopes and resources it needs, see [Authorization](/en/docs/api/authorization/).
- **`confirm` is not a human approval.** The parameter guards against accidents, but the model sets it itself.
- **Control prompts in your AI tool.** That is where you decide whether it asks before tool calls or runs on its own. Only use automatic modes with tightly restricted keys, ideally with a spending limit.
- **Secrets reach the context.** `vps_reset_password`, `webspace_reset_db_password` and `get_authcode` return their result to the assistant, and with that to the model provider.
- **Tool annotations:** Every tool reports `readOnlyHint` and, if it changes something, `destructiveHint`. Clients can use them to decide when to ask. They are hints, not a security boundary.
- **Output limits:** `stdout` and `stderr` of exec tools and text read from files are limited to 256 KB per result. The start and the end are kept, and the response then includes `truncated: true`. Base64 reads above the limit fail; use the REST API for those.
- **Audit:** Actions appear in the activity log with the channel `mcp`, and the API key used is stored with them. All actions of a client session carry the same run ID and can be shown together there.

## Authentication

MCP uses the same API key system as the REST API. See [Authorization](/en/docs/api/authorization/) for details on creating keys and managing scopes.

## Rate Limiting

MCP requests share the same rate limit as the REST API: **60 requests per minute** per API key. Rate limit headers are included in every response.

## Differences from REST API

| Feature | REST API | MCP |
|---------|----------|-----|
| Protocol | HTTP REST | JSON-RPC 2.0 over HTTP |
| Methods | Standard HTTP verbs | `POST` only |
| Response format | `{ "data": ... }` | JSON-RPC result/error |
| Sessions | Stateless | Stateless (no SSE streaming). `Mcp-Session-Id` only serves as a run ID. |
| Use case | Direct integration | AI assistant integration |

## Source code & client examples

The Sitequest MCP server listing, sample client configurations (VS Code, Claude Desktop, Cursor, and more), and the directory listing for MCP catalogs are maintained in the public repository:

[**github.com/Sitequest-Software/sitequest-mcp**](https://github.com/Sitequest-Software/sitequest-mcp)
