Code Index MCP for Windsurf: Setup & Config

What you can do with Code Index in Windsurf

Use quick file indexing and opt-in deep syntax analysis to help assistants navigate larger repositories.

• Find code affected by an API migration.
• Locate files by glob before inspecting them.
• Keep file discovery current as the workspace changes.

Before you start: Code Index in Windsurf

• Python 3.10+
• uv / uvx
• A project directory to index
• A native search utility for regex mode

Call set_project_path after launch or use the documented --project-path option. File watching refreshes the shallow index; build_deep_index is required for symbol summaries. Windows clients may need the profile-directory environment overrides described in the README.

Code Index Windsurf configuration

1. Choose Windsurf configuration scope

   For Code Index MCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Code Index MCP to Windsurf

   Use the code-index-mcp entry below in mcpServers. Keep Code Index MCP's documented stdio connection fields and your other Windsurf entries.

3. Check Code Index MCP in Windsurf

   Code Index MCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "code-index-mcp": {
      "command": "uvx",
      "args": [
        "code-index-mcp"
      ],
      "env": {}
    }
  }
}

Code Index tools available to Windsurf

Code Index's stored tool list documents 13 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

set_project_path

After refreshing Code Index in Windsurf settings, check Cascade's tool list for set_project_path.

Choose a repository directory and initialize its index.

refresh_index

After refreshing Code Index in Windsurf settings, check Cascade's tool list for refresh_index.

Rebuild the shallow file index.

build_deep_index

After refreshing Code Index in Windsurf settings, check Cascade's tool list for build_deep_index.

get_settings_info

After refreshing Code Index in Windsurf settings, check Cascade's tool list for get_settings_info.

search_code_advanced

After refreshing Code Index in Windsurf settings, check Cascade's tool list for search_code_advanced.

find_files

After refreshing Code Index in Windsurf settings, check Cascade's tool list for find_files.

Find repository files using glob patterns.

get_file_summary

After refreshing Code Index in Windsurf settings, check Cascade's tool list for get_file_summary.

Summarize file structure and symbols using the deep index.

get_file_watcher_status

After refreshing Code Index in Windsurf settings, check Cascade's tool list for get_file_watcher_status.

configure_file_watcher

After refreshing Code Index in Windsurf settings, check Cascade's tool list for configure_file_watcher.

create_temp_directory

After refreshing Code Index in Windsurf settings, check Cascade's tool list for create_temp_directory.

check_temp_directory

After refreshing Code Index in Windsurf settings, check Cascade's tool list for check_temp_directory.

Check index storage location and permissions.

clear_settings

After refreshing Code Index in Windsurf settings, check Cascade's tool list for clear_settings.

Reset cached index data and configuration.

refresh_search_tools

After refreshing Code Index in Windsurf settings, check Cascade's tool list for refresh_search_tools.

Detect available native search utilities again.

Code Index: full stored tool descriptions

Troubleshooting Code Index in Windsurf

• Check uvx code-index-mcp (from uv, for Python tools) on the machine running Windsurf's MCP integration for Code Index MCP; refresh MCP and inspect Cascade's tools.
• Code Index MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Deep summaries require build_deep_index first.
• Known limitation: Languages outside the specialized set get basic fallback indexing.
• Known limitation: Regex search requires an installed native search utility.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions