Windsurf

Connect Pharaoh to Windsurf so it sees your codebase architecture when you use AI features.

Prerequisite: Install the GitHub App first.

Setup

Option A: Windsurf settings UI

1. Open Windsurf

2. Go to Settings > MCP Servers

3. Click Add

4. Enter the URL: https://mcp.pharaoh.so/sse

5. Complete the GitHub OAuth flow in the browser window that opens

Option B: Config file

Add to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "pharaoh": {
      "url": "https://mcp.pharaoh.so/sse"
    }
  }
}

Restart Windsurf after saving. The OAuth flow runs on first connection.

Verify

Open Windsurf's AI chat (Cascade) and ask:

What modules does this codebase have?

Cascade should call get_codebase_map and return a module breakdown with file counts, function counts, and dependency relationships.

What happens automatically

• Cascade calls Pharaoh tools before making architectural decisions - checking for duplicate functions, understanding callers, mapping module boundaries

• Every push to your default branch refreshes the graph within minutes

• No config files or per-repo setup needed after the initial install

• Pharaoh tools return structured data in minimal tokens so the AI has room to reason

Troubleshooting

MCP option not available in settings: Update Windsurf to the latest version. MCP support requires a recent release.

Auth fails or OAuth window doesn't open: Authorize with the same GitHub account that has the Pharaoh app installed. If you have multiple GitHub accounts, check which one is signed in to your browser.

Tools not showing in Cascade: Restart Windsurf after adding the MCP server. Check that the server shows a connected status in Settings > MCP Servers.

"No repos found" or empty results: The GitHub App must be installed on the correct org or account. Go to github.com/apps/pharaoh-so/installations/new and verify the installation.

Config file location varies by OS: On macOS: ~/.codeium/windsurf/mcp_config.json. On Linux: ~/.codeium/windsurf/mcp_config.json. On Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json.