> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf

> Troubleshooting Neptune MCP in Windsurf

For installation instructions, see the [Quickstart](https://docs.neptune.dev/quickstart.md#step-1-install-the-neptune-mcp).

## Configuration

MCP servers are configured in the `~/.codeium/windsurf/mcp_config.json` file. You can access this via **Windsurf Settings** → **Cascade** → **Plugins** → **Manage plugins**.

> [!TIP]
>
> After adding or modifying your MCP configuration, press the **refresh button** in the Plugins panel to reload the servers.

> [!NOTE]
>
> For more details, see the [official Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp).

## Troubleshooting

> [accordion] MCP server not appearing
>
> 1. Make sure you've added the configuration in `~/.codeium/windsurf/mcp_config.json`
> 2. Press the **refresh button** in the Plugins panel
> 3. Reload the Windsurf window (`Cmd+Shift+P` → "Reload Window")
> 4. Check if Neptune appears in the MCP servers list

> [accordion] 'uvx: command not found'
>
> Windsurf can't find the `uv` package manager.
>
> 1. Install uv:
>
> ```bash theme={"dark"}
> # macOS
> brew install uv
>
> # Linux
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
>
> 2. Reload Windsurf

> [accordion] Windows: Command fails
>
> On Windows, you must wrap the command with `cmd /c`:
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "neptune": {
>       "command": "cmd",
>       "args": ["/c", "uvx", "--from", "git+https://github.com/shuttle-hq/neptune-mcp.git", "neptune", "mcp"]
>     }
>   }
> }
> ```

> [accordion] Neptune tools not appearing in Cascade
>
> Try asking Cascade: "What MCP tools do you have?"
>
> If Neptune isn't listed:
>
> 1. Check the MCP servers configuration
> 2. Look for error messages in the output panel
> 3. Try removing and re-adding the configuration

> [accordion] Login not opening browser
>
> If the browser doesn't open when you say "Log me in to Neptune":
>
> 1. Check your default browser settings
> 2. Look in Cascade's response for a login URL
> 3. Copy and paste the URL manually into your browser

> [accordion] Permission errors
>
> If you see permission errors when running `uvx`:
>
> ```bash theme={"dark"}
> # macOS/Linux
> chmod +x $(which uvx)
> ```

## Verify Installation

To verify Neptune is working in Windsurf:

1. Open Cascade (the AI chat)
2. Ask: "What Neptune tools do you have access to?"
3. You should see a list including `login`, `deploy_project`, `get_deployment_status`, etc.

## Next Steps

> [card] [Quickstart](https://docs.neptune.dev/quickstart.md#step-2-authenticate)
>
> Continue with authentication and deploy your first app


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.