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

# Claude Code

> Troubleshooting Neptune MCP in Claude Code (CLI)

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

## Installation

Claude Code uses the `claude mcp add` command to install MCP servers:

> [tab] macOS / Linux
>
> ```bash theme={"dark"}
> claude mcp add --transport stdio neptune -- uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```

> [tab] Windows
>
> ```bash theme={"dark"}
> claude mcp add --transport stdio neptune -- cmd /c uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```

## MCP Scopes

Claude Code supports different scopes for MCP server configuration:

| Scope | Flag | Description |
| - | - | - |
| Local | `--scope local` | Available only to you in the current project (default) |
| Project | `--scope project` | Shared with team via `.mcp.json` file |
| User | `--scope user` | Available to you across all projects |

```bash theme={"dark"}
# Make Neptune available across all your projects
claude mcp add --scope user --transport stdio neptune -- uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
```

## Managing MCP Servers

```bash theme={"dark"}
# List all configured servers
claude mcp list

# Get details for Neptune
claude mcp get neptune

# Remove Neptune
claude mcp remove neptune

# Check server status (within Claude Code)
/mcp
```

## Troubleshooting

> [accordion] 'uvx: command not found'
>
> Claude Code 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. Make sure uv is in your PATH
> 3. Try the command again

> [accordion] 'Connection closed' error on Windows
>
> On Windows, you must use the `cmd /c` wrapper:
>
> ```bash theme={"dark"}
> claude mcp add --transport stdio neptune -- cmd /c uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```
>
> Without `cmd /c`, Windows cannot directly execute `uvx`.

> [accordion] Server not appearing in /mcp
>
> 1. Verify the server was added:
>
> ```bash theme={"dark"}
> claude mcp list
> ```
>
> 2. Check the server details:
>
> ```bash theme={"dark"}
> claude mcp get neptune
> ```
>
> 3. Try removing and re-adding:
>
> ```bash theme={"dark"}
> claude mcp remove neptune
> claude mcp add --transport stdio neptune -- uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```

> [accordion] MCP timeout errors
>
> If the server takes too long to start, increase the timeout:
>
> ```bash theme={"dark"}
> MCP_TIMEOUT=10000 claude
> ```
>
> This sets a 10-second timeout (default is lower).

> [accordion] Login not opening browser
>
> If the browser doesn't open when you ask to log in:
>
> 1. Check your system's default browser settings
> 2. Look for a login URL in Claude's response
> 3. Copy and paste the URL manually

> [accordion] Want to share with your team?
>
> Use project scope to create a `.mcp.json` file that can be committed:
>
> ```bash theme={"dark"}
> claude mcp add --scope project --transport stdio neptune -- uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> ```
>
> This creates a `.mcp.json` in your project root that teammates can use.

## Verify Installation

To verify Neptune is working:

1. Run `/mcp` in Claude Code to check server status
2. Ask: "What Neptune tools do you have access to?"
3. You should see tools including `login`, `deploy_project`, etc.

## Learn More

* [Claude Code MCP Documentation](https://code.claude.com/docs/en/mcp)
* [Model Context Protocol](https://modelcontextprotocol.io)

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