GuidesTutorial

MCP integration

Connect Cursor, Claude, Windsurf, Kiro, and other MCP hosts to approved PreFlight tools.

Guides

MCP integration guide

A hands-on walkthrough for connecting PreFlight to AI coding assistants via the Model Context Protocol. By the end of this guide, your agent can trigger checks, evaluate Release Rules, and inspect incidents in natural language.

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools. PreFlight ships an MCP server that wraps the REST API into tool calls — so agents like Cursor, Claude Desktop, Windsurf, and Kiro can interact with your launch infrastructure directly from the editor.

Why MCP matters for launch readiness

| Without MCP | With MCP | | --- | --- | | Switch to browser, open dashboard, navigate to project | Ask agent: "run checks on my project" | | Copy API key, write curl command, parse JSON | Agent calls `run_checks` and summarizes results | | Check release rule status manually before merge | Agent evaluates gate and tells you if it's safe to ship | | Hunt through incident history for the right failure | Agent pulls active incidents with fix suggestions |

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

Step-by-step setup

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. 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. 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. Test the server locally. Run npm run mcp -- --api-key pf_live_... --project-id YOUR_UUID and verify it starts without errors. Configure your AI host. Add the MCP server entry to your host's configuration (see examples below). 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_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.

run_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_status

Returns overall project health including uptime, Uptime Monitoring 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, Uptime Monitoring sampling state, incident count, and per-provider connection status.

get_deploy_gate

Evaluates whether a deployment should proceed.

Example prompt: "Is the release rule allowing production right now in strict mode?"

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

get_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

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_activity

Returns the recent audit log for a project.

Example prompt: "Show me the last 10 release rule 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 release rule would allow this to ship. If it's blocked, summarize what I need to fix."

The agent will:

Call run_checks to run fresh probes
Call get_deploy_gate with mode=strict
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_status, get_incidents, and get_deploy_gate 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_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_activity to distinguish pre-existing issues from new regressions.

Environment variable reference

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `PREFLIGHT_API_KEY` | Yes | — | Bearer token for API authentication | | `PREFLIGHT_PROJECT_ID` | No | Auto-discovered | Default project for tool calls without explicit ID | | `PREFLIGHT_API_URL` | No | `http://localhost:3000` | API base URL (set to production URL in most cases) | The default API URL points to localhost. For most setups, set PREFLIGHT_API_URL=https://getpreflight.dev (or your self-hosted domain) in the MCP host config.

Security best practices

Use a dedicated key. Create a separate API key for MCP — don't share it with CI or other automation. This makes rotation isolated. Store keys in host secrets. Use environment variable configs in your MCP host, not hardcoded values in checked-in files. Scope appropriately. The API key inherits the creating user's project access. Don't use an admin key if the agent only needs read access to one project. Rotate regularly. Generate a new key quarterly, update your MCP config, then revoke the old key in Settings.

Troubleshooting

| Problem | Solution | | --- | --- | | "PREFLIGHT_API_KEY is not configured" | Set the env var in your MCP host config or pass `--api-key` to the server | | "Authentication failed (401)" | Key is invalid or revoked — generate a new one in Settings → API keys | | "Failed to connect to PreFlight" | Check `PREFLIGHT_API_URL` — for production use `https://getpreflight.dev` | | "Multiple projects found" | Set `PREFLIGHT_PROJECT_ID` or pass `projectId` on each tool call | | "Invalid project ID format" | Use the UUID from Dashboard → Projects (not the project name) | | Server starts but agent can't see tools | Restart your AI host after config changes; check path to PreFlight repo | | Tools timeout | Ensure network access from your machine to the API URL | | "npm run mcp" fails | Run `npm install` first; ensure Node.js 20+ is installed |