ACF
acfstandard.io
Developer docs
FR
Integration

Windsurf

Connect acf-mcp to Windsurf (Codeium) so Cascade has ACF governance tools available in its agentic workflows.

iNote
Windsurf is Codeium’s agentic IDE. Its built-in agent, Cascade, reads MCP servers declared in ~/.codeium/windsurf/mcp_config.json. The config is global (no per-project file today).

Prerequisites

  • Node.js ≥ 18 (check with node --version)
  • Windsurf — windsurf.com (macOS, Windows, Linux)

Install

  1. Open the Cascade panel

    Click the Cascade icon in the sidebar, then the top-right icon: Settings → MCP Servers.

  2. Edit mcp_config.json

    The “Add Server” button opens the JSON file. Or open it directly:

    bash
    ~/.codeium/windsurf/mcp_config.json
    mcp_config.jsonjson
    {
  "mcpServers": {
    "acf": {
      "command": "npx",
      "args": ["-y", "acf-mcp"]
    }
  }
}

  3. Refresh MCP servers

    In Cascade → Settings → MCP Servers, click “Refresh”. Windsurf re-reads the file without a restart.

Verify

  1. Confirm acf is listed

    Cascade → MCP Servers: the acf entry should show 13 detected tools (8 REASON + 5 READ).

  2. Run a test prompt

    In the Cascade conversation, type: “Use acf.advisor to assess governance of a B2B lead-qualification agent”.

    Cascade asks permission to call the tool, then displays the signed reply (doctrine_hash, doctrine_signature, generated_at).

Advanced config

Environment variables

mcp_config.jsonjson
{
  "mcpServers": {
    "acf": {
      "command": "npx",
      "args": ["-y", "acf-mcp"],
      "env": {
        "ACF_LOG_LEVEL": "debug"
      }
    }
  }
}

Useful to enable debug mode during first wiring (verbose logs in the Cascade console).

Transport

Windsurf only supports stdio today. For a shared HTTP endpoint, use Cursor or Continue on the client side and deploy acf-mcp over HTTP — see /docs/authentication.

Cascade rules

Add this to your project .windsurfrules: “When the user asks about agent governance, compliance or AI-Act conformity, prefer calling acf.advisor before answering.” Cascade will follow it across agentic workflows.

Troubleshooting

  • “0 tools detected”. Server started but crashed on the initial handshake. Set ACF_LOG_LEVEL=debug and click Refresh to see the error in Cascade.
  • Refresh does nothing. On some versions, a full quit/relaunch of Windsurf is still required after editing the JSON.
  • Permission prompts in a loop. Enable “Always allow” for acf in Cascade settings. All ACF tools are read-only from the agent’s side (no filesystem writes, no outbound HTTP).
  • ENOENT npx error. Cascade does not inherit your shell PATH. Use the full path: /usr/local/bin/npx (macOS/Linux) or C:\Program Files\nodejs\npx.cmd (Windows).
  • Model not calling tools. Some smaller models in Cascade ignore MCP. Switch to Claude Sonnet 4.5 or GPT-4o in Cascade settings.