# AI Access (MCP)

> Connect your own AI assistant, Claude or any MCP-compatible client, to your FadeHost account and let it manage your servers for you: check status, read...

Source: https://fadehost.com/docs/ai-access/

Connect your own AI assistant, Claude or any MCP-compatible client, to your FadeHost account and let it manage your servers for you: check status, read the console, start/stop/restart, run commands and trigger backups, all from a chat.

FadeHost exposes a standard [Model Context Protocol](https://modelcontextprotocol.io) server at:

```
https://api.fadehost.com/mcp
```

Authentication is a personal access token sent as a `Authorization: Bearer` header.

## Creating a token

1. In the panel, open **Profile → AI Access**.
2. Pick a name and a scope:
   - **Read:** the assistant can look but not touch. Server list, status, console logs, live stats, player activity, backup list.
   - **Manage:** everything in Read, plus start/stop/restart, console commands and creating backups.
3. Click **Create token** and copy it immediately, because **it is shown only once**. If you lose it, revoke it and create a new one.

You can hold up to 10 AI tokens, and revoke any of them at any time from the same page. Revoking a token disconnects that assistant instantly.

## Connecting Claude Code

The AI Access page shows this command pre-filled with your new token:

```bash
claude mcp add --transport http fadehost https://api.fadehost.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

Then just ask: *"Is my server up? Who's online? Restart it if the TPS looks bad."*

## Connecting any other MCP client

Any client that supports **streamable HTTP transport with custom headers** works. The generic configuration:

```json
{
  "mcpServers": {
    "fadehost": {
      "type": "http",
      "url": "https://api.fadehost.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

## What the assistant can do

| Tool | Scope | What it does |
|---|---|---|
| `list_servers` | Read | List every server you can manage, with id, game, status and address |
| `get_server` | Read | Full overview of one server: status, software, RAM/disk, settings, ports, last crash |
| `get_console_logs` | Read | Read recent console output |
| `get_live_stats` | Read | Live memory and CPU usage |
| `get_player_activity` | Read | Join/leave/chat counts and recent players over a time window |
| `list_backups` | Read | List off-site backup snapshots |
| `start_server` | Manage | Start a stopped server |
| `stop_server` | Manage | Stop a running server, saving the world first |
| `restart_server` | Manage | Restart a server |
| `send_console_command` | Manage | Run one console command over RCON and return its output |
| `create_backup` | Manage | Trigger an off-site backup right now |
| `get_creation_options` | Read | The ready-made presets and the per-game options a new server can be created with (keys, allowed values, what your plan allows) |
| `create_server` | Manage | Create a new server. Accepts plain names like "Paper", "Velocity", "1.21.8", a preset ("friends", "any-launcher", "expert"...) and per-game options such as offline mode, difficulty or a map |
| `create_app` | Manage | Deploy a Discord bot or a web app from a GitHub or GitLab repository, with environment variables and optionally a web address (https://name.fadehost.app) in the same call. |
| `list_files` | Files | Browse a server's file system |
| `read_file` | Files | Read a config or text file (up to 96KB) |
| `write_file` | Files | Create or overwrite a config file. Most changes apply after a restart |
| `list_vps` | VPS | List your managed VPS instances with specs, status and SSH host |
| `power_vps` | VPS | Start, shut down or reboot a VPS |
| `list_bots` | Bots | List your hosted Discord bots with id, status, runtime and repo |
| `get_bot_logs` | Bots | Read a bot's runtime logs: deploys, output, crashes |
| `power_bot` | Bots | Start, stop or restart a bot (env variables and deletion stay panel-only) |

Truly destructive operations stay **panel-only by design**: an assistant can never delete a server or VPS, and never restore a backup over your world. File writes overwrite the one file you name, so have the assistant read a file before editing it.

## Build a whole network with your assistant

The server comes with the recipe built in: ask your assistant for a
Hypixel-style network and it can create the backend servers and a Velocity
proxy, wire `velocity.toml` to the right addresses, set up modern forwarding
with a shared secret, flip the backends' `online-mode`, restart everything in
the right order and hand you one address for your players. You only need the
server slots on your plan, and the assistant does the rest.

## How permissions work

- The assistant can only do what **you** can do. Every action goes through exactly the same permission, subscription and quota checks as clicking the button in the panel, team roles included.
- On team servers, the token carries your team permissions: if you can't run console commands in the panel, neither can your assistant.
- Requests are rate-limited to 60 per minute per account.

## Good to know

- Console output returned to the assistant is labelled as untrusted data, so a message typed by a player on your server won't be mistaken for an instruction to your AI.
- The **last used** column on the AI Access page shows when each token was last active, a quick way to spot tokens you can revoke.
- Treat tokens like passwords. Anyone holding a Manage token can start, stop and command your servers.

## Troubleshooting

- **401 Unauthorized:** the token is wrong, revoked, or the header isn't reaching the server. Re-copy the full `Bearer` value.
- **"The server rejected the command":** console commands need the server **running** with RCON reachable, and a Manage-scope token.
- **"No accessible server found":** the id is wrong or the server belongs to an account/team your token can't access. Ask the assistant to call `list_servers` first.