Cipi Agent

Installation

cipi-agent is a lightweight Laravel package that connects your application to Cipi. It provides a webhook endpoint for automatic deploys on git push, a health check endpoint, an MCP server for AI assistants, a database anonymizer for GDPR-safe data exports, and a set of useful Artisan commands.

$ composer require cipi/agent

The service provider auto-discovers — no configuration or config/app.php change is needed. Cipi already injected the required .env variables during cipi app create, so the package works out of the box.

Artisan commands

Webhook — Automatic Deploys

The agent exposes a POST endpoint at /cipi/webhook. When your Git provider sends a push event, the agent verifies the signature and writes a .deploy-trigger flag file. A cron job running every minute as the app user detects this file, removes it, and runs Deployer in the background.

This design means the webhook response is instant (no HTTP timeout waiting for deployment to complete) and Deployer runs with the correct user permissions — no sudo required.

Configure your Git provider

The token to use is stored in .env as CIPI_WEBHOOK_TOKEN. You can also retrieve it any time with:

$ cipi deploy myapp --webhook

Branch filtering

By default every push triggers a deploy. To restrict deploys to a specific branch, add this to your .env:

CIPI_DEPLOY_BRANCH=main

Pushes to any other branch will receive a skipped response and no deploy will be triggered.

Health Check

The agent also exposes a GET endpoint at /cipi/health that returns a JSON payload with the status of the app, database, cache, queue, and the currently deployed Git commit hash. Useful for external monitoring services such as UptimeRobot. Protected by the CIPI_HEALTH_TOKEN Bearer token — generate one with php artisan cipi:generate-token health.

$ curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
    https://yourdomain.com/cipi/health

{
  "status": "healthy",
  "app_user": "myapp",
  "php": "8.5",
  "laravel": "12.0.0",
  "commit": "a1b2c3d",
  "checks": {
    "database": { "ok": true },
    "cache":    { "ok": true },
    "queue":    { "ok": true, "pending_jobs": 0 }
  }
}

The commit field shows the short Git hash of the currently deployed release, useful for verifying which version is running in production.

MCP Server

cipi-agent includes a built-in MCP server (Model Context Protocol) that exposes your application to AI assistants such as Cursor, VS Code (with GitHub Copilot), and Claude Desktop. The endpoint implements MCP 2024-11-05 over HTTP using JSON-RPC 2.0 and is protected by the CIPI_MCP_TOKEN Bearer token.

The MCP endpoint is available at POST /cipi/mcp and is disabled by default. To enable it:

$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp

Available tools

The MCP server exposes six tools that an AI assistant can invoke by name:

Setup instructions

Run the cipi:mcp Artisan command to get the endpoint URL and ready-to-paste configuration snippets for your AI client:

$ php artisan cipi:mcp

The command prints the available tools and the JSON configuration for Cursor, VS Code, and Claude Desktop.

Cursor

Add the following to ~/.cursor/mcp.json (or go to Cursor → Settings → MCP):

{
  "mcpServers": {
    "cipi-myapp": {
      "type": "http",
      "url": "https://yourdomain.com/cipi/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Replace cipi-myapp with your app user name, yourdomain.com with your actual domain, and YOUR_CIPI_MCP_TOKEN with the token from your .env. Cursor connects natively over HTTP — no bridge needed.

VS Code

VS Code (with GitHub Copilot) supports MCP natively since version 1.102. Add the following to .vscode/mcp.json in your project (or run MCP: Open User Configuration for a global setup):

{
  "servers": {
    "cipi-myapp": {
      "type": "http",
      "url": "https://yourdomain.com/cipi/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Replace cipi-myapp, yourdomain.com, and YOUR_CIPI_MCP_TOKEN as above. Use MCP: Add Server from the Command Palette for a guided setup. VS Code connects over HTTP — no bridge needed.

Claude Desktop

Claude Desktop requires the mcp-remote bridge to convert stdio to HTTP. Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cipi-myapp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yourdomain.com/cipi/mcp",
        "--header",
        "Authorization: Bearer YOUR_CIPI_MCP_TOKEN"
      ]
    }
  }
}

Install mcp-remote globally once with:

$ npm install -g mcp-remote

What you can do with it

Once connected, your AI assistant can interact with the Cipi-managed application in natural language. For example:

User:  Is the app healthy? Any pending jobs in the queue?

Claude: Calling health tool...
         Status: healthy — database, cache, and queue all OK.
         Queue: 0 pending jobs.

User:  Show me the last errors from the log.

Claude: Calling logs tool (lines: 100)...
         Found 2 errors in the last 100 lines:
         [2026-03-04 14:22:01] production.ERROR: Connection refused [...]
         [2026-03-04 14:23:15] production.ERROR: Redis timeout [...]

User:  Clear the cache and deploy the latest version.

Claude: Calling artisan tool (cache:clear)...
         Cache cleared successfully.
         Calling deploy tool...
         Deploy queued — Deployer will run within 1 minute.

User:  What's the current migration status?

Claude: Calling artisan tool (migrate:status)...
         All 47 migrations have been run.

User:  How many users signed up in the last 7 days?

Claude: Calling db_query tool (SELECT COUNT(*) FROM users WHERE created_at >= ...)...
         | count |
         |-------|
         | 23    |

Database Anonymizer

cipi-agent includes a built-in database anonymizer that creates sanitized copies of your production database — ideal for sharing with developers, QA teams, or staging environments without exposing real user data. It supports both MySQL and PostgreSQL and uses Faker-based transformations configured via a JSON file.

How it works

1. A POST /cipi/db request queues an AnonymizeDatabaseJob in the background
2. The job runs php artisan cipi:anonymize, which dumps the database, applies Faker-based transformations according to anonymization.json, and produces a sanitized SQL file
3. When complete, an email notification is sent with a signed download URL
4. GET /cipi/db/{token} serves the anonymized dump via a signed URL that expires after 15 minutes

A utility endpoint POST /cipi/db/user is also available for user ID lookup, useful when building anonymization rules.

Setup

Scaffold the anonymization configuration file:

$ php artisan cipi:init-anonymize

This creates /home/{app_user}/.db/anonymization.json with a starter template. The file is stored outside the project repository for security — it never gets committed.

Configuration

Edit /home/{app_user}/.db/anonymization.json to define which tables and columns to anonymize:

{
  "tables": {
    "users": {
      "name": "name",
      "email": "safeEmail",
      "phone": "phoneNumber",
      "address": "address"
    },
    "orders": {
      "shipping_address": "address",
      "notes": "sentence"
    }
  }
}

Each key under tables is a database table name. Each nested key is a column name, and the value is a Faker formatter (e.g. name, safeEmail, phoneNumber, address, sentence).

Endpoints

All endpoints are protected by the CIPI_ANONYMIZER_TOKEN Bearer token.

Enable the anonymizer

The anonymizer is disabled by default. Enable it and generate a token:

$ php artisan cipi:service anonymize --enable
$ php artisan cipi:generate-token anonymize

ENV Variables

These variables are automatically injected by Cipi into the app's .env during cipi app create. You normally do not need to set them manually.