Metadata-Version: 2.4
Name: lucidlink-mcp-cloudflared
Version: 0.2.0
Summary: One-command public URL for the LucidLink MCP server via a Cloudflare quick tunnel
Author: LucidLink
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://www.lucidlink.com
Keywords: mcp,lucidlink,cloudflared,tunnel,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lucidlink-mcp<0.3,>=0.2.2
Requires-Dist: httpx<1,>=0.27
Requires-Dist: starlette<2,>=0.37
Requires-Dist: uvicorn<1,>=0.31.1
Dynamic: license-file

# lucidlink-mcp-cloudflared

One command, one URL: serve the [LucidLink MCP](https://pypi.org/project/lucidlink-mcp/)
to **any MCP client that supports remote connectors** — claude.ai (web,
mobile, Cowork), Cursor, Codex, and friends — through a
[Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/).

```bash
uvx lucidlink-mcp-cloudflared
```

starts the **team gateway** and prints one connector URL
(`https://<random>.trycloudflare.com/mcp`). Add it once to your client
(claude.ai: Settings → Connectors); each person who connects enrolls with their
own service-account token and gets their own isolated backend, identity, and
audit trail. Ctrl+C kills server, tunnel, and URL together — nothing
persists anywhere. Details under [Team mode](#team-mode-one-url-per-member-auth).

For a personal, no-OAuth endpoint (the URL itself is the credential):

```bash
uvx lucidlink-mcp-cloudflared solo
```

prints `https://<random-words>.trycloudflare.com/<secret>/mcp`, paste-ready,
and self-tests it over the exact edge-and-back path a remote client will use.

## Why a separate package

The official `lucidlink-mcp` package deliberately never spawns a tunnel
vendor's binary or routes your traffic anywhere — its `--http` mode binds a
local port and leaves the pipe to you. This companion is the
explicitly-chosen convenience that adds the pipe. Installing it is the
opt-in.

## Prerequisites

- A LucidLink service-account token per person (a workspace admin mints
  them in the LucidLink admin app under Service Accounts). **No pre-setup
  needed**: in team mode each member pastes their token on the enrollment
  page when they click Connect; in `solo` mode, first run walks you
  through pasting and verifying yours — the same wizard as
  `lucidlink-mcp-setup`, saved to the same `~/.lucidlink/mcp-config.json`
  every LucidLink MCP client reads.
- `cloudflared` on PATH — **never downloaded for you**:
  - macOS: `brew install cloudflared`
  - Windows: `winget install --id Cloudflare.cloudflared`
  - Linux: [Cloudflare's downloads page](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)

## Flags

Bare invocation takes `team serve` flags: `--port`, `--write` (mutating
tools for every member that session), `--idle-timeout`, `--max-backends`,
`--public-url` (your own pipe instead of a quick tunnel).

`solo` flags:

- `--port N` — local port (default 8000; always binds loopback)
- `--write` — register mutating tools (**read-only by default**)
- `--path-secret SECRET` — bring your own secret path segment (one is always
  generated otherwise; a public quick-tunnel URL never runs without one)

## Team mode: one URL, per-member auth

The default command (`team serve` spelled out):

```bash
uvx lucidlink-mcp-cloudflared team serve
```

It prints **one connector URL** (`https://<host>/mcp`). Add it once as a
remote connector in your MCP client (claude.ai: Settings → Connectors —
on Team/Enterprise plans a workspace Owner does this; members then connect
individually). When a member connects,
their browser lands on the gateway's enrollment page and they paste **their
own** service-account token — verified with LucidLink, stored only on the
gateway box (0600). The client receives an opaque, revocable OAuth token
per member; SA tokens never pass through an admin, a URL, or a conversation.

Each member gets their **own backend process** under their own SA — own
permissions, own audit identity, own locks and rate limits — spawned lazily
on first request and reaped when idle (`--idle-timeout`, default 15 min;
`--max-backends` caps concurrent members, default 8; budget roughly one
client stack plus ~1 GB cache per *active* member).

Admin console:

```bash
uvx lucidlink-mcp-cloudflared team list                # who's enrolled
uvx lucidlink-mcp-cloudflared team remove maria        # revoke: kills all her tokens
uvx lucidlink-mcp-cloudflared team allow-write maria   # register mutating tools for her
uvx lucidlink-mcp-cloudflared team revoke-write maria  # back to read-only (the default)
```

Write grants apply when the member's backend next spawns — restart the
gateway (or wait for the idle reap) after changing one. For a sandbox
session where everyone should be able to write (demo filespace, kicking
the tires), skip the per-member ceremony: `team serve --write` registers
mutating tools for every member for that session only.

Caveat that matters: OAuth binds to the hostname, and a quick tunnel mints a
**new** hostname every restart — the whole team reconnects. Fine for a demo;
a real deployment runs `team serve --public-url https://mcp.yourco.example`
behind a named tunnel or reverse proxy.

## What to know before pasting the URL anywhere

- **The URL is a bearer credential.** Anyone who has it has the endpoint.
  Treat it like a password; it dies on Ctrl+C and a restart mints a new one.
- **The model reading files is the exposure.** Content the agent reads
  enters your conversation and your AI provider's infrastructure under
  *your* plan's data terms. The tunnel adds Cloudflare's edge as a TLS
  terminator in the path.
- **Quick tunnels are best-effort.** No SLA; a reconnect mints a new
  hostname (re-paste in your client). For anything persistent, run the official
  package behind your own pipe instead — see this package's
  `docs/REMOTE-HOSTING.md`.
