Skip to content

Latest commit

 

History

History
151 lines (105 loc) · 5.78 KB

windsurf.md

File metadata and controls

151 lines (105 loc) · 5.78 KB

Phantom + Windsurf

Why this combination exists

Windsurf's Cascade AI reads files in your workspace to understand context. A .env file containing real API keys is visible to Cascade and can surface in suggestions, explanations, and generated code.

After phantom init, successfully managed dotenv entries hold phantom tokens (phm_...). Cascade reads the tokens, not the real values. For a supported outbound API call, the authenticated proxy matches an exact route and injects only its route-owned vault value into the fixed auth header. Client-controlled headers and bodies never resolve tokens.

The MCP integration exposes the release-schema-verified catalog in Windsurf's Cascade chat. The current release contract enforces 54 unique tools; runtime tools/list is canonical.


Install

Step 1: install Phantom

Install the reviewed v0.8.7 binary using the platform-specific, checksum- verified path in getting started, then run phantom init in the project.

Step 2: wire up Windsurf (one command)

phantom setup --client windsurf

This writes ~/.codeium/windsurf/mcp_config.json with a phantom MCP server entry. A typical bundled-runtime entry looks like this; setup supplies the actual absolute path:

{
  "mcpServers": {
    "phantom": {
      "command": "/path/to/phantom",
      "args": ["mcp", "serve"]
    }
  }
}

Install both v0.8.7 release binaries before setup. Version 0.8.7 records the running phantom executable with mcp serve when it can resolve that runtime, otherwise it looks for a local phantom-mcp. Setup has no network package-runner fallback and fails closed when neither local runtime is executable. Keep both verified binaries installed and inspect the generated entry. The config is global and applies to every Windsurf workspace.

To preview what would be written without modifying the file:

phantom setup --client windsurf --print

After running setup, restart Windsurf for the MCP server to activate.

Step 3: run Windsurf with the proxy active

phantom exec -- windsurf .

This starts the Phantom proxy, sets *_BASE_URL environment variables, then launches Windsurf. API calls from the integrated terminal flow through the proxy.

For an explicitly supervised longer session, run phantom start in a trusted terminal and keep it open. Copy the printed exports into the terminal that launches Windsurf, then press Ctrl-C in the original owning terminal to stop. Detached --daemon mode and current external process control fail closed; phantom stop authenticates legacy v0.7.3 state only to report manual migration guidance and never kills a process or deletes the record.


MCP tools Windsurf can use

Once phantom is registered, Cascade can call the same runtime catalog as other MCP clients. See the core tool examples in the Claude Code guide, and use MCP tools/list for the canonical catalog.

Frequently used tools in Windsurf sessions:

  • phantom_status — verify .env protection state and service mappings (does not open the vault; use phantom_list_secrets for stored names)
  • phantom_list_secrets — list secret names (values never returned)
  • phantom_add_secret_interactive — returns the terminal command to enter a new secret out-of-band
  • phantom_doctor: run health checks; fix=true requests gated repairs
  • phantom_sync — show which secrets and platforms are configured for deployment sync

Effectful MCP calls, including phantom_doctor with fix=true, are disabled by default. They require PHANTOM_MCP_EFFECTS=trusted-terminal set outside agent authority, confirm: true, and a one-use approval token from an attached-terminal phantom mcp-approve ceremony outside the agent's shell and PTY authority.


Daily flow

# Launch Windsurf with the proxy running
phantom exec -- windsurf .

# Add a new API key without typing the value into chat
phantom add SENDGRID_API_KEY
# enter value at the terminal prompt

# Check that everything is configured correctly
phantom doctor

# Sync secrets to your deployment platform
phantom sync --platform vercel --project prj_abc123

Inside a session started with phantom exec, your application code runs normally. process.env.MY_KEY may hold a phm_... token, while an exact supported proxy route injects its own configured vault value into the upstream auth header. The token itself is never swapped in a client header or body.


Troubleshooting

Cascade reports it cannot find the MCP tools

Verify the config file exists:

cat ~/.codeium/windsurf/mcp_config.json

If the file is missing, re-run phantom setup --client windsurf. If the file is correct, restart Windsurf — MCP servers are loaded at startup.

The proxy environment is not passed to the Windsurf terminal

phantom exec sets environment variables in the shell that spawns Windsurf. If Windsurf was already running before you ran phantom exec, new terminal tabs inherit the original environment, not the proxy environment. Quit Windsurf completely and relaunch via phantom exec -- windsurf ..

phantom setup says the local MCP runtime is missing

On current main, this means setup did not find a runnable bundled server or executable local standalone server. Install both verified binaries using the platform-specific path in getting started, then re-run phantom setup --client windsurf. Released v0.7.9 fails closed instead of generating a registry-backed command.


Reference