qurl-mcp

# @layervai/qurl-mcp

[![npm version](https://img.shields.io/npm/v/@layervai/qurl-mcp.svg)](https://www.npmjs.com/package/@layervai/qurl-mcp)

> **⚠️ Renamed from `@layerv/qurl-mcp` in v0.4.0.** The old package is deprecated and will not receive further updates. If you're using `@layerv/qurl-mcp@0.3.x`, swap the scope in your MCP client config — same binary, same API key, no other changes.

> A qURL MCP Server that supports both local `stdio` mode and remote `HTTP` mode for creating, managing, resolving, and sharing secure access links.

## Overview

`qURL MCP` exposes qURL capabilities to MCP clients, GPTs, ChatGPT, and other remote integrations.

It currently supports:

- creating, reading, updating, and deleting qURLs
- resolving access tokens
- managing qURL tokens and sessions
- uploading text or file content and generating qURLs
- optionally serving LayerV public legal pages
- serving a configurable MP4 video playback page

## Private consumer access

Node.js 22.12 or later is required by the shared qURL SDK.

`publish_crid` creates a private URL resource with keys, invite_only,
email_capture, review, or contract access. `manage_crid_access` changes the
policy with its current version, sends invitations, lists grants, approves
or denies requests, and removes access. The tools return resource-scoped
receipts and omit invitation secrets and bearer links. Local apps use the
qURL CLI on the publisher machine.

For example, an assistant can turn “share this with ana@example.com, and
allow no requests” into an invite_only resource and an authorized invitation.
For email capture, the consumer must know that the publisher receives their
verified email. A verified email proves mailbox control, not legal identity.
Contract approval requires a trusted publisher backend entitlement receipt;
these tools do not verify payment. Do not report connection removal as
complete while session_cleanup is pending.

This feature requires the matching service and admission readers. Keep it
disabled until the publisher and consumer journeys pass. The package pins
the published SDK 3.0.0 and supports clean installation with dependency
scripts blocked. This release requires Node.js 22.12 or later; Node.js 20
is no longer supported.

## Runtime Modes

| Mode    | Purpose                         | Start Command        | Typical Use Case                                           |
| ------- | ------------------------------- | -------------------- | ---------------------------------------------------------- |
| `stdio` | Local subprocess MCP server     | `npm run start`      | Claude Desktop, Cursor, Codex, and other local MCP clients |
| `http`  | Authenticated remote MCP server | `npm run start:http` | Remote agent runtimes behind HTTPS                         |

## Feature Map

### qURL Management Tools

| Tool                      | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `create_qurl`             | Create a new qURL                                   |
| `resolve_qurl`            | Resolve an access token into a protected target URL |
| `list_qurls`              | List qURL resources                                 |
| `get_qurl`                | Fetch details for a single qURL                     |
| `delete_qurl`             | Delete a qURL                                       |
| `extend_qurl`             | Extend a link's expiration (needs `qurl:read` too)  |
| `update_qurl`             | Update qURL metadata or expiration                  |
| `mint_link`               | Mint a new access link for an existing resource     |
| `share_by_crid`           | Mint a temporary access link from a resource CRID   |
| `batch_create_qurls`      | Create multiple qURLs in one request                |
| `revoke_qurl_token`       | Revoke a specific token                             |
| `update_qurl_token`       | Update a specific token                             |
| `list_qurl_sessions`      | List active access sessions                         |
| `terminate_qurl_sessions` | Terminate one or all active sessions                |

`share_by_crid` recognizes a standalone `$<CRID>` value as an explicit request
to mint a temporary link for that CRID. The `$` is a user-facing marker and is
removed before the CRID is sent to the qURL API. A bare CRID remains supported.
This tool requires `qurl:resolve`. Its optional Go-duration `ttl` must resolve to
a positive whole number of seconds. The service clamps the requested lifetime.
Sharing makes one request with a 30-second timeout and does not automatically
retry. Repeating the tool call can mint another link.

Resource status filters accept `active`, `revoked`, or `active,revoked`.
A resource remains active or revoked even when its `expires_at` is in the past;
individual access tokens can expire. `expired` is not accepted by `list_qurls`,
even though response parsing tolerates legacy values. The snapshot retains
upstream's stale expiration prose; its active/revoked status enum is authoritative.

The qURL SDK reuses the same `Idempotency-Key` and request body when retrying
POST/PATCH requests after a network failure or HTTP 429. Mutating HTTP 5xx
responses are not automatically retried. Each new MCP tool invocation is a new
operation with a new key, so repeating `create_qurl`, `batch_create_qurls`, or
`mint_link` can mint additional tokens. MCP does not expose a caller-supplied key.

### Upload Tools

| Tool                    | Mode         | Description                                |
| ----------------------- | ------------ | ------------------------------------------ |
| `upload_file_qurl`      | `stdio`      | Upload a local file and mint a qURL        |
| `upload_file_data_qurl` | `stdio`/HTTP | Upload base64 file content and mint a qURL |
| `upload_text_qurl`      | `stdio`/HTTP | Upload text content and mint a qURL        |

`upload_file_qurl` is intentionally stdio-only. It can read any supported
PDF/image that the local MCP process user can access, so agents should invoke
it only for a path the user explicitly selected for sharing. Do not expose it
to untrusted prompts or autonomous agents: prompt injection could otherwise
select another readable PDF/image on the host. Run stdio under an OS account
whose filesystem access is limited to intended shareable content. HTTP mode
never registers this host-file tool.
The byte/text tools are also available in stdio so local clients can share
in-chat attachments without first materializing them at a known host path.
Connector upload and link minting are separate operations. The link comes from
the connector's `POST /api/mint_link/:resource_id` (in tunnel mode, a
per-recipient watermarked view), not from qURL `mint_link`, so uploaded files
cannot be re-linked with `mint_link`; run the upload tool again. Upload links
support `expires_in` (1m-30d, converted to an absolute expiry on the MCP host's
clock, so a host clock that is off shortens or lengthens the link; a link whose returned expiry
is already past by this host's clock is returned with `expires_at_already_past`), `one_time_use`, and `session_duration` (whole seconds, up to 24h); `access_policy` and
`max_sessions` must be omitted or null; non-null values are rejected before the upload. If the connector ever mints more
links than requested, the result reports how many extra in
`unexpected_extra_link_count` and any IDs it returned in
`unexpected_extra_qurl_ids` (at most 10); they may be live even when this host's clock suggests expiry, so tell the user. If minting
fails after upload, the connector currently has no delete endpoint; the server logs the orphaned
`resource_id` for operator cleanup and returns the mint failure. Upload links
cannot yet be revoked from this server: `delete_qurl` on the upload's
`resource_id` does not stop a connector-minted link (revocation needs the
connector's `/api/revoke_links`), so prefer short expiries for sensitive files.
Duration inputs accept whole days or weeks (`7d`, `1w`), or unsigned Go-unit
sequences (`1h30m`, `1.5h`). Mixed day/week sequences (`1d12h`), leading signs,
leading-dot fractions, and Greek mu (`μs`) are rejected; micro sign (`µs`) is accepted.
HTTP upload attempts remain bounded by the per-IP and per-credential MCP rate
limits; stdio operators should separately constrain autonomous retry loops.
Upload validation binds the declared media type to the filename plus format
start/end markers; it is not a malware scanner or full PDF/image decoder.
For polyglot resistance, a PDF's final `%%EOF` marker must be followed only by
ASCII whitespace; producer output with other trailing bytes is rejected even
if a permissive PDF reader would accept it. JPEG validation checks framing and
terminal markers rather than decoding image segments. The authenticated
connector must independently decode or otherwise fully validate content before
storage when semantic media validity matters. It must also preserve the
declared safe media type and serve downloads with `X-Content-Type-Options:
nosniff` rather than inferring an executable type.
There is intentionally no application-level path allowlist: symlinks and
time-of-check/time-of-use races make a lexical prefix check a misleading
security boundary. Use a dedicated OS account, container, or read-only mount
whose readable files are already limited to the intended sharing directory.
The final path component is opened with `O_NOFOLLOW`; intermediate directory
symlinks retain normal filesystem behavior under this trusted-local-user
boundary.

### MCP Resources

| URI            | Description                         |
| -------------- | ----------------------------------- |
| `qurl://links` | Current qURL list                   |
| `qurl://usage` | Current quota and usage information |

### MCP Prompts

| Prompt             | Description                       |
| ------------------ | --------------------------------- |
| `