MCP turns context-switching into conversation. The agent reads structured tool responses and can chain actions — run checks, read the gate, and suggest fixes in one prompt.

Prerequisites

• PreFlight workspace with at least one project and connected providers
• Account API key (Settings → API keys) — starts with pf_live_
• Node.js 20+ installed locally
• An MCP-compatible AI host (Cursor, Claude Desktop, Windsurf, Kiro, or similar)
• Network access to your PreFlight instance (production or localhost)

Step-by-step setup

1. Create an API key. Go to Dashboard → Settings → API keys. Name it something meaningful like cursor-mcp-key. Copy the full pf_live_… value immediately — it's shown only once.

2. Find your project ID. Open Dashboard → Projects and copy the UUID from the project URL or settings page. If you only have one project, the MCP server auto-discovers it.

3. Clone or navigate to the PreFlight repo. The MCP server lives at src/sdk/mcp/server.ts. Run npm install if you haven't already.

4. Test the server locally. Run npm run mcp -- --api-key pf_live_... --project-id YOUR_UUID and verify it starts without errors.

5. Configure your AI host. Add the MCP server entry to your host's configuration (see examples below).

6. Verify the connection. Ask your agent to "list my PreFlight projects" — it should return your project name and UUID.

Host configuration examples

Cursor

Create or edit .cursor/mcp.json in your workspace (or configure via Cursor Settings → MCP):

{
  "mcpServers": {
    "preflight": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "C:/path/to/preflight"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_your_key_here",
        "PREFLIGHT_PROJECT_ID": "550e8400-e29b-41d4-a716-446655440000",
        "PREFLIGHT_API_URL": "https://getpreflight.dev"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (usually in ~/.config/Claude/ on macOS/Linux or %APPDATA%/Claude/ on Windows):

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["tsx", "C:/path/to/preflight/src/sdk/mcp/server.ts"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_your_key_here",
        "PREFLIGHT_PROJECT_ID": "550e8400-e29b-41d4-a716-446655440000",
        "PREFLIGHT_API_URL": "https://getpreflight.dev"
      }
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json in your workspace:

{
  "mcpServers": {
    "preflight": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "C:/path/to/preflight"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_your_key_here",
        "PREFLIGHT_API_URL": "https://getpreflight.dev"
      },
      "disabled": false,
      "autoApprove": ["list_projects", "get_sentinel_status"]
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["tsx", "/path/to/preflight/src/sdk/mcp/server.ts"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_your_key_here",
        "PREFLIGHT_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Tool reference

list_projects

Lists all projects accessible via the configured API key. No parameters required.

Example prompt: "Show me all my PreFlight projects."

Returns: Project names, UUIDs, workspace IDs, and creation dates in a markdown table.

preflight_trigger_checks

Runs the full pre-flight readiness suite for a project.

Example prompt: "Run a full PreFlight check and tell me what's failing."

Returns: Status summary, pass/warning/failure counts, AI diagnosis (if enabled), and detailed probe results with fix suggestions.

get_sentinel_status

Returns overall project health including uptime, Sentinel state, and provider connectivity.

Example prompt: "What's the current health status of my project?"

Returns: Overall status (healthy/degraded/failing), 7-day uptime percentage, average response time, Sentinel sampling state, incident count, and per-provider connection status.

get_deploy_gate_status

Evaluates whether a deployment should proceed.

Example prompt: "Is the deploy gate allowing production right now in strict mode?"

Returns: Allowed/blocked verdict, evaluation mode, blocking reasons with dashboard URLs, and latest check run context.

get_active_incidents

Retrieves active incidents and recent probe failures.

Example prompt: "List open incidents and suggest a fix for each."

Returns: Incident summary, individual incident records with keys and timestamps, plus recent probe failures with error messages and fix suggestions.

get_uptime_sla

Returns uptime percentages across trailing windows.

Example prompt: "What's our 7-day uptime SLA?"

Returns: 24h/7d/30d uptime percentages, sample counts, failure counts, consecutive success streak, and latest sample status.

get_project_activity

Returns the recent audit log for a project.

Example prompt: "Show me the last 10 deploy gate events."

Returns: Activity timeline with status, event type, title, actor, and timestamp.

Workflow recipes

Pre-merge readiness check

Ask your agent before merging a PR:

"Run a PreFlight check, then tell me if the deploy gate would allow this to ship. If it's blocked, summarize what I need to fix."

The agent will:

1. Call preflight_trigger_checks to run fresh probes
2. Call get_deploy_gate_status with mode=strict
3. If blocked, explain each blocker with the fix suggestion from probe results

Morning health review

Start your workday with:

"Give me a health summary: uptime SLA, any open incidents, and whether the gate is clear."

The agent chains get_sentinel_status, get_active_incidents, and get_deploy_gate_status into a single concise briefing.

Incident triage

When an alert fires:

"What incidents are open? For each one, what probe failed and what's the suggested fix?"

The agent calls get_active_incidents and formats the response with probe keys, error messages, and actionable fix suggestions.

Post-deploy verification

After shipping:

"Trigger a full check run and report back. If anything fails, check if it was already failing before the deploy by looking at recent activity."

The agent runs checks, then cross-references get_project_activity to distinguish pre-existing issues from new regressions.

Environment variable reference