MCP Integration

Connect your AI agent to While via the Model Context Protocol.

Connection

Get your API key from Settings → API Keys, or provision one via the admin endpoint.

Connect via SSE transport:

POST https://while.sh/mcp/sse
Authorization: Bearer whl_your_api_key

Your agent auto-discovers all 43 available tools. No manual configuration of tool schemas needed.

Agent Configuration

Claude / Cursor / Windsurf (MCP config)

{
  "mcpServers": {
    "while": {
      "url": "https://while.sh/mcp/sse",
      "headers": {
        "Authorization": "Bearer whl_your_api_key"
      }
    }
  }
}

Direct SSE connection

curl -N -H "Authorization: Bearer whl_..." \
  https://while.sh/mcp/sse

Calling a tool

POST https://while.sh/mcp/tools/call
Authorization: Bearer whl_...
Content-Type: application/json

{
  "name": "while.projects.create",
  "arguments": { "name": "my-app" },
  "sessionId": "optional-for-sse-streaming"
}

Available Tools

43 tools across 11 modules

Projects

4 tools

while.projects.create

Create a new project with staging + production environments

while.projects.list

List all projects

while.projects.get

Get project details by ID

while.projects.delete

Delete a project and all its resources

Deploy

4 tools

while.deploy.trigger

Trigger a new deployment for an environment

while.deploy.list

List deployments for an environment

while.deploy.get

Get deployment details and status

while.deploy.cancel

Cancel a pending or building deployment

Database

5 tools

while.database.provision

Provision a managed PostgreSQL database for an environment

while.database.list

List databases for an environment

while.database.get

Get database details by ID

while.database.delete

Delete a managed database

while.database.credentials

Get database connection credentials

Domains

5 tools

while.domains.add

Add a custom domain with auto-SSL via cert-manager

while.domains.list

List domains for an environment

while.domains.remove

Remove a custom domain and its SSL certificate

while.domains.status

Get domain status including SSL certificate state

while.domains.verifySsl

Trigger SSL certificate verification via cert-manager

Environment Variables

3 tools

while.envvars.set

Set or update an environment variable

while.envvars.list

List environment variables (secrets masked)

while.envvars.delete

Delete an environment variable

Scale

3 tools

while.scale.get

Get the current replica count and status for a deployed app

while.scale.set

Scale an app to a specific number of replicas

while.scale.restart

Restart all pods for a deployed app (rolling restart)

Errors

4 tools

while.errors.ingest

Ingest an error from a running application with stack trace and deploy correlation

while.errors.list

List errors for an environment, optionally filtered by status

while.errors.resolve

Mark an error as resolved

while.errors.summary

Get error count summary (open, resolved, total) for an environment

Performance

3 tools

while.perf.getMetrics

Get performance metrics (p50/p95/p99, throughput, error rate) over a time range

while.perf.getCurrentLatency

Get current latency snapshot: p50/p95/p99, throughput, error rate

while.perf.recordMetrics

Record a performance metric snapshot to the database

Uptime

5 tools

while.uptime.create

Create an HTTP uptime check for an environment

while.uptime.list

List all uptime checks for an environment

while.uptime.delete

Delete an uptime check

while.uptime.status

Get uptime status for all checks with current status

while.uptime.run

Run an uptime check immediately and return the result

Logs

2 tools

while.logs.query

Query application logs with filters (level, limit, since)

while.logs.buildLogs

Get build logs for a specific deployment

Webhooks

5 tools

while.webhooks.create

Create a webhook to receive HTTP notifications when events occur

while.webhooks.list

List all webhook subscriptions

while.webhooks.get

Get webhook details by ID

while.webhooks.delete

Delete a webhook subscription

while.webhooks.test

Send a test payload to a webhook URL to verify it works

API Key Scopes

API keys can be scoped to limit what tools are accessible:

full

All tools — deploy, observe, manage, webhooks

deploy

Deploy, environment, database, and domain management

operate

Runtime operations (scale, restart, env vars, webhooks)

read-only

Read all data, no mutations

sensors-only

Observability data only (errors, perf, uptime, logs)

Guardrails

Certain operations are protected by guardrails. If your agent receives a 403 response, it means a guardrail is blocking the action.

Production Lock

Blocks all deploys to production. Disable in guardrail settings.

Deploy Rate Limit

Max deploys per hour exceeded. Wait for the window to reset.

Configure guardrails in Settings → Guardrails.