Skip to main content
ACE3 LogoACE3
Public BetaWe're in Public Beta. Things may break. Please report issues via the Support tab.
Back to Setup Guide

Windsurf Setup

Configure ACE MCP with Codeium's Windsurf AI IDE - Complete step-by-step guide for all platforms.

Prerequisites
1

Node.js 18+ installed

Check with: node --version

2

Windsurf installed

Download Windsurf →

3

ACE CLI installed and logged in

4

ACE server running

1
Open Windsurf Settings

Open Windsurf and navigate to MCP configuration:

1

Open Windsurf Settings

Press Cmd/Ctrl + ,

2

Navigate to MCP

Go to "Cascade" → "MCP Servers"

3

Add or Edit Server

Click "Add Server" or edit the config directly

2
Add ACE Configuration

Add the ACE MCP server configuration. You can do this through the UI or by editing the config file directly:

Config file location:

Add this configuration:

Important: Customize Your Namespace

Replace my-project with a unique namespace for your project. Use lowercase letters, numbers, and hyphens.

3
Restart Windsurf

Restart Windsurf for changes to take effect:

Restart Windsurf

Close and reopen Windsurf, or reload the window via Command Palette

4
Use ACE with Cascade

In Windsurf's Cascade AI assistant, you can now use ACE tools. Try these prompts:

Store a decision:

"Store this architecture decision: using Supabase for auth"

Recall context:

"Recall what we know about the payment integration"

Log work:

"Log today's work on the dashboard feature"

Success!

If Cascade responds by using ACE tools, your setup is complete!

Troubleshooting

"ace: command not found"

The ACE CLI is not in your PATH. Try these fixes:

  1. Reinstall ACE globally: npm install -g @ace3-memory/ace
  2. Check if npm global bin is in PATH: npm bin -g
  3. Add npm global bin to your PATH in ~/.bashrc or ~/.zshrc
ACE not appearing in Cascade

If ACE tools don't appear:

  1. Verify ACE server is running: ace status
  2. Check config file for JSON syntax errors
  3. Restart Windsurf completely (quit and reopen)
  4. Verify the config file path is correct for your OS
"Connection refused" errors

ACE server may not be running:

  1. Start ACE server: ace start
  2. Check health: curl http://localhost:7777/health
  3. Check if port 7777 is blocked by firewall

Pro Tips

Use with Cascade Flows

ACE works great with Cascade's multi-file editing. Ask it to "recall the architecture decisions" before making changes.

Project-Specific Namespaces

Use different namespaces for different projects to keep memories isolated.

Track Technical Debt

Ask Cascade to "track an issue" when you spot technical debt. ACE will remember it for later.

View Dashboard

Visit ace3-ai.com/dashboard to visualize your memories and decisions.

Available ACE Tools

Once configured, Windsurf's Cascade can use these 20+ ACE tools:

ace_rememberace_recallace_get_contextace_searchace_track_issueace_resolve_issueace_find_solutionsace_track_decisionace_best_practicesace_get_statsace_log_workace_architectureace_patternsace_manage_tagsace_graph_connectace_graph_traverseace_create_planace_generate_planace_observe

Next Steps