delta0-sdk

Relay CLI that bridges local MCP servers to delta0 Inspector through Supabase Realtime.

delta0 Inspector runs in the browser, which means it cannot directly communicate with MCP servers running on your local machine or private network. delta0-sdk solves this by acting as a transparent message bridge — it connects to a Supabase Realtime channel on one side and your local MCP server on the other, forwarding JSON-RPC messages bidirectionally without interpreting them.

Browser (delta0 Inspector)
    ↕ Supabase Realtime
delta0-sdk (this CLI)
    ↕ STDIO / SSE / Streamable HTTP
Local MCP Server

Quick Start

1. Get a relay token

In the delta0 Inspector web app, open your project settings and click "Copy relay token". This gives you a base64url-encoded string containing your connection credentials.

2. Run the relay

npx delta0-sdk connect <token> -- npx @modelcontextprotocol/server-filesystem /tmp

That's it. The relay will start your MCP server locally, connect to the Supabase Realtime channel, and bridge messages between the browser and your server.

Installation

You can run it directly with npx (no install required):

npx delta0-sdk connect <token> -- <command>

Or install globally:

npm install -g delta0-sdk
delta0-sdk connect <token> -- <command>

Usage

delta0-sdk connect <token> [options] [-- <command> [args...]]

Arguments

Argument	Description
token	Base64url-encoded relay token from the delta0 web app

Options

Option	Description
--sse <url>	Connect to an MCP server via SSE transport
--http <url>	Connect to an MCP server via Streamable HTTP transport
-- <command> [args...]	Launch an MCP server as a child process via STDIO transport
-V, --version	Output the version number
-h, --help	Display help

Transport Modes

delta0-sdk supports all three MCP transport types. You must specify exactly one.

STDIO (most common)

Spawns the MCP server as a child process and communicates over stdin/stdout. Use -- to separate the server command from delta0-sdk arguments.

# Filesystem server
npx delta0-sdk connect <token> -- npx @modelcontextprotocol/server-filesystem /path/to/dir

# Python-based server
npx delta0-sdk connect <token> -- python -m my_mcp_server

# Any executable
npx delta0-sdk connect <token> -- ./my-server --port 0

SSE

Connects to an already-running MCP server that exposes an SSE endpoint.

npx delta0-sdk connect <token> --sse http://localhost:3000/sse

Streamable HTTP

Connects to an already-running MCP server that exposes a Streamable HTTP endpoint.

npx delta0-sdk connect <token> --http http://localhost:3000/mcp

Relay Token

The relay token is a base64url-encoded JSON object containing the following fields:

{
  "supabaseUrl": "https://xxx.supabase.co",
  "anonKey": "eyJ...",
  "userId": "user-uuid",
  "projectId": "project-uuid"
}

The token is generated by the delta0 Inspector web app. You should never need to construct it manually.

How It Works

1. Decode token — Extracts Supabase connection info and project identifiers from the relay token.
2. Subscribe to channel — Connects to the Supabase Realtime channel relay:{userId}:{projectId}.
3. Start local transport — Launches or connects to the local MCP server using the specified transport mode.
4. Bridge messages — Forwards messages transparently in both directions:
   • mcp:client events (from the browser) → sent to the local MCP server
   • Responses from the local MCP server → sent as mcp:server events to the browser
5. Health checks — Responds to mcp:control ping events with mcp:status connected status.
6. Graceful shutdown — On SIGINT/SIGTERM, notifies the browser with a disconnected status, closes the local transport, and removes the channel.

delta0-sdk is a transparent bridge — it does not parse, validate, or modify JSON-RPC messages. It simply passes them through.

Logs

All log output is written to stderr so it doesn't interfere with STDIO transport communication on stdout. Log lines are prefixed with [delta0-sdk].

[delta0-sdk] Project: proj-456
[delta0-sdk] User: user-123
[delta0-sdk] Transport: STDIO → npx @modelcontextprotocol/server-filesystem /tmp
[delta0-sdk] Channel subscribed: relay:user-123:proj-456
[delta0-sdk] Local transport started
[delta0-sdk] Relay active — bridging messages
[delta0-sdk] → local [#1] method=initialize
[delta0-sdk] ← local [#2] result id=0
[delta0-sdk] → local [#3] method=tools/list
[delta0-sdk] ← local [#4] result id=1

Programmatic Usage

You can also use delta0-sdk as a library:

import { startRelay } from "delta0-sdk";
import { decodeToken } from "delta0-sdk/token";

const token = decodeToken("eyJ...");

const shutdown = await startRelay({
  token,
  transport: {
    mode: "stdio",
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "/tmp"],
  },
});

// Later, to stop the relay:
await shutdown();

Development

git clone https://github.com/delta0-inc/delta0-sdk.git
cd delta0-sdk
npm install
npm run build    # Compile TypeScript to dist/
npm run dev      # Watch mode

Project Structure

src/
├── cli.ts           # CLI entry point (commander-based)
├── relay.ts         # Core bridge logic (Supabase Realtime ↔ local transport)
├── token.ts         # Token encoding/decoding with validation
└── transports.ts    # Local MCP transport factory (STDIO/SSE/HTTP)

License

MIT