Skip to main content
For installation instructions, see the Quickstart.

​
Configuration

MCP servers are configured in the ~/.codeium/windsurf/mcp_config.json file. You can access this via Windsurf Settings → Cascade → Plugins → Manage plugins.
After adding or modifying your MCP configuration, press the refresh button in the Plugins panel to reload the servers.
For more details, see the official Windsurf MCP documentation.

​
Troubleshooting

  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
Windsurf can’t find the uv package manager.
  1. Install uv:
# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Reload Windsurf
On Windows, you must wrap the command with cmd /c:
{
  "mcpServers": {
    "neptune": {
      "command": "cmd",
      "args": ["/c", "uvx", "--from", "git+https://github.com/shuttle-hq/neptune-cli-python.git", "neptune", "mcp"]
    }
  }
}
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
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
If you see permission errors when running uvx:
# 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

Quickstart

Continue with authentication and deploy your first app