Cipi API

Laravel package that exposes a REST API, an MCP server, and Swagger documentation for the Cipi server control panel.

Requirements

• PHP 8.2+
• Laravel 12+

Installation

composer require cipi/api

Publish the configuration and assets:

php artisan vendor:publish --tag=cipi-config
php artisan vendor:publish --tag=cipi-assets
php artisan migrate

Seed the API user and create a token:

php artisan cipi:seed-api-user
php artisan cipi:token-create

Features

• REST API — CRUD for apps, aliases, databases, SSL, and async jobs (/api/*), secured with Laravel Sanctum and token abilities. App create supports optional Git for custom apps (SFTP-only), matching Cipi 4.4.4+. Apps can also be taken offline and restored with suspend / unsuspend (HTTP 503 maintenance page), matching Cipi 4.5.8+. HTTP Basic Auth can be enabled, disabled, and inspected per app via /api/apps/{name}/basicauth/* (synchronous, wraps cipi basicauth). App logs (GET /api/apps/{name}/logs) return paginated nginx, PHP-FPM, and Laravel snapshots (requires apps-view). Server status (GET /api/status) returns the same data as cipi status as structured JSON (requires status-view).
• MCP Server — Model Context Protocol endpoint at /mcp for AI-powered integrations.
• Swagger Docs — Interactive API reference at /docs, generated from public/api-docs/openapi.json. The spec covers apps, aliases, deploy, SSL, databases (GET /api/dbs via cipi db list; other /api/dbs/* actions use jobs), and job polling (including structured result types per job).
• Artisan Commands — cipi:token-create, cipi:token-list, cipi:token-revoke.

MCP Integration

The MCP server is exposed at /mcp using Streamable HTTP transport and is secured with the same Sanctum token used by the REST API. A token with the mcp-access ability is sufficient for all MCP tools — per-endpoint REST abilities (apps-view, deploy-manage, etc.) are not required on /mcp.

Generate a token if you haven't already:

php artisan cipi:token-create

Replace https://your-server.com and YOUR_TOKEN in the examples below with your actual Cipi host and token.

VS Code

Create (or edit) .vscode/mcp.json in your workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cipi-token",
      "description": "Cipi API Token",
      "password": true
    }
  ],
  "servers": {
    "cipi-api": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cipi-token}"
      }
    }
  }
}

Restart VS Code after adding the configuration. The token will be requested on first connection and securely stored.

Cursor

Create (or edit) .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "cipi-api": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Restart Cursor after adding the configuration (Cursor v0.40+).

Claude Code

Run the following command from your terminal:

claude mcp add --transport http cipi-api https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Verify the server is connected:

claude mcp list

Available MCP Tools

Once connected, the following tools are available to the AI agent:

... View full README on GitHub