# AI agents (MCP)

> Let Claude, Cursor, VS Code and other AI agents list your servers and sites and deploy or roll back, through the zefily CLI's MCP server and an API token you control.

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is how AI apps such as Claude, Cursor and VS Code use outside tools. The [zefily CLI](/docs/cli) includes an MCP server: `zefily mcp`. Once you add it to your AI app, you can ask things like *"Which of my sites failed their last deploy, and why?"* or *"Deploy shop.example.com and tell me when it is live."*

The agent works through the same [REST API](/docs/api-and-cli) as everything else. It can do only what its API token allows, and with an approval-mode token every change waits for your passkey.

## What the agent can do

| Tool | Does | Token scope |
| --- | --- | --- |
| `list_servers` | Your servers with their state, OS and agent version | `servers:read` |
| `list_sites` | Sites with their type, HTTPS and deploy branch, of one server or all | `sites:read` |
| `list_jobs` | A server's recent jobs (installs, deploys, updates) | `jobs:read` |
| `get_job` | One job's state, failure reason and log | `jobs:read` |
| `deploy_site` | Deploys a site from its repository | `sites:deploy` |
| `rollback_site` | Switches a site back to its previous release, or to a given one | `sites:deploy` |

It cannot open a terminal, read files, change settings or delete anything.

## 1. Install the CLI

Follow [Zefily CLI](/docs/cli): download it for your system and put it on your PATH. Then check in a new terminal that `zefily version` answers.

Some AI apps, Claude Desktop in particular, do not read the PATH your terminal uses. If the app says it cannot start `zefily`, write the program's full path as the `command` in the examples below:

| System | Full path, if you installed as in the CLI guide |
| --- | --- |
| Linux | `/home/<you>/.local/bin/zefily` |
| macOS | `/Users/<you>/.local/bin/zefily` |
| Windows | `C:\Users\<you>\AppData\Local\Programs\zefily\zefily.exe` (in JSON, write each `\` twice: `C:\\Users\\…`) |

`which zefily` (Linux, macOS) or `where.exe zefily` (Windows) prints it.

## 2. Create a token for the agent

Under **Settings → API tokens**, create a token only for the agent:

- **Scopes**: `servers:read`, `sites:read` and `jobs:read` let it look; add `sites:deploy` so it can deploy and roll back.
- **Require my passkey approval for every change**: tick it. A deploy or rollback the agent starts then waits on your dashboard until you approve it with your [approval passkey](/docs/approvals); reading is not affected. The agent is told that the change waits for you.
- **Expires after**: choose a period, so a forgotten token stops working on its own.

The token is shown once. Copy it for the next step; you can revoke it any time in the same list.

## 3. Add Zefily to your AI app

### Claude Code

```bash
claude mcp add zefily --scope user --env ZEFILY_TOKEN=zf_… -- zefily mcp
```

`--scope user` makes it available in every project; leave it out to add it to the current project only. `claude mcp list` shows whether it connects.

### Claude Desktop

In Claude Desktop, open **Settings → Developer → Edit Config**. It opens `claude_desktop_config.json` (on macOS in `~/Library/Application Support/Claude/`, on Windows in `%APPDATA%\Claude\`). Add `zefily` under `mcpServers`, keeping any servers already there:

```json
{
  "mcpServers": {
    "zefily": {
      "command": "zefily",
      "args": ["mcp"],
      "env": { "ZEFILY_TOKEN": "zf_…" }
    }
  }
}
```

Save the file and quit Claude Desktop completely (not only its window), then start it again. Zefily's tools appear under the tools button of the chat box.

### Cursor

**Cursor Settings → MCP → Add new global MCP server** opens `~/.cursor/mcp.json`. Add the same `mcpServers` entry as for Claude Desktop and save.

### VS Code

Run **MCP: Open User Configuration** from the Command Palette (or create `.vscode/mcp.json` in a project) and add:

```json
{
  "inputs": [
    { "type": "promptString", "id": "zefily-token", "description": "Zefily API token", "password": true }
  ],
  "servers": {
    "zefily": {
      "type": "stdio",
      "command": "zefily",
      "args": ["mcp"],
      "env": { "ZEFILY_TOKEN": "${input:zefily-token}" }
    }
  }
}
```

VS Code asks for the token the first time it starts the server and keeps it in its secret storage instead of the file. Use the tools in Copilot Chat's agent mode.

### Other MCP clients

Any client that starts local (stdio) servers works: the command is `zefily`, the argument `mcp`, and the environment variable `ZEFILY_TOKEN` carries the token.

## Keep it safe

- The configuration files above hold the token in plain text (except VS Code's prompt). Do not commit them to a repository or share them.
- Give each agent or computer its own token, so you can revoke one without the others. **Settings → API tokens** shows when each token was last used.
- Keep approval mode on for tokens with `sites:deploy`. A deploy that reaches you unexpectedly is a reason to revoke the token.

## Troubleshooting

| Message | Fix |
| --- | --- |
| The app cannot start `zefily` | Use the full path as `command` (step 1), and restart the app |
| *set ZEFILY_TOKEN to an API token* | Add the `env` entry with your token |
| *the token is missing, wrong, revoked or expired* | Create a new token and put it in the configuration |
| *not allowed (token scope or member role)* | The token lacks the scope the tool needs, or your role does not allow it: create a token with that scope |
| *rate limit reached* | Too many requests in a minute for your plan: wait a moment |
| A deploy waits | That is approval mode: approve it on your dashboard |

---
Source: https://zefily.com/docs/mcp