# Laravel Cloud MCP Server

MCP server for [Laravel Cloud](https://cloud.laravel.com/) account management
using the [Laravel Cloud API](https://cloud.laravel.com/docs/api/introduction).

It ships with two transports that share the same tools:

- **stdio** — run locally, launched by your MCP client. Authenticates with a
  `LARAVEL_CLOUD_API_TOKEN` from the environment (`src/index.ts`).
- **Cloudflare Worker** — remote, multi-tenant Streamable HTTP server. Each
  caller supplies **their own** Laravel Cloud token as
  `Authorization: Bearer <token>`; nothing is stored on the Worker
  (`src/worker.ts`). See [Deploy to Cloudflare](#deploy-to-cloudflare) and
  [Use with Poke](#use-with-poke).

## Setup (local stdio)

```bash
npm install
npm run build
```

Create a Laravel Cloud API token from your Laravel Cloud organization settings,
then configure your MCP client to launch this server with the token in the
environment:

```json
{
  "mcpServers": {
    "laravel-cloud": {
      "command": "node",
      "args": ["/path/to/laravel-cloud-mcp-server/dist/index.js"],
      "env": {
        "LARAVEL_CLOUD_API_TOKEN": "your-laravel-cloud-api-token"
      }
    }
  }
}
```

API tokens are scoped to a single organization, so the server operates on the
organization that issued the token.

Optional environment variables:

- `LARAVEL_CLOUD_API_BASE_URL`: override the API base URL. Defaults to
  `https://cloud.laravel.com/api`.
- `LARAVEL_CLOUD_USER_AGENT`: override the user agent sent to Laravel Cloud.
  Defaults to `laravel-cloud-mcp-server/1.0.0`.

## Deploy to Cloudflare

The Worker exposes the same tools over the MCP **Streamable HTTP** transport at
`/mcp` (legacy SSE at `/sse`), backed by a Durable Object via the
[`agents`](https://developers.cloudflare.com/agents/) SDK. `GET /` is a health
check.

**Authentication is multi-tenant and pass-through.** The Worker stores **no**
Laravel Cloud credentials. Every request must carry the caller's own Laravel
Cloud token as `Authorization: Bearer <token>`; that token is bound to the MCP
session and used for all Laravel Cloud API calls in that session. Requests
without a bearer token get `401`.

### Deploy

```bash
npm install
npx wrangler login
npm run deploy        # deploys to https://laravel-cloud-mcp-server.<subdomain>.workers.dev
```

No secrets to configure. Optional `LARAVEL_CLOUD_API_BASE_URL` /
`LARAVEL_CLOUD_USER_AGENT` overrides can be added under `vars` in
`wrangler.jsonc`.

### Local development

```bash
npm run dev           # local worker at http://localhost:8787
```

Pass a token per request, e.g.:

```bash
curl -s http://localhost:8787/health
curl -s -X POST http://localhost:8787/mcp \
  -H "Authorization: Bearer <your-laravel-cloud-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"dev","version":"0"}}}'
```

After editing `wrangler.jsonc`, run `npm run cf-typegen` (`wrangler types`) and
typecheck the Worker with `npm run typecheck:worker`.

## Use with Poke

[Poke](https://poke.com/) sends the integration's API key as
`Authorization: Bearer <key>` on every request — so each user simply pastes
**their own Laravel Cloud API token** as the key, and the Worker uses it for
that user.

1. Deploy the Worker (above) and note its URL.
2. In Poke, add an MCP integration:
   - **URL**: `https://laravel-cloud-mcp-server.<subdomain>.workers.dev/mcp`
   - **API Key**: the user's Laravel Cloud API token

   Or via CLI:

   ```bash
   npx poke@latest mcp add \
     https://laravel-cloud-mcp-server.<subdomain>.workers.dev/mcp \
     -n "Laravel Cloud" -k "<user-laravel-cloud-api-token>"
   ```

Each Poke user's token only ever touches their own session; the Worker keeps no
copy. If a request arrives without a token, or the token is rejected by Laravel
Cloud, the corresponding tool call returns an error.

## Tools

### Meta

- `laravel_cloud_get_organization`
- `laravel_cloud_list_regions`
- `laravel_cloud_get_usage`
- `laravel_cloud_list_dedicated_clusters`

### Applications

- `laravel_cloud_list_applications`
- `laravel_cloud_get_application`
- `laravel_cloud_create_application`
- `laravel_cloud_update_application`
- `laravel_cloud_delete_application`
- `laravel_cloud_delete_application_avatar`

### Environments

- `laravel_cloud_list_environments`
- `laravel_cloud_get_environment`
- `laravel_cloud_create_environment`
- `laravel_cloud_update_environment`
- `laravel_cloud_delete_environment`
- `laravel_cloud_start_environment`
- `laravel_cloud_stop_environment`
- `laravel_cloud_get_environment_metrics`
- `laravel_cloud_list_environment_logs`
- `laravel_cloud_purge_edge_cache`
- `laravel_cloud_add_environment_variables`
- `laravel_cloud_delete_environment_variables`

### Domains

- `laravel_cloud_list_domains`
- `laravel_cloud_get_domain`
- `laravel_cloud_create_domain`
- `laravel_cloud_update_domain`
- `laravel_cloud_delete_domain`
- `laravel_cloud_verify_domain`

### Commands

- `laravel_cloud_list_commands`
- `laravel_cloud_get_command`
- `laravel_cloud_run_command`

### Deployments

- `laravel_cloud_list_deployments`
- `laravel_cloud_get_deployment`
- `laravel_cloud_get_deployment_logs`
- `laravel_cloud_initiate_deployment`

### Instances & managed queues

- `laravel_cloud_list_instances`
- `laravel_cloud_get_instance`
- `laravel_cloud_create_instance`
- `laravel_cloud_update_instance`
- `laravel_cloud_delete_instance`
- `laravel_cloud_list_instance_sizes`
- `laravel_cloud_set_default_managed_queue`
- `laravel_cloud_pause_managed_queue`
- `laravel_cloud_resume_managed_queue`
- `laravel_cloud_purge_managed_queue`
- `laravel_cloud_list_failed_jobs`
- `laravel_cloud_retry_failed_job`
- `laravel_cloud_delete_failed_job`

### Background processes

- `laravel_cloud_list_background_processes`
- `laravel_cloud_get_background_process`
- `laravel_cloud_create_background_process`
- `laravel_cloud_update_background_process`
- `laravel_cloud_delete_background_process`

### Caches

- `laravel_cloud_list_caches`
- `laravel_cloud_list_cache_types`
- `laravel_cloud_get_cache`
- `laravel_cloud_create_cache`
- `laravel_cloud_update_cache`
- `laravel_cloud_delete_cache`
- `laravel_cloud_get_cache_metrics`

### Database clusters & databases

- `laravel_cloud_list_database_clusters`
- `laravel_cloud_list_database_types`
- `laravel_cloud_get_database_cluster`
- `laravel_cloud_create_database_cluster`
- `laravel_cloud_update_database_cluster`
- `laravel_cloud_delete_database_cluster`
- `laravel_cloud_get_database_cluster_metrics`
- `laravel_cloud_list_databases`
- `laravel_cloud_get_database`
- `laravel_cloud_create_database`
- `laravel_cloud_delete_database`

### Database snapshots & restores

- `laravel_cloud_list_database_snapshots`
- `laravel_cloud_get_database_snapshot`
- `laravel_cloud_create_database_snapshot`
- `laravel_cloud_delete_database_snapshot`
- `laravel_cloud_create_database_restore`

### Object storage buckets & keys

- `laravel_cloud_list_buckets`
- `laravel_cloud_get_bucket`
- `laravel_cloud_create_bucket`
- `laravel_cloud_update_bucket`
- `laravel_cloud_delete_bucket`
- `laravel_cloud_list_bucket_keys`
- `laravel_cloud_get_bucket_key`
- `laravel_cloud_create_bucket_key`
- `laravel_cloud_update_bucket_key`
- `laravel_cloud_delete_bucket_key`

### WebSocket clusters & applications

- `laravel_cloud_list_websocket_clusters`
- `laravel_cloud_get_websocket_cluster`
- `laravel_cloud_create_websocket_cluster`
- `laravel_cloud_update_websocket_cluster`
- `laravel_cloud_delete_websocket_cluster`
- `laravel_cloud_get_websocket_cluster_metrics`
- `laravel_cloud_list_websocket_applications`
- `laravel_cloud_get_websocket_application`
- `laravel_cloud_create_websocket_application`
- `laravel_cloud_update_websocket_application`
- `laravel_cloud_delete_websocket_application`
- `laravel_cloud_get_websocket_application_metrics`

Destructive tools (deletes plus managed-queue purges) require a `confirm: true`
argument.

The deprecated **Databases (Legacy)** endpoints and the binary
**application avatar upload** endpoint are intentionally omitted; use the
database-cluster tools and the Laravel Cloud dashboard for those.