> ## 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.

# Generic MCP Setup

> Set up Neptune MCP with any compatible client

Neptune works with any AI tool that supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). This guide covers how to connect using STDIO or HTTP transport.

## Prerequisites

* **Python 3.13+** installed
* **[uv](https://docs.astral.sh/uv/)** package manager

> [tab] macOS
>
> ```bash theme={"dark"}
> brew install uv
> ```

> [tab] Linux
>
> ```bash theme={"dark"}
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```

> [tab] Windows
>
> ```powershell theme={"dark"}
> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
> ```

## Option 1: STDIO Transport (Recommended)

Most MCP clients use STDIO transport, where the client spawns the MCP server as a subprocess and communicates via stdin/stdout.

### The Command

```bash theme={"dark"}
uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
```

### Configuration Format

Most clients use a JSON configuration like this:

> [tab] macOS / Linux
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "neptune": {
>       "command": "uvx",
>       "args": ["--from", "git+https://github.com/shuttle-hq/neptune-mcp.git", "neptune", "mcp"]
>     }
>   }
> }
> ```

> [tab] Windows
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "neptune": {
>       "command": "cmd",
>       "args": ["/c", "uvx", "--from", "git+https://github.com/shuttle-hq/neptune-mcp.git", "neptune", "mcp"]
>     }
>   }
> }
> ```

> [!NOTE]
>
> On Windows, you need to wrap the command with `cmd /c` because most MCP clients can't directly execute `uvx`.

### Where to Put This Configuration

| Client | Config Location |
| - | - |
| Cursor | Settings → Tools & MCP → Add new MCP server |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| VS Code + Cline | VS Code Settings → search "Cline MCP" → Edit in settings.json |
| Windsurf | Settings → Cascade → MCP Servers |
| Warp | `~/.warp/mcp.json` |

## Option 2: HTTP Transport

If your client doesn't support STDIO, or you prefer HTTP, you can run the Neptune MCP as an HTTP server.

### Start the Server

```bash theme={"dark"}
uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp --transport=http
```

The server starts at `http://localhost:8001/mcp` by default.

### Connect Your Client

Configure your MCP client to connect to:

```
http://localhost:8001/mcp
```

### Custom Port

To use a different port:

```bash theme={"dark"}
uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp --transport=http --port=9000
```

> [!WARNING]
>
> The HTTP server must be running before your AI client tries to connect. Consider running it in a separate terminal or as a background service.

## Available Tools

Once connected, your AI assistant has access to these Neptune tools:

| Tool | Description |
| - | - |
| `login` | Authenticate via GitHub OAuth |
| `get_project_schema` | Get the neptune.json schema |
| `add_new_resource` | Get info about resource types |
| `provision_resources` | Create cloud infrastructure |
| `deploy_project` | Build and deploy your app |
| `get_deployment_status` | Check deployment status |
| `wait_for_deployment` | Wait for deployment to complete |
| `get_logs` | Retrieve application logs |
| `set_secret_value` | Set a secret's value |
| `list_bucket_files` | List files in a storage bucket |
| `get_bucket_object` | Retrieve an object from a bucket |
| `delete_project` | Delete project and resources |

## Troubleshooting

> [accordion] 'uvx: command not found'
>
> Make sure `uv` is installed and in your PATH:
>
> ```bash theme={"dark"}
> uv --version
> ```
>
> If not found, reinstall uv and restart your terminal/shell.

> [accordion] Python version error
>
> Neptune MCP requires Python 3.13+. Check your version:
>
> ```bash theme={"dark"}
> python --version
> ```
>
> If needed, install Python 3.13+ from [python.org](https://www.python.org/downloads/).

> [accordion] MCP server fails to start
>
> Try running the command manually in your terminal to see error messages:
>
> ```bash theme={"dark"}
> uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```
>
> Press `Ctrl+C` to stop.

> [accordion] HTTP server connection refused
>
> 1. Make sure the HTTP server is running before connecting
> 2. Check if something else is using port 8001
> 3. Try a different port with `--port=9000`

> [accordion] Windows: Command not working
>
> On Windows, always wrap with `cmd /c`:
>
> ```json theme={"dark"}
> {
>   "command": "cmd",
>   "args": ["/c", "uvx", "--from", "..."]
> }
> ```

## Next Steps

Once connected, head to the [Quickstart](https://docs.neptune.dev/quickstart.md#step-2-authenticate) to authenticate and deploy your first app.


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