AI agents (MCP)

The Model Context Protocol (MCP) is how AI apps such as Claude, Cursor and VS Code use outside tools. The zefily 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 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#

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

1. Install the CLI#

Follow Zefily 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:

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; 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#

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:

{
  "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:

{
  "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#