---
sidebar_position: 6
title: 6. Use from your AI agent
pagination_prev: get-started/trigger-and-logs
---

# Use Zibby from Claude Code, Cursor, Codex, or Gemini

Zibby ships an MCP (Model Context Protocol) server — [`@zibby/mcp-cli`](../packages/mcp-cli). Add it once to your agent's config and Zibby becomes a first-class tool the agent can call directly from chat. Deploy agents, trigger runs, tail logs — all without leaving your editor.

```
You:    Deploy the browser-test template to my Playhouse project, then run it.
Agent:  → zibby_scaffold_agent
        → zibby_deploy_agent
        → zibby_trigger_agent
        → "Done. Job a23e… completed in 47s, 0 failures."
```

The MCP server runs **locally** as a subprocess of your agent — no Zibby-hosted endpoint, no credentials shared with us, no proxy in the middle. Your existing `~/.zibby/config.json` session is reused if you've already run `zibby login`.

## Install

Pick your agent. All flavors run the same npm package via `npx -y` — no global install.

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### OpenAI Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.zibby]
command = "npx"
args = ["-y", "@zibby/mcp-cli"]
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### Windows note

If your agent on Windows can't find `npx`, wrap with `cmd /c`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
    }
  }
}
```

## First-time login

If you haven't run `zibby login` yet in a terminal, just tell the agent:

```
You:    Log in to Zibby.
Agent:  → zibby_login
        (browser opens to the Zibby login page)
        → "Logged in as you@yourcompany.com (3 projects cached)."
```

Login state lives in `~/.zibby/config.json` (mode `0600`) — the same file the CLI writes. Subsequent agent sessions reuse it.

## What the agent can do

| Read-only | Write |
|---|---|
| List projects | Scaffold an agent from an official template |
| List official templates | Deploy an agent to a project |
| List agents (local + remote) | Trigger a deployed agent |
| Show login status | Run an agent locally (debug) |
| Fetch logs from a run | Download a deployed agent (with explicit user confirmation) |
| Static-validate an agent | |

**Destructive operations stay out of the agent's hands** — agent delete, env-var changes, schedule mutation, and credential management require you to run `zibby` in a terminal. Two-stage authorization for anything that could surprise you.

See the [`@zibby/mcp-cli` package reference](../packages/mcp-cli) for the full tool list and security model.

## Example session

```
You:    What templates are available?

Agent:  → zibby_list_templates
        "Three official templates:
         - browser-test-automation: Playwright preflight + live execution + script gen
         - code-analysis: Jira ticket → analyze → generate code → emit tests
         - generate-test-cases: code diff → prioritized AI-runnable test specs"

You:    Scaffold generate-test-cases into a new agent called "release-tests" in my Playhouse project.

Agent:  → zibby_list_projects                       (resolves "Playhouse" → projectId)
        → zibby_scaffold_agent name=release-tests template=generate-test-cases
        → zibby_validate_agent name=release-tests
        "Scaffolded and validated. Ready to deploy."

You:    Deploy it.

Agent:  → zibby_deploy_agent name=release-tests projectId=…
        "Deployed v1 — UUID 33039db5-2f32-4094-9841-317bc56a88c9."

You:    Run it against this PR diff: ‹pastes diff›

Agent:  → zibby_trigger_agent uuid=33039db5… input={diff: "...", changedFiles: [...]}
        → zibby_agent_logs jobId=c62e97a4… lines=100
        "Run completed in 1m 23s. Generated 7 test specs (4 Critical, 2 High, 1 Medium)."
```

→ Full tool reference: [`@zibby/mcp-cli`](../packages/mcp-cli)