preflightai-mcp

Pre-write context safety for AI coding agents.

preflightai-mcp is a Model Context Protocol server that exposes a small set of tools an AI coding agent (Cursor, Claude Desktop, Cline, …) can call before every code edit to ask: "is this edit still safe given what other agents and humans have changed?"

It is the local stdio component of PreflightAI / Nexus. The hosted dashboard and API run on Render; this package is what each engineer runs on their own machine alongside their editor.

Quick start

1. Sign in to the dashboard, create a project, and issue an API key.

2. Add the entry below to your MCP client config (Cursor: ~/.cursor/mcp.json):

   {
     "mcpServers": {
       "preflightai": {
         "command": "npx",
         "args": ["-y", "preflightai-mcp"],
         "env": {
           "NEXUS_API_URL": "https://nexus-web-prod-06o5.onrender.com",
           "NEXUS_API_KEY": "nx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
           "NEXUS_PROJECT_ID": "proj_xxxxxxxxxxxx",
           "NEXUS_CLIENT_NAME": "cursor",
           "NEXUS_ROOT_DIR": "${workspaceFolder}"
         }
       }
     }
   }

3. Restart your editor. The nexus_* tools appear in the agent tool list.

Verify install

npx -y preflightai-mcp --help
NEXUS_API_KEY=nx_live_… NEXUS_PROJECT_ID=proj_… npx -y preflightai-mcp --doctor

--doctor validates env vars, hits /api/health, and confirms the project is reachable.

Tools exposed

| Tool | When to call it | | --- | --- | | nexus_declare_intent | Before starting a coherent unit of work. | | nexus_check_write | Mandatory before every code edit. Returns allow, allow_with_warnings, or block. | | nexus_acknowledge_replan | After a block, once you've read the replan packet. | | nexus_complete_intent | When the intent is done. | | nexus_report_snapshot | Manually push a live worktree snapshot so other agents see your unpushed work. Auto-fired by declare_intent / check_write when NEXUS_LIVE_SNAPSHOT=true. | | nexus_whoami | Resolve API key → GitHub login → stable actorId. | | nexus_status | Health probe. |

Full schemas live in src/server.ts.

Environment variables

| Variable | Required | Default | | --- | --- | --- | | NEXUS_API_URL | no | https://nexus-web-prod-06o5.onrender.com | | NEXUS_API_KEY | yes | — | | NEXUS_PROJECT_ID | yes | — | | NEXUS_CLIENT_NAME | no | agent | | NEXUS_ROOT_DIR | no | process.cwd() | | NEXUS_LIVE_SNAPSHOT | no | on (set to off to disable auto live-snapshot reporting) | | NEXUS_LIVE_SNAPSHOT_MAX_BYTES | no | 204800 (200 KiB cap on file content shipped per snapshot) |

License

MIT.