LucidLink MCP Server

Connect AI agents (Claude Code, Codex, Cursor, and other MCP clients) to a LucidLink filespace - read, write, search, lock, manage users and audit files in natural language.

Prerequisites

• A LucidLink service-account token (sa_live:...) for a filespace you can safely test in. Your LucidLink workspace admin can mint one - see Service Accounts.
• Node.js 22+ on PATH - only for the admin tools (workspace, members, permissions). The file tools do not need Node.

You don't need Python set up in advance; uv brings its own.

Install

The client configs below launch the server with uvx, so the only thing to install is uv (it brings its own Python, no separate setup):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

Reload your PATH so uvx is found: open a new terminal (on macOS/Linux you can instead source $HOME/.local/bin/env in the current shell). If uv warns about PATH later, run uv tool update-shell. uvx lucidlink-mcp@latest fetches the package on first run and picks up new releases automatically on later launches, so there's no separate install or update step. Check it works:

uvx lucidlink-mcp@latest --version

Prefer a bare lucidlink-mcp command (to pin a version, or to keep uvx out of your config)? Install it with uv tool install lucidlink-mcp, or pip install lucidlink-mcp into a Python 3.11+ environment. Then use lucidlink-mcp wherever the configs below say uvx lucidlink-mcp@latest, and update it yourself with uv tool upgrade lucidlink-mcp (or pip install -U); a bare install doesn't auto-update.

Configure your token

uvx --from lucidlink-mcp@latest lucidlink-mcp-setup

Prompts for the token, validates it, and stores it in ~/.lucidlink/mcp-config.json (mode 0600), so no client config has to carry it. (Installed the bare command? Just run lucidlink-mcp-setup. Prefer not to use the setup tool at all? See Fallbacks below.)

That's the whole setup. If your account sees several filespaces, the agent lists them on first use and you tell it which to link, or pin a default with LUCIDLINK_FILESPACE (see Settings).

Register with your client

Claude Code - via the CLI:

claude mcp add lucidlink -s user -- uvx lucidlink-mcp@latest

...or in .mcp.json at the project root (shareable; Claude Code asks to approve it once):

{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp@latest"]
    }
  }
}

Add options as env vars - -e LUCIDLINK_MCP_TOOLSETS=admin (CLI) or an "env" object (JSON); see Settings below for the full list.

Codex - via the CLI:

codex mcp add lucidlink -- uvx lucidlink-mcp@latest

...or in ~/.codex/config.toml:

[mcp_servers.lucidlink]
command = "uvx"
args = ["lucidlink-mcp@latest"]

Add options as env vars - --env LUCIDLINK_MCP_TOOLSETS=admin (CLI) or a [mcp_servers.lucidlink.env] table (TOML); see Settings below. The token comes from ~/.lucidlink/mcp-config.json (via lucidlink-mcp-setup), so no LUCIDLINK_TOKEN is needed here.

Cursor - ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp@latest"]
    }
  }
}

Add an "env" object for options, e.g. "env": { "LUCIDLINK_MCP_TOOLSETS": "admin" }. If Cursor can't find uvx, give its absolute path (command -v uvx).

Settings

All optional except the token. Put them in the env block of your client's server entry.

Variable	Effect
LUCIDLINK_TOKEN	the token (or set it once via lucidlink-mcp-setup and omit this)
LUCIDLINK_FILESPACE	default filespace to link when several are visible
LUCIDLINK_ACCOUNT	default account name when several accounts are configured (see below)
LUCIDLINK_MCP_TOOLSETS	admin adds workspace-management tools; core trims to 16 essential file tools
LUCIDLINK_MCP_READ_ONLY	1 registers only read/search tools; nothing can write
LUCIDLINK_MCP_NODE	absolute path to a Node 22+ binary, if the admin tools can't find node

Agents can link SEVERAL filespaces at once (linking is additive; switching back is instant). Each linked filespace allocates a 1 GiB disk cache that stays until the server exits, and an account holds at most 4 links at once (maxLinkedFilespaces in ~/.lucidlink/mcp-config.json). To work across several service accounts, put named tokens in ~/.lucidlink/mcp-config.json instead of a single token:

{
  "accounts": { "prod": "sa_live:...", "staging": "sa_live:..." },
  "defaultAccount": "prod"
}

The agent just names a filespace: link_filespace resolves it across accounts and switches automatically (use_account(name) exists for switching accounts explicitly). A lone token is simply the single account named default, so existing setups keep working unchanged.

Try it

Ask your agent:

• "List my LucidLink filespaces", then "show me the files in /"
• "Create /mcp-test/hello.txt with a short note, then read it back"
• "Search the filespace for files named hello.txt" (finds the file you just made)

Link S3 objects and URLs (optional)

LucidLink Connect links existing content into the filespace without copying it; the agent reads it like any file, read-only. It needs filespace format 3.6 or newer with Connect enabled.

S3 objects come through an S3 data store. Its keys never reach the agent - put them in ~/.lucidlink/data-stores.json (mode 0600), keyed by store name:

{ "my-store": { "access_key": "AKIA...", "secret_key": "...",
                "bucket_name": "my-bucket", "region": "us-east-1" } }

Then ask the agent to register the store (register_data_store, kind s3) and link an object (link_external_file).

HTTP/HTTPS URLs link with link_external_url. On filespace format 3.8 and newer a URL link belongs to an HTTP-link data store, which needs no credentials (register_data_store, kind http_link); on 3.6 it links without one.

Enabling the audit trail (optional)

The agent can answer who changed which files, and when once the filespace's audit trail is on. It's off by default, and enabling it needs filespace-admin rights:

• On a machine with the desktop client connected, a filespace admin runs lucid config --global --set --Audit.FsEvents 1 (details).

---

Fallbacks & troubleshooting

Set the token without the setup tool - two equivalents:

• Write ~/.lucidlink/mcp-config.json yourself as { "token": "sa_live:..." } and chmod 600 it.
• Or put "env": { "LUCIDLINK_TOKEN": "sa_live:..." } in your client's server entry.

Several service accounts? Run lucidlink-mcp-setup --account NAME once per account, or hand-author the accounts object (see Settings); re-runs preserve existing named accounts either way.

Command not found, or client shows "disconnected"? The launcher (uvx, or lucidlink-mcp if you installed the bare command) isn't on the PATH your client sees, common with GUI clients that start from a minimal PATH. Put its absolute path in the config; command -v uvx (or command -v lucidlink-mcp) prints it. As a last resort, run the server module directly: python3 -m lucidlink_mcp.

Telemetry

The MCP server sends usage telemetry to LucidLink: one event per tool call and one per workspace connection. An event records the tool name, its outcome and duration, the kind of error if it failed, the filespace, service-account and workspace ids it concerns, the MCP client's name and version, the server and SDK versions, the operating system and its version, the CPU architecture, the Python version, whether the read-only toolset is on, and ids that correlate the events of one run. It never carries paths, filenames, tool arguments or file content. The lucidlink SDK the server runs on sends its own usage telemetry, described in its README on PyPI. LucidLink collects this data under the Developer Platform License Agreement (see "License and usage") and handles personal data under its privacy policy: https://www.lucidlink.com/privacy.

License and usage

This MCP server (the “MCP Server”) is proprietary to LucidLink Corp. and is part of the LucidLink Developer Platform. It is provided solely to enable you to install, run, and self-host the MCP Server, and to develop applications and integrations that interact with LucidLink services.

Use of this MCP Server is governed by the LucidLink Developer Platform License Agreement, available at https://developer.lucidlink.com/LucidLink%20Developer%20Platform%20License%20Agreement.pdf (the “Agreement”), or, if you or your organization have entered into a separate written agreement with LucidLink that governs your use of the Developer Platform, by that separate written agreement (in each case, the “Applicable Terms”). See the LICENSE file for details.

The MCP Server runs on the LucidLink Python SDK (the lucidlink package on PyPI), which it uses unmodified under the same Agreement; the SDK's own license notice ships with that package.

This MCP Server (including any associated example or sample code) is not licensed under an open‑source license. All rights are reserved by LucidLink except as expressly granted in the Applicable Terms. Third-party components bundled with the MCP Server are licensed under their own terms; see the NOTICE file.