APITutorial

MCP server reference

Run approved PreFlight tools from compatible AI development hosts.

AI agents

PreFlight MCP server

The PreFlight MCP server exposes launch-readiness operations to AI hosts such as Cursor, Claude Desktop, and other Model Context Protocol clients. Agents can list projects, trigger full check runs, read Uptime Monitoring status, evaluate Release Rules, and inspect incidents without custom glue code.

The server ships in this repository at src/sdk/mcp/server.ts and talks to the same /api/v1 routes documented in the [API overview](/docs/api/overview). It runs over stdio transport and authenticates with a workspace API key.

What you can automate

| Tool | What it does | | --- | --- | | `list_projects` | Lists every project visible to the configured API key. | | `run_checks` | Runs the full pre-flight suite for a project and returns markdown-formatted probe results. | | `get_status` | Returns overall health, uptime, Uptime Monitoring sampling state, and connected provider status. | | `get_deploy_gate` | Evaluates strict or relaxed release rule policy and lists blocking reasons. | | `get_incidents` | Returns open or acknowledged incidents plus recent failures from the last seven days. | | `get_uptime` | Returns 24h / 7d / 30d uptime percentages and consecutive success streaks. | | `get_activity` | Returns recent audit events (checks, gates, settings, alerts). |

Requirements

API keys must match pf_live_ followed by at least 32 alphanumeric characters. Keys are shown once at creation; store them in your agent host secrets, not in the repo.

Install and run locally

From the PreFlight repository root:

npm install
npm run mcp -- --api-key pf_live_your_key_here --project-id your-project-uuid

Environment variables are loaded automatically from .env.local or .env when present:

PREFLIGHT_API_KEY=pf_live_...
PREFLIGHT_PROJECT_ID=550e8400-e29b-41d4-a716-446655440000
PREFLIGHT_API_URL=https://getpreflight.dev

If PREFLIGHT_PROJECT_ID is omitted and the account owns exactly one project, the server auto-selects it. Multiple projects require an explicit UUID or the projectId argument on each tool call.

Cursor configuration

Add a local MCP entry in Cursor settings (or .cursor/mcp.json):

{
  "mcpServers": {
    "preflight": {
      "command": "npm",
      "args": ["run", "mcp", "--prefix", "/absolute/path/to/preflight"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_...",
        "PREFLIGHT_PROJECT_ID": "your-project-uuid",
        "PREFLIGHT_API_URL": "https://getpreflight.dev"
      }
    }
  }
}

Replace the prefix path with your checkout location. On Windows, use forward slashes or escaped backslashes in the JSON path.

Claude Desktop configuration

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/preflight/src/sdk/mcp/server.ts"],
      "env": {
        "PREFLIGHT_API_KEY": "pf_live_...",
        "PREFLIGHT_API_URL": "https://getpreflight.dev"
      }
    }
  }
}

Example agent prompts

Once connected, ask your agent:

“Run a full PreFlight check on my launch project and summarize blockers.”
“Is the release rule allowing production right now in strict mode?”
“List open incidents and the suggested fix for each failure.”
“What is the 7-day uptime SLA for this project?”

The MCP server returns markdown tables and headings so agents can cite probe keys, fix suggestions, and timestamps directly in chat.

Tool reference

`run_checks`

Triggers POST /api/v1/projects/:projectId/checks and formats the response with status counts, optional AI diagnosis, and per-probe fix suggestions.

`get_deploy_gate`

Maps to GET /api/v1/projects/:projectId/deploy-gate.

`get_incidents`

Troubleshooting

| Error | Fix | | --- | --- | | `PREFLIGHT_API_KEY is not configured` | Pass `--api-key`, set the env var, or add it to the MCP host config. | | `Authentication failed (401)` | Rotate the key in Settings and update the host secret. | | `Failed to connect to PreFlight` | Confirm `PREFLIGHT_API_URL` points at a running host. For local dev, start `npm run dev` first. | | `Multiple projects found` | Set `PREFLIGHT_PROJECT_ID` or pass `projectId` on each tool invocation. | | `Invalid project ID format` | Use the UUID from Dashboard → Projects or `list_projects`. |