sandbox

Neo4j Sandbox MCP Server

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio neo4j-contrib-sandbox-mcp-server uv run sandbox-api-mcp-server \
  --env PORT="9100 (optional; defaults to 9100 if not set)" \
  --env AUTH0_DOMAIN="Your Auth0 tenant domain (e.g., your-tenant.auth0.com)" \
  --env AUTH0_AUDIENCE="Audience for your Auth0 API (e.g., https://your-tenant.auth0.com/api/v2/)" \
  --env AUTH0_CLIENT_ID="Your Auth0 Application Client ID" \
  --env SANDBOX_API_KEY="Neo4j Sandbox API key" \
  --env AUTH0_CLIENT_SECRET="Your Auth0 Application Client Secret"

How to use

This MCP server exposes a set of tools that interact with the Neo4j Sandbox API via a FastAPI application wrapped with FastMCP. The tools mirror endpoints in the underlying sandbox API, enabling you to list, start, terminate, extend, and fetch connection details for sandbox instances. To use these tools, run the server using UV (as described in installation) and connect with an MCP client or tooling like Claude Desktop via mcp-remote. The server handles authentication through Auth0 and API keys, so ensure your environment is configured with the required credentials.

Once running, you can access tools such as list_sandboxes_for_user to see all sandboxes for the authenticated user, start_new_sandbox to launch a sandbox for a given use case (e.g., movies or blank), and terminate_sandbox to stop a sandbox by its hash key. Additional tools allow you to extend lifetimes and fetch connection details for a sandbox, which is useful for integrating with clients or IDEs that need database connection strings. The provided endpoints are exposed via two transports: SSE (legacy) at /sse and the modern Streamable HTTP transport at /mcp, with authentication enforced at the FastAPI layer.

For client setup, consider using mcp-remote to bridge OAuth token handling and proxy requests to the local MCP server. This simplifies authentication flows when connecting from desktop clients like Claude Desktop.

How to install

Prerequisites:

Python 3.8+ and uv (via the astral uv installer) or a compatible Python environment
Access to a Neo4j Sandbox API key
Auth0 tenant credentials for OAuth2/JWT authentication

Step-by-step installation:

Install UV (if not already installed): macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Clone the repository or navigate to the project directory containing the sandbox-api-mcp-server FastAPI app.
Create a .env file (optional but recommended) in the project root and populate with required environment variables: AUTH0_DOMAIN=your-tenant.auth0.com AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/ AUTH0_CLIENT_ID=your-client-id AUTH0_CLIENT_SECRET=your-client-secret SANDBOX_API_KEY=your-sandbox-api-key
Install dependencies and run the server via UV: uv run sandbox-api-mcp-server
Verify the server is running on http://0.0.0.0:9100 (or the port defined by PORT). You can now connect via an MCP client or mcp-remote.

Notes:

The server relies on Auth0 for authentication and supports API-key authentication as a fallback at the FastAPI layer.
If you change the port, update the PORT environment variable accordingly before starting the server.

Additional notes

Tips and common issues:

Ensure all required environment variables (AUTH0_DOMAIN, AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, SANDBOX_API_KEY) are set and accessible to the process running UV.
If the server fails to start, check that the port is not blocked by another process and that the environment variables are loaded (dotenv support is recommended).
When using Claude Desktop or other MCP clients, prefer the Streamable HTTP transport (/mcp) via mcp-remote for modern compatibility. The SSE transport (/sse) remains for backward compatibility.
If you encounter token expiration issues, refresh tokens via mcp-remote or re-authenticate using the browser prompt triggered by the OAuth flow.
The available tools correspond to FastAPI routes; you can inspect them or test with an MCP client to verify inputs/outputs for each tool.